From 9e1581e4450691c87a89b77053488608c2d9b86d Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 19:25:06 -0500
Subject: [PATCH 01/30] docs: rt chat invite spec: rooms from the viewer,
 agents from herdr panes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../specs/2026-08-26-rt-chat-invite-design.md | 357 ++++++++++++++++++
 1 file changed, 357 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md

diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
new file mode 100644
index 00000000..bddc917c
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -0,0 +1,357 @@
+# rt chat invite: rooms from the viewer, agents from herdr panes
+
+Extends `2026-08-23-rt-chat-design.md` and `2026-08-24-rt-chat-presence-design.md`.
+Where this document disagrees with either, this one wins; the sections it
+revises are named under **What this changes in the base designs**.
+
+Mockups: https://claude.ai/code/artifact/93d55ea7-54c1-4866-9685-bdc3b605661b
+(three artboards: the New room form, the standalone PanePicker, entry points
+and the returned payload). Their generator lands in the chat repo's
+`design/build.py` with the viewer PR.
+
+## Problem
+
+Today a room is assembled by hand: Matt opens every herdr pane he wants in
+it, types the sign-in slash command, and pastes a brief into each one. The
+viewer can read rooms and post into them but cannot create one, cannot seed
+it before anyone arrives, and knows nothing about the panes on the desk. And
+an agent told "add you and the agent working on foo into a room so you can
+coordinate" has no way to find foo's pane or to get it into the room; it can
+only sign itself in and hope.
+
+Two facts of the shipped design shape the fix:
+
+- **Only the agent can make itself listening.** Sign-in plus arming `rt chat
+  tail` under `Monitor` happens inside the pane. Nothing outside a pane can
+  arm a tail, so "adding an agent" has to end with that pane running the
+  join itself.
+- **Joining hides history.** `chat:join` seeds the member's cursor at the
+  room's `MAX(id)` so a joiner is never woken by the past. A seed message
+  posted before an agent joins is therefore invisible to `rt chat read`,
+  `--since`, and the tail's catch-up. "All joiners will see it" needs a verb
+  that reaches behind the cursor.
+
+herdr is the thing that makes the rest trivial: it knows every pane, which
+ones run Claude, each pane's Claude Code session id (the same key the
+presence row is stored under), whether the agent is idle, working or blocked
+at a prompt, and it can type into a pane. The whole feature is gated on
+herdr; without it the new surfaces hide.
+
+## Decisions and rationale
+
+Ratified in brainstorming, 2026-08-26:
+
+1. **Adding a pane to a room types a slash command into it.** The invite
+   injects `/chat:join <room>` (plus an optional note) and the agent signs
+   in, joins, arms its tail and reads the seed itself. Rejected: a silent
+   server-side join on the agent's behalf. The daemon would allow it
+   (`chat:join` takes any handle) but the agent would be a member with no
+   tail, `idle` at best, and nothing would tell it why it is there.
+2. **The seed message is the brief.** One message, posted as the human when
+   the room is created, visible in the transcript to anyone who opens the
+   room later. A per-pane note is optional and rides the injected command.
+3. **The primitives live in rt** (`chat:panes`, `chat:invite`, `read --last`),
+   called by the viewer through rt-client and by agents through the CLI.
+   Rejected: the viewer's server talking to herdr on its own (agents would
+   then depend on the viewer being up, and the pane/presence join would be
+   done twice), and each caller driving herdr directly (two copies of the
+   injection quirks).
+4. **The seed reaches a joiner through `rt chat read <room> --last N`**, a
+   cursor-independent read over the existing non-mutating `chat:messages`
+   verb. Rejected: a `readFrom` parameter on join (daemon change that only
+   helps invited joins) and pasting the seed body into every pane (long
+   seeds duplicated N times).
+5. **The pane picker is a standalone component** that resolves with the
+   picked pane rows. The New room form and the room page are its first two
+   callers; it carries no invite semantics of its own, so focusing a pane
+   from the roster or launching something into a pane can reuse it.
+6. **The picker lists only panes running Claude Code.** Shell panes are
+   hidden; a Claude pane whose agent never signed in is listed as
+   `not signed in` and is invitable, because those are exactly the panes
+   the by-hand workflow was for.
+7. **A pane can be peeked.** When a session title is not enough to tell two
+   panes apart, a row expands to the last lines of that pane's screen
+   (herdr `pane.read`), fetched only for that row.
+8. **The picker is reachable from the New room form and from an existing
+   room's page bar.** Pulling a pane into `#build` later must not mean
+   recreating `#build`.
+9. **An agent recruiting another agent always confirms first**, through
+   `AskUserQuestion` forms: which pane, what room name, what seed. A wrong
+   invite derails someone else's turn, and the herdr doorbell hook already
+   rings on a form, so the confirmation is cheap for Matt.
+
+## The primitives (rt)
+
+### The gate
+
+`herdrAvailable()`: the socket at `HERDR_SOCKET_PATH`, else
+`~/.config/herdr/herdr.sock`, exists and answers `session.snapshot`. The
+daemon runs outside any pane, so the path is configured, never inherited.
+Both new verbs answer `{ ok: false, error: "herdr unavailable" }` when the
+gate fails; nothing else about their shape changes. The daemon speaks herdr's
+newline-delimited JSON directly over the socket, one connection per call,
+5s timeout per call. No shell-out.
+
+### `chat:panes`
+
+`rt chat panes [--json]`, rt-client `chatPanes()`. One row per herdr pane
+whose `agent === "claude"`, joined to presence:
+
+```ts
+interface ChatPane {
+  paneId: string;            // herdr pane_id, e.g. "w7A:pY"
+  workspace: string;         // herdr WorkspaceInfo.label
+  title?: string;            // terminal_title_stripped, the Claude session title
+  cwd?: string;              // foreground_cwd ?? cwd
+  repo?: string;             // repoLabel(deriveRepoIdentity(cwd)), as presence derives it
+  branch?: string;           // git, as presence derives it
+  agentStatus: "idle" | "working" | "blocked" | "done" | "unknown";
+  sessionId?: string;        // agent_session.value, the Claude Code session UUID
+  presence?: { handle: string; status: BuddyStatus; rooms: string[] };
+}
+```
+
+The join is by `sessionId` first (presence rows are keyed on it), then by
+`presence.pane === paneId` for a row whose session id herdr does not know.
+`presence` is absent for a pane whose agent never signed in. `rooms` is the
+handle's membership list (`listRooms`), so a caller can mark "already in
+#build" without a second call. Sort order for humans: listening, idle, deaf,
+not signed in; within a group, herdr's pane order.
+
+### `chat:pane-peek`
+
+`rt chat panes --peek <pane> [--lines 8]`, rt-client `chatPanePeek()`.
+Returns `{ paneId, lines: string[] }`, herdr `pane.read` of the visible
+screen, trailing blank lines dropped. Read on demand only; never as part of
+`chat:panes`.
+
+### `chat:invite`
+
+`rt chat invite <pane> --room <room> [--note <text>]`, rt-client
+`chatInvite()`. Types the join command into one pane and reports what
+happened; it never touches membership.
+
+- Text injected: `/chat:join <room>`, then, when a note is given, a second
+  line `note from <humanHandle>: <note>`. Nothing else; the brief is in the
+  room.
+- Delivery: herdr `agent.prompt` with `wait: { until: ["working"],
+  timeout_ms: 5000 }`. On a stall, one `Enter` keypress (the Claude TUI can
+  absorb the bundled Enter into the composer), then one more 5s wait.
+- Result: `{ paneId, delivered: "accepted" | "queued" | "refused", reason?:
+  string }`. `accepted`: the agent reached `working`. `queued`: the agent was
+  already `working`, herdr queued the text and no confirmation is possible.
+  `refused`: the pane is `blocked` (herdr will not inject into an approval
+  dialog), is not a Claude pane, or herdr is unavailable; `reason` says
+  which.
+- The pane's own session is refused with `reason: "that is this pane"` when
+  the caller runs inside herdr and `HERDR_PANE_ID` matches.
+
+### `rt chat read <room> --last N`
+
+Shows the newest N messages of a room regardless of the caller's cursor
+(`chat:messages`, the verb the viewer already reads with), then advances the
+cursor exactly as a plain `read` does. `--last` and `--since` are mutually
+exclusive. Documented in `rt:chat` as the way to catch up on a room you just
+joined or were pointed at.
+
+## Data flow
+
+**Create a room from the viewer.** `POST /api/chat/rooms { room, seed?,
+wakeOn? }`: the server joins as the human (which creates the room, stamping
+`wakeOn` as the room default when given), posts the seed if one was written,
+and returns `{ room, seedId? }`. Then `POST /api/chat/invite { room, panes:
+[{ paneId, note? }] }` runs `chatInvite` per pane, sequentially, and returns
+every result. The client navigates to `/r/<room>` and shows the results on
+the transcript's edge line. Members appear as each pane signs in: the roster
+polls every 5s and refetches on wake frames, and the join skill's first post
+is a wake frame.
+
+**Add agents to an existing room.** The room page opens the picker directly
+with `disable` marking members and blocked panes, then calls the invite
+route with what comes back. Invitees are pointed at the room's newest
+messages by `read --last`; the page's hint says to post a fresh brief first
+if the room needs one.
+
+**Recruit from a pane.** The agent runs `rt chat panes --json`, matches the
+request against title, repo, branch, cwd and handle, confirms through a
+form, signs itself in with `--room`, posts the seed as itself, and runs
+`rt chat invite` per chosen pane. See Skills.
+
+## Web viewer
+
+### Routes
+
+| Route | Does |
+| --- | --- |
+| `GET /api/herdr/panes` | `chatPanes()` as `{ available, panes }`. herdr unavailable is `available: false` with 200, not a 502, so the UI hides both entry points instead of erroring. |
+| `GET /api/herdr/panes/:id/peek?lines=8` | `chatPanePeek()` as `{ lines }`. |
+| `POST /api/chat/rooms` | `{ room, seed?, wakeOn? }`; validates the room name against rt's charset (400); joins as the human, posts the seed; returns `{ room, seedId? }`. |
+| `POST /api/chat/invite` | `{ room, panes: [{ paneId, note? }] }`; one `chatInvite` per pane, sequential; returns `{ results: InviteResult[] }` with 200 even when some refused. |
+
+All under `src/server/herdr.ts` and additions to `src/server/chat.ts`,
+mounted like `chat`; fixtures for every route so `CHAT_FIXTURES=1` shows the
+whole flow.
+
+### PanePicker (standalone)
+
+```ts
+// src/ui/PanePicker/
+interface PickPanesOptions {
+  context?: string;                              // "to invite to #build", shown in the header
+  multiple?: boolean;                            // default true
+  disable?: (pane: ChatPane) => string | null;   // reason renders inline; null = selectable
+  preselected?: string[];                        // paneIds
+}
+const pickPanes = usePanePicker();               // (opts) => Promise<ChatPane[] | null>
+```
+
+Owns fetching `/api/herdr/panes`, the filter (handle, workspace, title,
+repo, path), the sort, the per-row peek (fetched when the eye opens), and
+selection. Resolves with the picked `ChatPane` rows verbatim, `null` on
+cancel. Carries no invite semantics: which rows are disabled and why is the
+caller's `disable`.
+
+Row anatomy (see the artboards): a 16px checkbox; the 8px status dot and
+handle, or a hollow dot and `not signed in`; the workspace, plus the session
+title when it differs from the handle; the caller's reason or the agent
+state on the right (`working · queues until its turn ends`); a 22px eye; a
+second line `repo · branch` with room tags; the path, head-truncated with an
+LTR-isolated inner run so short paths keep their order; the peek block inside
+the row when open. Rows use the `.opt` wash when selected and 0.55 opacity
+when disabled.
+
+### New room form
+
+Opened by a 24px `+` beside the count in the rooms rail header. Fields:
+room name (with the `#` prefix and the charset hint), seed (a textarea, the
+markdown subset hint, "posted as matt · every invitee is told to read it
+first"), wake mode (`mention` default, `all` explained as a war room), and
+an Agents section listing picked panes, each with an optional note and a
+remove control, with a `pick panes` button that launches the picker with
+`context` and `disable` set for inviting. Footer: `Create without inviting`
+and `Create #<room> · invite N`. Submit order is create, seed, invites, then
+close and navigate.
+
+### Room page
+
+`add agents` beside `mark read` in the page bar launches the picker directly
+and invites the result. After either flow, the transcript's edge line reads
+`invited 2 · assured pane accepted · fred queued (working) · members appear
+as they sign in` until the next room change.
+
+### Phone
+
+The form and the picker become full-height drawers with 44px controls, the
+existing `Drawer` pattern. Not drawn in this pass.
+
+### Conformance
+
+The three artboards join `design/build.py` as generators; `ANATOMY.md`
+gains a "Pane picker" and "New room" section; `audit.mjs` gets `TARGETS` for
+the modal shell, the pane row, the checkbox, the peek block and both entry
+points. The task is not done until the audit passes against the fixtures
+server. CONFORMANCE.md's "focusing a herdr pane from a member row" stays not
+built; the picker is the component that will do it.
+
+## Skills
+
+### `/chat:join <room>` (chat plugin, beside `sign-in`)
+
+The text an invite types into a pane, so it must work cold in any pane,
+signed in or not:
+
+1. Gate: `rt chat rooms --json`; daemon down means say so and stop.
+2. `rt chat sign-in --room <room>` (adds the room on an already-signed-in
+   session; the handle is kept).
+3. Arm the tail with `Monitor` if it is not running, by the session-start
+   hook's own rule.
+4. `rt chat read <room> --last 10`: the seed and anything since.
+5. Post one line to the room saying what it understood and what it is
+   taking, so the viewer shows arrival.
+6. Act on the seed plus any `note from <human>:` line that arrived with the
+   command. One narration line in the pane, per `rt:chat`.
+
+### Recruiting (new section in `rt:chat`)
+
+The skill's trigger line gains "put you and another agent in a room". For
+"add you and the agent working on foo into a room so you can coordinate":
+
+1. `rt chat panes --json`. Unavailable: say this needs herdr, stop.
+2. Match foo against title, repo, branch, cwd and handle. Exclude this
+   pane and panes already in the target room.
+3. **Always a form.** One `AskUserQuestion` carrying the candidate panes as
+   options (title · repo · status; multi-select), the proposed room name
+   (a slug from the topic), and the seed draft (post as drafted, or
+   rewrite). No pane is touched before the form returns.
+4. `rt chat sign-in --room <room>`, post the seed as itself, then
+   `rt chat invite <pane> --room <room> [--note ...]` per chosen pane,
+   sequentially.
+5. Report one line per pane (`accepted`, `queued, working`, `refused: at a
+   prompt`) and the room link. A refused pane is reported, never retried
+   blind.
+
+## Failure modes
+
+| Situation | What happens |
+| --- | --- |
+| rt daemon down | The existing banner; the `+` and `add agents` disable like the composer. |
+| herdr socket missing or not answering | `chat:panes` and `chat:invite` return `herdr unavailable`; the viewer hides both entry points; the recruiting flow says it needs herdr and stops. |
+| Target pane blocked at a prompt | `refused: at a prompt`. The picker already disables it with that reason; a race between listing and inviting surfaces on the edge line. Matt answers the prompt and re-invites. |
+| Target agent working | `queued`. The text lands when its turn ends; nothing polls. |
+| Enter absorbed by the composer | One nudge, one more wait; still not `working` means `queued`, reported as such. |
+| Pane already in the room | Disabled in the picker; the recruiting flow skips it and says so. |
+| Seed post fails after the room was created | The room exists with no seed; the form reports the failure and keeps the draft, the same rule the composer follows. |
+| Invite fails part-way through a list | Every result is returned; the edge line shows each. Nothing is rolled back; a join is idempotent so re-inviting is safe. |
+| Short path in the picker | The LTR-isolated run keeps segment order; long paths still head-truncate. (Check `Roster.tsx`'s `.path` for the same bidi reorder on short paths while in there.) |
+
+## Testing
+
+- repo-tools: the herdr NDJSON client against a fake unix socket
+  (`Bun.listen`): pane/presence join by session id, the pane-id fallback,
+  `blocked` refused, stalled then nudged then accepted, timeout. `read
+  --last` at the CLI, cursor advancing, exclusive with `--since`. rt-client
+  exports and types. `lib/herdr-agent.ts` moves from the removed
+  `herdr wait` to `herdr agent wait` (0.8.0), with its test updated.
+- chat: route tests with rt-client mocked as `chat.test.ts` does, including
+  `available: false` and partial invite results. `PanePicker`: filter, sort,
+  caller `disable` reasons, peek fetched only on open, resolve versus cancel,
+  `multiple: false`. `NewRoomModal`: submit order, name validation, draft
+  kept on failure, result line. Fixtures for every route. `audit.mjs`
+  targets for the new components, passing against `CHAT_FIXTURES=1`.
+- skills: `/chat:join` and the recruiting flow each get a real run in a
+  pane before they are called done.
+
+## Delivery order
+
+1. repo-tools: the herdr client and gate, `chat:panes`, `chat:pane-peek`,
+   `chat:invite`, `read --last`, rt-client wrappers and types, the verb
+   table and the recruiting section in `rt:chat`, the `herdr wait` fix.
+   Publish rt-client.
+2. chat: routes and fixtures, `PanePicker`, `NewRoomModal`, the two entry
+   points, the edge line, artboards and audit. Starts against fixtures; the
+   final wiring waits on rt-client.
+3. mattstack-marketplace: the `chat:join` skill.
+
+## Out of scope
+
+- A membership-change event from `chat:join`. Polling plus the join skill's
+  first post covers arrival; a `chat/<room>/member` frame is a one-line
+  follow-up if it lags.
+- Focusing a herdr pane from the roster, DMing whoever is in a pane, or
+  launching an agent into a new pane: future picker callers.
+- Remote or multi-session herdr (`HERDR_SESSION`); only the default socket.
+- Per-pane account or model: herdr does not expose them.
+- A standalone `rt chat create` verb; join-creates stands.
+
+## What this changes in the base designs
+
+- `2026-08-23-rt-chat-design.md`, entry points: "by launcher" gains the
+  viewer and the recruiting flow as launchers, both through `chat:invite`.
+- `2026-08-23-rt-chat-design.md`, reading: `read` gains `--last N`, a
+  cursor-independent read that still advances the cursor.
+- `2026-08-24-rt-chat-presence-design.md`, web viewer: the viewer gains the
+  `/api/herdr/*` routes and two `POST` routes that create a room and invite
+  panes; the "no route addresses a pane by id" note in the chat repo's
+  CONFORMANCE.md is now false for the picker and stays true for the roster.
+- `skills/rt-chat/SKILL.md`: two new verbs in the table (`panes`, `invite`),
+  the `--last` flag on `read`, and the recruiting section.

From 052079b1c75ce8ac61beb31cddd3dc1cc1dde8a7 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 19:30:27 -0500
Subject: [PATCH 02/30] docs: invite spec: rt pane group, spawning a pane from
 the picker

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../specs/2026-08-26-rt-chat-invite-design.md | 159 +++++++++++++-----
 1 file changed, 121 insertions(+), 38 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
index bddc917c..3321561d 100644
--- a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -5,9 +5,9 @@ Where this document disagrees with either, this one wins; the sections it
 revises are named under **What this changes in the base designs**.
 
 Mockups: https://claude.ai/code/artifact/93d55ea7-54c1-4866-9685-bdc3b605661b
-(three artboards: the New room form, the standalone PanePicker, entry points
-and the returned payload). Their generator lands in the chat repo's
-`design/build.py` with the viewer PR.
+(four artboards: the New room form, the standalone PanePicker, the New pane
+form inside it, entry points and the returned payload). Their generator lands
+in the chat repo's `design/build.py` with the viewer PR.
 
 ## Problem
 
@@ -50,7 +50,7 @@ Ratified in brainstorming, 2026-08-26:
 2. **The seed message is the brief.** One message, posted as the human when
    the room is created, visible in the transcript to anyone who opens the
    room later. A per-pane note is optional and rides the injected command.
-3. **The primitives live in rt** (`chat:panes`, `chat:invite`, `read --last`),
+3. **The primitives live in rt** (`pane:list`, `chat:invite`, `read --last`),
    called by the viewer through rt-client and by agents through the CLI.
    Rejected: the viewer's server talking to herdr on its own (agents would
    then depend on the viewer being up, and the pane/presence join would be
@@ -79,6 +79,14 @@ Ratified in brainstorming, 2026-08-26:
    `AskUserQuestion` forms: which pane, what room name, what seed. A wrong
    invite derails someone else's turn, and the herdr doorbell hook already
    rings on a form, so the confirmation is cheap for Matt.
+10. **The picker can start a pane.** A `new pane` form (directory, cswap
+    account, model, effort, optional opening prompt) runs the launch
+    sequence `remote-agent.sh` and shepherdr's `spawn-agent.sh` already do
+    by hand, and the new pane joins the list as `starting` until Claude is
+    idle. That is what lets a whole fleet be assembled from the chat instead
+    of one terminal at a time. The verbs live under `rt pane` (list, peek,
+    spawn), since they are herdr concerns rt already has helpers for;
+    `invite` stays under `rt chat` because it is about a room.
 
 ## The primitives (rt)
 
@@ -87,14 +95,15 @@ Ratified in brainstorming, 2026-08-26:
 `herdrAvailable()`: the socket at `HERDR_SOCKET_PATH`, else
 `~/.config/herdr/herdr.sock`, exists and answers `session.snapshot`. The
 daemon runs outside any pane, so the path is configured, never inherited.
-Both new verbs answer `{ ok: false, error: "herdr unavailable" }` when the
-gate fails; nothing else about their shape changes. The daemon speaks herdr's
-newline-delimited JSON directly over the socket, one connection per call,
-5s timeout per call. No shell-out.
+Every `pane:*` verb and `chat:invite` answer `{ ok: false, error: "herdr
+unavailable" }` when the gate fails; nothing else about their shape changes.
+The daemon speaks herdr's newline-delimited JSON directly over the socket,
+one connection per call, 5s timeout per call. No shell-out to `herdr`; the
+one shell-out in this feature is `cswap list` for the account roster.
 
-### `chat:panes`
+### `pane:list`
 
-`rt chat panes [--json]`, rt-client `chatPanes()`. One row per herdr pane
+`rt pane list [--json]`, rt-client `paneList()`. One row per herdr pane
 whose `agent === "claude"`, joined to presence:
 
 ```ts
@@ -118,12 +127,43 @@ handle's membership list (`listRooms`), so a caller can mark "already in
 #build" without a second call. Sort order for humans: listening, idle, deaf,
 not signed in; within a group, herdr's pane order.
 
-### `chat:pane-peek`
-
-`rt chat panes --peek <pane> [--lines 8]`, rt-client `chatPanePeek()`.
-Returns `{ paneId, lines: string[] }`, herdr `pane.read` of the visible
-screen, trailing blank lines dropped. Read on demand only; never as part of
-`chat:panes`.
+### `pane:peek`
+
+`rt pane peek <pane> [--lines 8]`, rt-client `panePeek()`. Returns
+`{ paneId, lines: string[] }`, herdr `pane.read` of the visible screen,
+trailing blank lines dropped. Read on demand only; never as part of
+`pane:list`.
+
+### `pane:spawn`
+
+`rt pane spawn --cwd <path> [--account <cswap>] [--model <m>] [--effort <e>]
+[--prompt <text>] [--workspace <label>]`, rt-client `paneSpawn()`. Starts
+Claude in a new herdr tab and returns it as a `ChatPane` once it is usable.
+
+1. Workspace: `--workspace`, else the `chat.herdrWorkspace` setting
+   (default `chat`), registered through the settings registry. Create-or-
+   reuse by label, mr-board's pattern: `workspace.list`, match the label,
+   else `workspace.create` with `--no-focus` semantics.
+2. `tab.create` in that workspace with the directory's basename as the
+   label, `--no-focus`; the tab's `root_pane` is the pane.
+3. `pane.send_input` of `cd <cwd> && <launch>` plus Enter, where launch is
+   `cswap run <account> --share-history -- claude [--model m] [--effort e]`
+   when an account is given and plain `claude [...]` otherwise. `--account`
+   accepts a cswap slot number, email or alias, validated against
+   `cswap list` (400-class error when unknown).
+4. Poll `agent.get` until herdr registers the agent (the 0.3s to 0.6s lag
+   shepherdr documents), then `agent.wait` until `idle`, `done` or
+   `blocked`, 60s. `blocked` with "trust" on the visible screen is the
+   trust dialog: send Enter and wait again.
+5. If `--prompt` was given, `agent.prompt` it and wait for `working`.
+6. Return the pane as `pane:list` would list it (`presence` absent,
+   `agentStatus` as observed) plus `ready: boolean`. A pane that never
+   reached idle within the budget is still returned, `ready: false`, with
+   the pane id, so nothing is orphaned silently.
+
+The account roster for callers: `rt pane accounts [--json]` parses
+`cswap list` into `{ slot, email, alias?, headroom? }` rows. No cswap means
+an empty list and the account field hidden.
 
 ### `chat:invite`
 
@@ -172,19 +212,30 @@ route with what comes back. Invitees are pointed at the room's newest
 messages by `read --last`; the page's hint says to post a fresh brief first
 if the room needs one.
 
-**Recruit from a pane.** The agent runs `rt chat panes --json`, matches the
+**Recruit from a pane.** The agent runs `rt pane list --json`, matches the
 request against title, repo, branch, cwd and handle, confirms through a
 form, signs itself in with `--room`, posts the seed as itself, and runs
 `rt chat invite` per chosen pane. See Skills.
 
+**Spawn from the picker.** `POST /api/panes { cwd, account?, model?,
+effort?, prompt?, workspace? }` runs `paneSpawn` and answers with the
+returned `ChatPane` when it is ready (the request stays open for up to the
+60s budget; the picker shows the row as `starting` meanwhile and swaps in
+the answer). A `ready: false` answer stays listed with its state so Matt can
+peek at what happened. Once idle the row is an ordinary pane: selectable,
+invitable, `not signed in` until it joins.
+
 ## Web viewer
 
 ### Routes
 
 | Route | Does |
 | --- | --- |
-| `GET /api/herdr/panes` | `chatPanes()` as `{ available, panes }`. herdr unavailable is `available: false` with 200, not a 502, so the UI hides both entry points instead of erroring. |
-| `GET /api/herdr/panes/:id/peek?lines=8` | `chatPanePeek()` as `{ lines }`. |
+| `GET /api/panes` | `paneList()` as `{ available, panes }`. herdr unavailable is `available: false` with 200, not a 502, so the UI hides both entry points instead of erroring. |
+| `GET /api/panes/:id/peek?lines=8` | `panePeek()` as `{ lines }`. |
+| `GET /api/panes/accounts` | `paneAccounts()` as `{ accounts }`; empty without cswap. |
+| `POST /api/panes` | `{ cwd, account?, model?, effort?, prompt?, workspace? }`; `paneSpawn()`; answers `{ pane, ready }` when the pane is usable or the budget is spent; 400 on a missing cwd or unknown account. |
+| `GET /api/panes/directories?q=` | suggestions for the directory field: rt's repos and their worktrees (`repos list`, `worktree list`), filtered by `q`. |
 | `POST /api/chat/rooms` | `{ room, seed?, wakeOn? }`; validates the room name against rt's charset (400); joins as the human, posts the seed; returns `{ room, seedId? }`. |
 | `POST /api/chat/invite` | `{ room, panes: [{ paneId, note? }] }`; one `chatInvite` per pane, sequential; returns `{ results: InviteResult[] }` with 200 even when some refused. |
 
@@ -201,15 +252,27 @@ interface PickPanesOptions {
   multiple?: boolean;                            // default true
   disable?: (pane: ChatPane) => string | null;   // reason renders inline; null = selectable
   preselected?: string[];                        // paneIds
+  allowCreate?: boolean;                         // shows the `new pane` action; default false
 }
 const pickPanes = usePanePicker();               // (opts) => Promise<ChatPane[] | null>
 ```
 
-Owns fetching `/api/herdr/panes`, the filter (handle, workspace, title,
-repo, path), the sort, the per-row peek (fetched when the eye opens), and
-selection. Resolves with the picked `ChatPane` rows verbatim, `null` on
-cancel. Carries no invite semantics: which rows are disabled and why is the
-caller's `disable`.
+Owns fetching `/api/panes`, the filter (handle, workspace, title, repo,
+path), the sort, the per-row peek (fetched when the eye opens), selection,
+and, with `allowCreate`, the New pane form. Resolves with the picked
+`ChatPane` rows verbatim, `null` on cancel. Carries no invite semantics:
+which rows are disabled and why is the caller's `disable`.
+
+**New pane form** (a second view inside the picker, back arrow to the
+list): directory (a path input with suggestions from `/api/panes/
+directories`, any path accepted), account (from `/api/panes/accounts`,
+headroom beside each, hidden when the list is empty), model (defaults to
+the newest Claude), effort (optional), workspace (from `chat.herdrWorkspace`,
+editable), opening prompt (optional). `Start pane` posts to `/api/panes`,
+returns to the list with the new row shown as `starting · selectable when
+idle`, and preselects it when the answer comes back `ready`. A `ready:
+false` answer keeps the row, unselectable, with its observed state so the
+eye can show what the pane is doing.
 
 Row anatomy (see the artboards): a 16px checkbox; the 8px status dot and
 handle, or a hollow dot and `not signed in`; the workspace, plus the session
@@ -276,7 +339,7 @@ signed in or not:
 The skill's trigger line gains "put you and another agent in a room". For
 "add you and the agent working on foo into a room so you can coordinate":
 
-1. `rt chat panes --json`. Unavailable: say this needs herdr, stop.
+1. `rt pane list --json`. Unavailable: say this needs herdr, stop.
 2. Match foo against title, repo, branch, cwd and handle. Exclude this
    pane and panes already in the target room.
 3. **Always a form.** One `AskUserQuestion` carrying the candidate panes as
@@ -295,7 +358,7 @@ The skill's trigger line gains "put you and another agent in a room". For
 | Situation | What happens |
 | --- | --- |
 | rt daemon down | The existing banner; the `+` and `add agents` disable like the composer. |
-| herdr socket missing or not answering | `chat:panes` and `chat:invite` return `herdr unavailable`; the viewer hides both entry points; the recruiting flow says it needs herdr and stops. |
+| herdr socket missing or not answering | every `pane:*` verb and `chat:invite` return `herdr unavailable`; the viewer hides both entry points; the recruiting flow says it needs herdr and stops. |
 | Target pane blocked at a prompt | `refused: at a prompt`. The picker already disables it with that reason; a race between listing and inviting surfaces on the edge line. Matt answers the prompt and re-invites. |
 | Target agent working | `queued`. The text lands when its turn ends; nothing polls. |
 | Enter absorbed by the composer | One nudge, one more wait; still not `working` means `queued`, reported as such. |
@@ -303,19 +366,32 @@ The skill's trigger line gains "put you and another agent in a room". For
 | Seed post fails after the room was created | The room exists with no seed; the form reports the failure and keeps the draft, the same rule the composer follows. |
 | Invite fails part-way through a list | Every result is returned; the edge line shows each. Nothing is rolled back; a join is idempotent so re-inviting is safe. |
 | Short path in the picker | The LTR-isolated run keeps segment order; long paths still head-truncate. (Check `Roster.tsx`'s `.path` for the same bidi reorder on short paths while in there.) |
+| Spawn: workspace or tab creation fails | `pane:spawn` errors before anything runs; the form shows the herdr error and keeps its values. |
+| Spawn: Claude never registers or never reaches idle within 60s | The pane is returned with `ready: false` and its observed state; it stays open in herdr and listed in the picker, unselectable, peekable. Nothing is closed on rt's behalf. |
+| Spawn: trust dialog | `blocked` with "trust" on screen is answered with Enter once; any other `blocked` is returned as-is. |
+| Spawn: unknown cswap account | Refused before launch (`400`); the account field lists what `cswap list` knows. |
+| Spawn: an opening prompt on a pane that only reached `blocked` | Not sent; reported in `ready: false`. |
 
 ## Testing
 
 - repo-tools: the herdr NDJSON client against a fake unix socket
   (`Bun.listen`): pane/presence join by session id, the pane-id fallback,
-  `blocked` refused, stalled then nudged then accepted, timeout. `read
-  --last` at the CLI, cursor advancing, exclusive with `--since`. rt-client
-  exports and types. `lib/herdr-agent.ts` moves from the removed
-  `herdr wait` to `herdr agent wait` (0.8.0), with its test updated.
+  `blocked` refused, stalled then nudged then accepted, timeout. The spawn
+  sequence against the same fake with scripted status transitions:
+  registration lag, trust dialog answered once, idle within budget, budget
+  exhausted returning `ready: false`, unknown account refused before any
+  socket call. The `cswap list` parser on captured output, including the
+  no-cswap case. `read --last` at the CLI, cursor advancing, exclusive with
+  `--since`. rt-client exports and types. `lib/herdr-agent.ts` moves from
+  the removed `herdr wait` to `herdr agent wait` (0.8.0), with its test
+  updated.
 - chat: route tests with rt-client mocked as `chat.test.ts` does, including
   `available: false` and partial invite results. `PanePicker`: filter, sort,
   caller `disable` reasons, peek fetched only on open, resolve versus cancel,
-  `multiple: false`. `NewRoomModal`: submit order, name validation, draft
+  `multiple: false`, the `new pane` action hidden without `allowCreate`, the
+  form's field visibility with and without accounts, the `starting` row
+  swapping in the spawn answer and preselecting on `ready`, a `ready: false`
+  row staying unselectable. `NewRoomModal`: submit order, name validation, draft
   kept on failure, result line. Fixtures for every route. `audit.mjs`
   targets for the new components, passing against `CHAT_FIXTURES=1`.
 - skills: `/chat:join` and the recruiting flow each get a real run in a
@@ -323,8 +399,9 @@ The skill's trigger line gains "put you and another agent in a room". For
 
 ## Delivery order
 
-1. repo-tools: the herdr client and gate, `chat:panes`, `chat:pane-peek`,
-   `chat:invite`, `read --last`, rt-client wrappers and types, the verb
+1. repo-tools: the herdr client and gate, `pane:list`, `pane:peek`,
+   `pane:spawn`, `pane:accounts`, `chat:invite`, `read --last`, the
+   `chat.herdrWorkspace` setting, rt-client wrappers and types, the verb
    table and the recruiting section in `rt:chat`, the `herdr wait` fix.
    Publish rt-client.
 2. chat: routes and fixtures, `PanePicker`, `NewRoomModal`, the two entry
@@ -337,8 +414,11 @@ The skill's trigger line gains "put you and another agent in a room". For
 - A membership-change event from `chat:join`. Polling plus the join skill's
   first post covers arrival; a `chat/<room>/member` frame is a one-line
   follow-up if it lags.
-- Focusing a herdr pane from the roster, DMing whoever is in a pane, or
-  launching an agent into a new pane: future picker callers.
+- Focusing a herdr pane from the roster and DMing whoever is in a pane:
+  future picker callers.
+- Provisioning a worktree from the New pane form; the directory must exist
+  (`rt worktree provision` stays a CLI step).
+- Closing or restarting a spawned pane from the viewer.
 - Remote or multi-session herdr (`HERDR_SESSION`); only the default socket.
 - Per-pane account or model: herdr does not expose them.
 - A standalone `rt chat create` verb; join-creates stands.
@@ -350,8 +430,11 @@ The skill's trigger line gains "put you and another agent in a room". For
 - `2026-08-23-rt-chat-design.md`, reading: `read` gains `--last N`, a
   cursor-independent read that still advances the cursor.
 - `2026-08-24-rt-chat-presence-design.md`, web viewer: the viewer gains the
-  `/api/herdr/*` routes and two `POST` routes that create a room and invite
+  `/api/panes*` routes and two `POST` routes that create a room and invite
   panes; the "no route addresses a pane by id" note in the chat repo's
   CONFORMANCE.md is now false for the picker and stays true for the roster.
-- `skills/rt-chat/SKILL.md`: two new verbs in the table (`panes`, `invite`),
-  the `--last` flag on `read`, and the recruiting section.
+- `skills/rt-chat/SKILL.md`: `rt chat invite` in the verb table, the
+  `--last` flag on `read`, a pointer to the new `rt pane` group (`list`,
+  `peek`, `spawn`, `accounts`), and the recruiting section.
+- `lib/herdr-agent.ts`: the spawn sequence becomes the shared
+  implementation `pane:spawn` uses; its callers keep their interface.

From 873a02c924613dd778d354133a1026a52f76ac08 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 19:40:31 -0500
Subject: [PATCH 03/30] docs: invite spec: review round 1 fixes (note
 attribution, timeouts, async spawns, who refetch, pane:directories)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../specs/2026-08-26-rt-chat-invite-design.md | 153 ++++++++++++------
 1 file changed, 102 insertions(+), 51 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
index 3321561d..9247278a 100644
--- a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -98,8 +98,15 @@ daemon runs outside any pane, so the path is configured, never inherited.
 Every `pane:*` verb and `chat:invite` answer `{ ok: false, error: "herdr
 unavailable" }` when the gate fails; nothing else about their shape changes.
 The daemon speaks herdr's newline-delimited JSON directly over the socket,
-one connection per call, 5s timeout per call. No shell-out to `herdr`; the
-one shell-out in this feature is `cswap list` for the account roster.
+one connection per call, 5s timeout per call. No shell-out to `herdr`. The
+two process spawns in this feature (`cswap list` for the account roster,
+`git` for an unsigned pane's branch) are async `Bun.spawn`s; the base
+design's rule that nothing sync-execs on the daemon thread (MAT-222) holds.
+
+Request timeouts: rt-client's default is 15s. `paneSpawn()` passes
+`timeoutMs: 90_000` and `chatInvite()` `timeoutMs: 20_000`, and the viewer's
+own `fetch` for those routes sets no shorter limit; the daemon's socket idle
+timeout (255s) already covers both.
 
 ### `pane:list`
 
@@ -112,8 +119,8 @@ interface ChatPane {
   workspace: string;         // herdr WorkspaceInfo.label
   title?: string;            // terminal_title_stripped, the Claude session title
   cwd?: string;              // foreground_cwd ?? cwd
-  repo?: string;             // repoLabel(deriveRepoIdentity(cwd)), as presence derives it
-  branch?: string;           // git, as presence derives it
+  repo?: string;             // the presence row's; else the daemon's repo index for cwd (no git)
+  branch?: string;           // the presence row's; else one async `git` spawn for cwd
   agentStatus: "idle" | "working" | "blocked" | "done" | "unknown";
   sessionId?: string;        // agent_session.value, the Claude Code session UUID
   presence?: { handle: string; status: BuddyStatus; rooms: string[] };
@@ -162,8 +169,19 @@ Claude in a new herdr tab and returns it as a `ChatPane` once it is usable.
    the pane id, so nothing is orphaned silently.
 
 The account roster for callers: `rt pane accounts [--json]` parses
-`cswap list` into `{ slot, email, alias?, headroom? }` rows. No cswap means
-an empty list and the account field hidden.
+`cswap list` (async spawn) into `{ slot, email, alias?, headroom? }` rows.
+No cswap means an empty list and the account field hidden.
+
+### `pane:directories`
+
+`rt pane directories [--q <text>] [--json]`, rt-client `paneDirectories()`.
+Suggestions for the New pane form's directory field: every repo the daemon
+indexes and every worktree it tracks, as `{ path, repo, branch? }`, filtered
+by `q` as a substring of the path. Read from the daemon's own state (the
+repo index and the worktree table), no git, so it is cheap enough to call
+per keystroke. It exists because rt-client has no `repos:list` or
+`worktree:list` catalog entry today and the viewer should not grow one just
+to autocomplete a path.
 
 ### `chat:invite`
 
@@ -171,27 +189,37 @@ an empty list and the account field hidden.
 `chatInvite()`. Types the join command into one pane and reports what
 happened; it never touches membership.
 
-- Text injected: `/chat:join <room>`, then, when a note is given, a second
-  line `note from <humanHandle>: <note>`. Nothing else; the brief is in the
-  room.
-- Delivery: herdr `agent.prompt` with `wait: { until: ["working"],
-  timeout_ms: 5000 }`. On a stall, one `Enter` keypress (the Claude TUI can
-  absorb the bundled Enter into the composer), then one more 5s wait.
+- Text injected, **one line**: `/chat:join <room>` and, when a note is
+  given, ` note from <from>: <note>` appended on the same line with any
+  newlines in the note collapsed to spaces. Claude Code dispatches a slash
+  command from the first line only, so a second line would turn the whole
+  thing into a plain prompt. Nothing else; the brief is in the room.
+- `from` is a payload field, never assumed: the CLI sends the session
+  file's handle (an agent) or `chat.humanHandle` when the caller is not
+  signed in; the viewer's route sends `chat.humanHandle` explicitly. An
+  agent's note therefore arrives attributed to that agent, never to Matt.
+- Delivery: `agent.get` first. `blocked`: refused, nothing sent. `working`:
+  `agent.prompt` without a wait, herdr queues it, result `queued`.
+  Otherwise `agent.prompt` with `wait: { until: ["working"], timeout_ms:
+  5000 }`; on a stall, one `Enter` keypress (the Claude TUI can absorb the
+  bundled Enter into the composer), then one more 5s wait.
 - Result: `{ paneId, delivered: "accepted" | "queued" | "refused", reason?:
-  string }`. `accepted`: the agent reached `working`. `queued`: the agent was
-  already `working`, herdr queued the text and no confirmation is possible.
-  `refused`: the pane is `blocked` (herdr will not inject into an approval
-  dialog), is not a Claude pane, or herdr is unavailable; `reason` says
-  which.
-- The pane's own session is refused with `reason: "that is this pane"` when
-  the caller runs inside herdr and `HERDR_PANE_ID` matches.
+  string }`. `accepted`: the agent reached `working`. `queued`: it was
+  already working, or never showed `working` after the nudge; either way
+  no confirmation is possible. `refused`: the pane is `blocked` (herdr will
+  not inject into an approval dialog), is not a Claude pane, is the
+  caller's own pane, or herdr is unavailable; `reason` says which.
+- The caller's own pane: the CLI sends `HERDR_PANE_ID` as `callerPane` in
+  the payload (the daemon cannot see the caller's environment); a match is
+  refused with `reason: "that is this pane"`.
 
 ### `rt chat read <room> --last N`
 
 Shows the newest N messages of a room regardless of the caller's cursor
 (`chat:messages`, the verb the viewer already reads with), then advances the
-cursor exactly as a plain `read` does. `--last` and `--since` are mutually
-exclusive. Documented in `rt:chat` as the way to catch up on a room you just
+cursor with `chat:mark` (the newest N always include the room's max id, so
+mark is exactly what a plain `read` would have done). `--last` and `--since`
+are mutually exclusive. Documented in `rt:chat` as the way to catch up on a room you just
 joined or were pointed at.
 
 ## Data flow
@@ -202,9 +230,11 @@ wakeOn? }`: the server joins as the human (which creates the room, stamping
 and returns `{ room, seedId? }`. Then `POST /api/chat/invite { room, panes:
 [{ paneId, note? }] }` runs `chatInvite` per pane, sequentially, and returns
 every result. The client navigates to `/r/<room>` and shows the results on
-the transcript's edge line. Members appear as each pane signs in: the roster
-polls every 5s and refetches on wake frames, and the join skill's first post
-is a wake frame.
+the transcript's edge line. Members appear as each pane signs in: the room
+page refetches `who` for the open room on every `chat/<room>/msg` frame
+(today it fetches only on room change), the fleet roster keeps its 5s poll,
+and the join skill's first post is a `chat/<room>/msg` frame in every wake
+mode, mentions or not.
 
 **Add agents to an existing room.** The room page opens the picker directly
 with `disable` marking members and blocked panes, then calls the invite
@@ -235,7 +265,7 @@ invitable, `not signed in` until it joins.
 | `GET /api/panes/:id/peek?lines=8` | `panePeek()` as `{ lines }`. |
 | `GET /api/panes/accounts` | `paneAccounts()` as `{ accounts }`; empty without cswap. |
 | `POST /api/panes` | `{ cwd, account?, model?, effort?, prompt?, workspace? }`; `paneSpawn()`; answers `{ pane, ready }` when the pane is usable or the budget is spent; 400 on a missing cwd or unknown account. |
-| `GET /api/panes/directories?q=` | suggestions for the directory field: rt's repos and their worktrees (`repos list`, `worktree list`), filtered by `q`. |
+| `GET /api/panes/directories?q=` | `paneDirectories({ q })` as `{ directories }`: rt's repos and their worktrees, filtered by `q`. |
 | `POST /api/chat/rooms` | `{ room, seed?, wakeOn? }`; validates the room name against rt's charset (400); joins as the human, posts the seed; returns `{ room, seedId? }`. |
 | `POST /api/chat/invite` | `{ room, panes: [{ paneId, note? }] }`; one `chatInvite` per pane, sequential; returns `{ results: InviteResult[] }` with 200 even when some refused. |
 
@@ -278,9 +308,9 @@ Row anatomy (see the artboards): a 16px checkbox; the 8px status dot and
 handle, or a hollow dot and `not signed in`; the workspace, plus the session
 title when it differs from the handle; the caller's reason or the agent
 state on the right (`working · queues until its turn ends`); a 22px eye; a
-second line `repo · branch` with room tags; the path, head-truncated with an
-LTR-isolated inner run so short paths keep their order; the peek block inside
-the row when open. Rows use the `.opt` wash when selected and 0.55 opacity
+second line `repo · branch` with room tags; the path rendered the way
+`Roster.tsx` already does it (real `…/leaf` text, `truncate` as the safety
+net, no `direction: rtl`); the peek block inside the row when open. Rows use the `.opt` wash when selected and 0.55 opacity
 when disabled.
 
 ### New room form
@@ -309,7 +339,7 @@ existing `Drawer` pattern. Not drawn in this pass.
 
 ### Conformance
 
-The three artboards join `design/build.py` as generators; `ANATOMY.md`
+The four artboards join `design/build.py` as generators; `ANATOMY.md`
 gains a "Pane picker" and "New room" section; `audit.mjs` gets `TARGETS` for
 the modal shell, the pane row, the checkbox, the peek block and both entry
 points. The task is not done until the audit passes against the fixtures
@@ -323,16 +353,24 @@ built; the picker is the component that will do it.
 The text an invite types into a pane, so it must work cold in any pane,
 signed in or not:
 
+The command line is `/chat:join <room> [note from <handle>: <text>]`, all
+on one line; the skill reads the room as the first word of `$ARGUMENTS` and
+the rest as the note.
+
 1. Gate: `rt chat rooms --json`; daemon down means say so and stop.
-2. `rt chat sign-in --room <room>` (adds the room on an already-signed-in
-   session; the handle is kept).
+2. Not signed in: `rt chat sign-in` (which joins the derived repository
+   room, so the invitee still lands where its worktree-mates are), then
+   `rt chat join <room>`. Already signed in: `rt chat join <room>` alone;
+   the handle is kept. Never `sign-in --room <room>` here: an explicit
+   `--room` replaces the derived room instead of adding to it.
 3. Arm the tail with `Monitor` if it is not running, by the session-start
    hook's own rule.
 4. `rt chat read <room> --last 10`: the seed and anything since.
 5. Post one line to the room saying what it understood and what it is
    taking, so the viewer shows arrival.
-6. Act on the seed plus any `note from <human>:` line that arrived with the
-   command. One narration line in the pane, per `rt:chat`.
+6. Act on the seed plus the note, if any, treating it as coming from the
+   handle it names (an agent's note is that agent's request, not Matt's).
+   One narration line in the pane, per `rt:chat`.
 
 ### Recruiting (new section in `rt:chat`)
 
@@ -345,7 +383,10 @@ The skill's trigger line gains "put you and another agent in a room". For
 3. **Always a form.** One `AskUserQuestion` carrying the candidate panes as
    options (title · repo · status; multi-select), the proposed room name
    (a slug from the topic), and the seed draft (post as drafted, or
-   rewrite). No pane is touched before the form returns.
+   rewrite). A question holds at most four options, so the four best
+   matches are the options; when more match, the question text lists the
+   rest by pane id and title and `Other` accepts a pane id. No pane is
+   touched before the form returns.
 4. `rt chat sign-in --room <room>`, post the seed as itself, then
    `rt chat invite <pane> --room <room> [--note ...]` per chosen pane,
    sequentially.
@@ -365,7 +406,7 @@ The skill's trigger line gains "put you and another agent in a room". For
 | Pane already in the room | Disabled in the picker; the recruiting flow skips it and says so. |
 | Seed post fails after the room was created | The room exists with no seed; the form reports the failure and keeps the draft, the same rule the composer follows. |
 | Invite fails part-way through a list | Every result is returned; the edge line shows each. Nothing is rolled back; a join is idempotent so re-inviting is safe. |
-| Short path in the picker | The LTR-isolated run keeps segment order; long paths still head-truncate. (Check `Roster.tsx`'s `.path` for the same bidi reorder on short paths while in there.) |
+| Long or short path in the picker | Rendered as `…/leaf` text the way `Roster.tsx` does, so short paths keep their order and long ones still read from the leaf. |
 | Spawn: workspace or tab creation fails | `pane:spawn` errors before anything runs; the form shows the herdr error and keeps its values. |
 | Spawn: Claude never registers or never reaches idle within 60s | The pane is returned with `ready: false` and its observed state; it stays open in herdr and listed in the picker, unselectable, peekable. Nothing is closed on rt's behalf. |
 | Spawn: trust dialog | `blocked` with "trust" on screen is answered with Enter once; any other `blocked` is returned as-is. |
@@ -382,9 +423,13 @@ The skill's trigger line gains "put you and another agent in a room". For
   exhausted returning `ready: false`, unknown account refused before any
   socket call. The `cswap list` parser on captured output, including the
   no-cswap case. `read --last` at the CLI, cursor advancing, exclusive with
-  `--since`. rt-client exports and types. `lib/herdr-agent.ts` moves from
-  the removed `herdr wait` to `herdr agent wait` (0.8.0), with its test
-  updated.
+  `--since`. rt-client exports and types, including the `timeoutMs`
+  overrides on `paneSpawn()` and `chatInvite()`. `lib/herdr-agent.ts` keeps
+  shelling out to the `herdr` CLI (it is the CLI-side bounded-agent helper
+  used by `lib/repo-index.ts` and `lib/rebase-escalation.ts`, not the
+  daemon); the only change is its `herdr wait ...` calls becoming
+  `herdr agent wait ...`, which herdr 0.7.5 renamed, with its test's fake
+  `herdr` updated to match.
 - chat: route tests with rt-client mocked as `chat.test.ts` does, including
   `available: false` and partial invite results. `PanePicker`: filter, sort,
   caller `disable` reasons, peek fetched only on open, resolve versus cancel,
@@ -399,21 +444,26 @@ The skill's trigger line gains "put you and another agent in a room". For
 
 ## Delivery order
 
-1. repo-tools: the herdr client and gate, `pane:list`, `pane:peek`,
-   `pane:spawn`, `pane:accounts`, `chat:invite`, `read --last`, the
-   `chat.herdrWorkspace` setting, rt-client wrappers and types, the verb
-   table and the recruiting section in `rt:chat`, the `herdr wait` fix.
-   Publish rt-client.
+1. repo-tools: the herdr socket client and gate, `pane:list`, `pane:peek`,
+   `pane:spawn`, `pane:accounts`, `pane:directories`, `chat:invite`,
+   `read --last`, the `chat.herdrWorkspace` setting, rt-client wrappers
+   and types with their `timeoutMs` overrides, the verb table and the
+   recruiting section in `rt:chat`, the `herdr agent wait` rename in
+   `lib/herdr-agent.ts`. Publish rt-client.
 2. chat: routes and fixtures, `PanePicker`, `NewRoomModal`, the two entry
-   points, the edge line, artboards and audit. Starts against fixtures; the
-   final wiring waits on rt-client.
-3. mattstack-marketplace: the `chat:join` skill.
+   points, the `who` refetch on `chat/<room>/msg`, the edge line, artboards
+   and audit. Starts against fixtures; the final wiring waits on rt-client.
+3. mattstack-marketplace: the `chat:join` skill, plus its
+   `./skills/join` entry in the plugin's `plugin.json` `skills` array.
 
 ## Out of scope
 
-- A membership-change event from `chat:join`. Polling plus the join skill's
-  first post covers arrival; a `chat/<room>/member` frame is a one-line
-  follow-up if it lags.
+- A membership-change event from `chat:join`. The `who` refetch on
+  `chat/<room>/msg` plus the join skill's first post covers arrival; a
+  `chat/<room>/member` frame is a one-line follow-up if it lags.
+- Moving `lib/herdr-agent.ts` (the CLI-side helper) onto the daemon's
+  socket client so there is one spawn implementation. Its callers are not
+  chat's; that is a follow-up with its own tests.
 - Focusing a herdr pane from the roster and DMing whoever is in a pane:
   future picker callers.
 - Provisioning a worktree from the New pane form; the directory must exist
@@ -436,5 +486,6 @@ The skill's trigger line gains "put you and another agent in a room". For
 - `skills/rt-chat/SKILL.md`: `rt chat invite` in the verb table, the
   `--last` flag on `read`, a pointer to the new `rt pane` group (`list`,
   `peek`, `spawn`, `accounts`), and the recruiting section.
-- `lib/herdr-agent.ts`: the spawn sequence becomes the shared
-  implementation `pane:spawn` uses; its callers keep their interface.
+- `lib/herdr-agent.ts`: only the `herdr wait` to `herdr agent wait` rename.
+  `pane:spawn` is a new daemon-side implementation on the socket client;
+  the CLI-side helper stays as is until the follow-up above migrates it.

From 59be66895dd4641996a741948c5d9b0adbcbbea0 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 19:42:33 -0500
Subject: [PATCH 04/30] docs: invite spec: review round 2 fixes (waiting-call
 socket timeouts, recruiter joins instead of re-signing in)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../specs/2026-08-26-rt-chat-invite-design.md | 24 ++++++++++++-------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
index 9247278a..32c7a4da 100644
--- a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -98,7 +98,10 @@ daemon runs outside any pane, so the path is configured, never inherited.
 Every `pane:*` verb and `chat:invite` answer `{ ok: false, error: "herdr
 unavailable" }` when the gate fails; nothing else about their shape changes.
 The daemon speaks herdr's newline-delimited JSON directly over the socket,
-one connection per call, 5s timeout per call. No shell-out to `herdr`. The
+one connection per call. Socket timeout: 5s for a plain call; for a waiting
+call (`agent.wait`, `agent.prompt` with `wait`) the request's own
+`timeout_ms` plus a 5s margin, since herdr answers those at, not before,
+their budget. No shell-out to `herdr`. The
 two process spawns in this feature (`cswap list` for the account roster,
 `git` for an unsigned pane's branch) are async `Bun.spawn`s; the base
 design's rule that nothing sync-execs on the daemon thread (MAT-222) holds.
@@ -119,7 +122,7 @@ interface ChatPane {
   workspace: string;         // herdr WorkspaceInfo.label
   title?: string;            // terminal_title_stripped, the Claude session title
   cwd?: string;              // foreground_cwd ?? cwd
-  repo?: string;             // the presence row's; else the daemon's repo index for cwd (no git)
+  repo?: string;             // the presence row's; else the repo index for cwd, via the worktree table for a linked worktree (no git)
   branch?: string;           // the presence row's; else one async `git` spawn for cwd
   agentStatus: "idle" | "working" | "blocked" | "done" | "unknown";
   sessionId?: string;        // agent_session.value, the Claude Code session UUID
@@ -244,8 +247,8 @@ if the room needs one.
 
 **Recruit from a pane.** The agent runs `rt pane list --json`, matches the
 request against title, repo, branch, cwd and handle, confirms through a
-form, signs itself in with `--room`, posts the seed as itself, and runs
-`rt chat invite` per chosen pane. See Skills.
+form, joins the room (signing in first only if it has not), posts the seed
+as itself, and runs `rt chat invite` per chosen pane. See Skills.
 
 **Spawn from the picker.** `POST /api/panes { cwd, account?, model?,
 effort?, prompt?, workspace? }` runs `paneSpawn` and answers with the
@@ -387,9 +390,12 @@ The skill's trigger line gains "put you and another agent in a room". For
    matches are the options; when more match, the question text lists the
    rest by pane id and title and `Other` accepts a pane id. No pane is
    touched before the form returns.
-4. `rt chat sign-in --room <room>`, post the seed as itself, then
-   `rt chat invite <pane> --room <room> [--note ...]` per chosen pane,
-   sequentially.
+4. Sign in only if not already signed in (plain `rt chat sign-in`, which
+   keeps the derived repository room), then `rt chat join <room>`, the same
+   rule as `/chat:join`; a re-sign-in would rewrite the session file's
+   `room` and `sign-in --room` would replace the derived room. Post the
+   seed as itself, then `rt chat invite <pane> --room <room> [--note ...]`
+   per chosen pane, sequentially.
 5. Report one line per pane (`accepted`, `queued, working`, `refused: at a
    prompt`) and the room link. A refused pane is reported, never retried
    blind.
@@ -440,7 +446,9 @@ The skill's trigger line gains "put you and another agent in a room". For
   kept on failure, result line. Fixtures for every route. `audit.mjs`
   targets for the new components, passing against `CHAT_FIXTURES=1`.
 - skills: `/chat:join` and the recruiting flow each get a real run in a
-  pane before they are called done.
+  pane before they are called done; the join run includes a note on the
+  command line, since that is the case the one-line dispatch claim exists
+  for.
 
 ## Delivery order
 

From 1cb3f93936c5184fdb76bc3932142d19dcbe027e Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 19:43:20 -0500
Subject: [PATCH 05/30] docs: invite spec: chatInvite timeout 30s (review
 advisory)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
index 32c7a4da..dd05bb24 100644
--- a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -107,7 +107,7 @@ two process spawns in this feature (`cswap list` for the account roster,
 design's rule that nothing sync-execs on the daemon thread (MAT-222) holds.
 
 Request timeouts: rt-client's default is 15s. `paneSpawn()` passes
-`timeoutMs: 90_000` and `chatInvite()` `timeoutMs: 20_000`, and the viewer's
+`timeoutMs: 90_000` and `chatInvite()` `timeoutMs: 30_000`, and the viewer's
 own `fetch` for those routes sets no shorter limit; the daemon's socket idle
 timeout (255s) already covers both.
 

From 3f467b8fd1301d65dd711c348d2387e995028340 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:11:16 -0500
Subject: [PATCH 06/30] docs: rt chat invite plans, parts 1 (rt), 2 (viewer), 3
 (join skill)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-26-rt-chat-invite-1-rt.md   | 2179 +++++++++++++++++
 .../2026-08-26-rt-chat-invite-2-viewer.md     | 1919 +++++++++++++++
 .../2026-08-26-rt-chat-invite-3-join-skill.md |  210 ++
 3 files changed, 4308 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
 create mode 100644 docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
 create mode 100644 docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
new file mode 100644
index 00000000..714e6f26
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
@@ -0,0 +1,2179 @@
+# rt chat invite, part 1: the rt primitives (repo-tools)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give rt the herdr-facing verbs the chat viewer and the recruiting skill need: `pane:list`, `pane:peek`, `pane:spawn`, `pane:accounts`, `pane:directories`, `chat:invite`, `rt chat read --last N`, the `chat.herdrWorkspace` setting, their rt-client wrappers, the `rt pane` CLI group, and the skill docs.
+
+**Architecture:** A new daemon-side herdr client speaks newline-delimited JSON over herdr's unix socket, one connection per call (herdr closes after every response). Daemon handlers in `lib/daemon/handlers/pane.ts` join herdr's pane list to rt's presence rows by Claude session id and expose the verbs through the rt-client `Commands` catalog like every other typed verb. `chat:invite` lives in the chat handler module and types `/chat:join <room>` into a pane with `agent.prompt`. Process spawns (`cswap list`, `git` for a branch) go through `lib/subprocess.ts`'s async `runCapture`, never sync. The CLI gains a `pane` group and two chat additions; rt-client gains six wrappers and five types.
+
+**Tech Stack:** Bun (`Bun.connect` / `Bun.listen` unix sockets, `bun:test`, `bun:sqlite`), TypeScript, the rt daemon's typed handler contract (`TypedHandlers`), rt-client.
+
+**Spec:** `docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md` (this repo).
+
+## Global Constraints
+
+- Work in this worktree (`~/Documents/GitHub/repo-tools-chat-invite`, branch `spec/rt-chat-invite`, rebased onto `main` before the PR); never on repo-tools' main checkout.
+- **No sync-exec on the daemon thread (MAT-222).** Handlers may call synchronous `bun:sqlite`; every process spawn is `runCapture` from `lib/subprocess.ts`; every herdr call is the async socket client. No `execSync`/`spawnSync` anywhere under `lib/daemon/` or `lib/herdr/`.
+- The herdr socket path is `HERDR_SOCKET_PATH`, else `~/.config/herdr/herdr.sock`. Socket timeout: 5s for a plain call; for a waiting call (`agent.wait`, `agent.prompt` with `wait`) the request's `timeout_ms` plus 5000.
+- Every `pane:*` verb and `chat:invite` answers `{ ok: false, error: "herdr unavailable" }` when the socket is missing or does not answer; the string is exactly `herdr unavailable`, optionally followed by `: <detail>`.
+- Every cataloged verb needs, in the same task: the `Commands` entry, the `COMMAND_NAMES` entry, the handler, and the router registration; `lib/daemon/__tests__/rt-client-commands.test.ts` fails otherwise.
+- Types rt-client cannot import are duplicated in `packages/rt-client/src/commands.ts` with the existing "Duplicated shape on purpose" comment convention.
+- Room and handle names are validated with `isValidChatName` (`^[a-z0-9._-]+$`).
+- Tests: `bun test <path>` per file while working; `bun test lib commands packages scripts` before every commit. Handler tests live in `lib/daemon/__tests__/`, lib tests in `lib/<dir>/__tests__/` or `lib/__tests__/`, CLI tests in `commands/__tests__/`, rt-client tests in `packages/rt-client/test/`.
+- After touching `lib/command-tree-def.ts`, run `bun scripts/gen-docs.ts` and commit the regenerated `website/docs/reference` (`bun scripts/check-docs.ts` gates it).
+- After touching anything under `packages/rt-client/src`, run `cd packages/rt-client && bun run build` (the dist-freshness test).
+- No em dashes or en dashes in code, comments, docs or commit messages. Comments only for constraints the code cannot show.
+- Commit after every task with a short imperative message.
+
+---
+
+### Task 1: the herdr socket client and its fake
+
+**Files:**
+- Create: `lib/herdr/client.ts`
+- Create: `lib/herdr/__tests__/fake-herdr.ts`
+- Test: `lib/herdr/__tests__/client.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `herdrSocketPath(): string`
+  - `HERDR_UNAVAILABLE = "herdr unavailable"`
+  - `type HerdrResult<T> = { ok: true; result: T } | { ok: false; code: string; message: string }`
+  - `herdrRequest<T>(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number; sockPath?: string }): Promise<HerdrResult<T>>`
+  - `herdrAvailable(sockPath?: string): Promise<boolean>`
+  - `waitTimeout(timeoutMs: number): number` (= `timeoutMs + 5000`)
+  - test helper `fakeHerdr(handler): { sock, seen, stop }`
+
+- [ ] **Step 1: Write the fake herdr server**
+
+Create `lib/herdr/__tests__/fake-herdr.ts`:
+
+```ts
+import { tmpdir } from "os";
+import { join } from "path";
+
+/** A reply the fake returns as herdr's `{ error: { code, message } }` envelope. */
+export class HerdrFakeError {
+  constructor(public code: string, public message: string) {}
+}
+
+export type FakeHerdrHandler = (method: string, params: Record<string, unknown>) => unknown | Promise<unknown>;
+
+let counter = 0;
+
+/**
+ * herdr's wire contract, for tests: newline-delimited JSON over a unix
+ * socket, one request per connection, the server closes after replying.
+ * The handler returns the `result` object (with its `type` field) or a
+ * HerdrFakeError; a thrown error becomes `internal_error`.
+ */
+export function fakeHerdr(handler: FakeHerdrHandler) {
+  const sock = join(tmpdir(), `fake-herdr-${process.pid}-${counter++}.sock`);
+  const seen: Array<{ method: string; params: Record<string, unknown> }> = [];
+  const buffers = new Map<object, string>();
+  const server = Bun.listen({
+    unix: sock,
+    socket: {
+      data(socket, chunk) {
+        const buf = (buffers.get(socket) ?? "") + chunk.toString();
+        const nl = buf.indexOf("\n");
+        if (nl < 0) {
+          buffers.set(socket, buf);
+          return;
+        }
+        buffers.delete(socket);
+        const line = buf.slice(0, nl);
+        void (async () => {
+          let reply: string;
+          let id = "";
+          try {
+            const req = JSON.parse(line) as { id: string; method: string; params?: Record<string, unknown> };
+            id = req.id;
+            const params = req.params ?? {};
+            seen.push({ method: req.method, params });
+            const out = await handler(req.method, params);
+            reply = out instanceof HerdrFakeError
+              ? JSON.stringify({ id, error: { code: out.code, message: out.message } })
+              : JSON.stringify({ id, result: out });
+          } catch (err) {
+            reply = JSON.stringify({ id, error: { code: "internal_error", message: err instanceof Error ? err.message : String(err) } });
+          }
+          socket.write(reply + "\n");
+          socket.end();
+        })();
+      },
+      close(socket) {
+        buffers.delete(socket);
+      },
+      error() {},
+    },
+  });
+  return { sock, seen, stop: () => server.stop(true) };
+}
+```
+
+- [ ] **Step 2: Write the failing client tests**
+
+Create `lib/herdr/__tests__/client.test.ts`:
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { tmpdir } from "os";
+import { join } from "path";
+import { HERDR_UNAVAILABLE, herdrAvailable, herdrRequest, waitTimeout } from "../client.ts";
+import { fakeHerdr, HerdrFakeError } from "./fake-herdr.ts";
+
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops) stop();
+  stops.length = 0;
+});
+
+test("a success reply comes back as ok with the result object", async () => {
+  const { sock, seen, stop } = fakeHerdr((method) => {
+    if (method === "pane.list") return { type: "pane_list", panes: [{ pane_id: "w1:p1" }] };
+    return new HerdrFakeError("invalid_request", "nope");
+  });
+  stops.push(stop);
+  const res = await herdrRequest<{ type: string; panes: unknown[] }>("pane.list", {}, { sockPath: sock });
+  expect(res.ok).toBe(true);
+  if (!res.ok) throw new Error("unreachable");
+  expect(res.result.panes).toHaveLength(1);
+  expect(seen[0]).toEqual({ method: "pane.list", params: {} });
+});
+
+test("an error reply comes back as ok:false with herdr's code and message", async () => {
+  const { sock, stop } = fakeHerdr(() => new HerdrFakeError("agent_blocked", "agent w1:p1 is blocked"));
+  stops.push(stop);
+  const res = await herdrRequest("agent.prompt", { target: "w1:p1", text: "hi" }, { sockPath: sock });
+  expect(res).toEqual({ ok: false, code: "agent_blocked", message: "agent w1:p1 is blocked" });
+});
+
+test("params travel verbatim, with the request id as a string", async () => {
+  const { sock, seen, stop } = fakeHerdr(() => ({ type: "ok" }));
+  stops.push(stop);
+  await herdrRequest("pane.send_input", { pane_id: "w1:p1", text: "ls", keys: ["enter"] }, { sockPath: sock });
+  expect(seen[0]!.params).toEqual({ pane_id: "w1:p1", text: "ls", keys: ["enter"] });
+});
+
+test("a missing socket is herdr unavailable, never a throw", async () => {
+  const res = await herdrRequest("pane.list", {}, { sockPath: join(tmpdir(), "no-such-herdr.sock") });
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.message.startsWith(HERDR_UNAVAILABLE)).toBe(true);
+});
+
+test("a reply slower than timeoutMs is a timeout", async () => {
+  const { sock, stop } = fakeHerdr(async () => {
+    await Bun.sleep(400);
+    return { type: "ok" };
+  });
+  stops.push(stop);
+  const res = await herdrRequest("agent.wait", { target: "w1:p1" }, { sockPath: sock, timeoutMs: 100 });
+  expect(res).toMatchObject({ ok: false, code: "timeout" });
+});
+
+test("herdrAvailable probes session.snapshot", async () => {
+  const { sock, seen, stop } = fakeHerdr(() => ({ type: "session_snapshot", snapshot: { panes: [], workspaces: [], agents: [], tabs: [], layouts: [], version: "0.8.0", protocol: 19 } }));
+  stops.push(stop);
+  expect(await herdrAvailable(sock)).toBe(true);
+  expect(seen[0]!.method).toBe("session.snapshot");
+  expect(await herdrAvailable(join(tmpdir(), "no-such-herdr.sock"))).toBe(false);
+});
+
+test("waitTimeout adds the 5s margin herdr needs to answer at its own budget", () => {
+  expect(waitTimeout(60_000)).toBe(65_000);
+});
+```
+
+- [ ] **Step 3: Run the tests to verify they fail**
+
+Run: `bun test lib/herdr/__tests__/client.test.ts`
+Expected: FAIL, `Cannot find module "../client.ts"`.
+
+- [ ] **Step 4: Write the client**
+
+Create `lib/herdr/client.ts`:
+
+```ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export const HERDR_UNAVAILABLE = "herdr unavailable";
+
+export type HerdrResult<T> = { ok: true; result: T } | { ok: false; code: string; message: string };
+
+const PLAIN_TIMEOUT_MS = 5_000;
+const WAIT_MARGIN_MS = 5_000;
+
+/** The daemon runs outside any pane, so the path is configured, never inherited from herdr. */
+export function herdrSocketPath(): string {
+  return process.env.HERDR_SOCKET_PATH ?? join(homedir(), ".config", "herdr", "herdr.sock");
+}
+
+/** herdr answers a waiting call at its budget, not before; the socket must outlive it. */
+export function waitTimeout(timeoutMs: number): number {
+  return timeoutMs + WAIT_MARGIN_MS;
+}
+
+let seq = 0;
+
+/**
+ * One request, one connection: herdr reads a single line and closes after
+ * replying, so there is nothing to pool. Never throws.
+ */
+export function herdrRequest<T = unknown>(
+  method: string,
+  params: Record<string, unknown> = {},
+  opts: { timeoutMs?: number; sockPath?: string } = {},
+): Promise<HerdrResult<T>> {
+  const sockPath = opts.sockPath ?? herdrSocketPath();
+  const timeoutMs = opts.timeoutMs ?? PLAIN_TIMEOUT_MS;
+  const id = `rt:${process.pid}:${++seq}`;
+  const line = JSON.stringify({ id, method, params }) + "\n";
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let buf = "";
+    let conn: { end(): void } | undefined;
+    const finish = (r: HerdrResult<T>) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { conn?.end(); } catch { /* already closed */ }
+      resolve(r);
+    };
+    const unavailable = (detail: string): HerdrResult<T> => ({ ok: false, code: "unreachable", message: `${HERDR_UNAVAILABLE}: ${detail}` });
+    const timer = setTimeout(() => finish({ ok: false, code: "timeout", message: `herdr ${method} timed out after ${timeoutMs}ms` }), timeoutMs);
+
+    if (!existsSync(sockPath)) {
+      finish(unavailable(`no socket at ${sockPath}`));
+      return;
+    }
+
+    Bun.connect({
+      unix: sockPath,
+      socket: {
+        open(socket) {
+          conn = socket;
+          socket.write(line);
+        },
+        data(_socket, chunk) {
+          buf += chunk.toString();
+          const nl = buf.indexOf("\n");
+          if (nl < 0) return;
+          const text = buf.slice(0, nl);
+          let parsed: { result?: T; error?: { code?: string; message?: string } };
+          try {
+            parsed = JSON.parse(text);
+          } catch {
+            finish({ ok: false, code: "invalid_response", message: `herdr ${method}: unparseable reply` });
+            return;
+          }
+          if (parsed.error) {
+            finish({ ok: false, code: String(parsed.error.code ?? "error"), message: String(parsed.error.message ?? "") });
+          } else {
+            finish({ ok: true, result: parsed.result as T });
+          }
+        },
+        error(_socket, err) {
+          finish(unavailable(err.message));
+        },
+        connectError(_socket, err) {
+          finish(unavailable(err.message));
+        },
+        close() {
+          finish(unavailable("connection closed before a reply"));
+        },
+      },
+    }).catch((err: unknown) => finish(unavailable(err instanceof Error ? err.message : String(err))));
+  });
+}
+
+/** The gate every pane verb sits behind: a socket that exists and answers. */
+export async function herdrAvailable(sockPath: string = herdrSocketPath()): Promise<boolean> {
+  if (!existsSync(sockPath)) return false;
+  const res = await herdrRequest("session.snapshot", {}, { sockPath });
+  return res.ok;
+}
+```
+
+- [ ] **Step 5: Run the tests to verify they pass**
+
+Run: `bun test lib/herdr/__tests__/client.test.ts`
+Expected: 7 pass. If `close()` fires before `data()` has settled a normal reply, the `finish` guard makes it a no-op; if a test sees `connection closed before a reply` on a successful call, the fake wrote and ended before the client's `data` ran, which means the buffered chunk arrives after `close`: move the `close` handler's `finish` behind a `queueMicrotask` so the pending `data` callback wins.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/herdr/client.ts lib/herdr/__tests__/fake-herdr.ts lib/herdr/__tests__/client.test.ts
+git commit -m "herdr: NDJSON socket client with a fake server for tests"
+```
+
+---
+
+### Task 2: cwd to repo and branch without a git spawn on the daemon
+
+**Files:**
+- Create: `lib/repo-for-cwd.ts`
+- Modify: `commands/chat.ts:188-274` (move `safeRealpath`, `findGitRoot`, `resolveMainWorktreePath`, `repoAliasForPath` out; import them back)
+- Test: `lib/__tests__/repo-for-cwd.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `findGitRoot(start: string): string | null`
+  - `resolveMainWorktreePath(worktreeRoot: string): string | null`
+  - `repoAliasForPath(mainWorktreePath: string, index: Record<string, string>): string | null`
+  - `repoForCwd(cwd: string, index: Record<string, string>): string | null` (the three above composed: git root, main worktree, alias)
+  - `branchForCwd(cwd: string, exec?: typeof runCapture): Promise<string | undefined>` (one async `git rev-parse --abbrev-ref HEAD`)
+- Consumes: `runCapture` from `lib/subprocess.ts`, `repoLabel` from `lib/repo-label.ts`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `lib/__tests__/repo-for-cwd.test.ts`:
+
+```ts
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { branchForCwd, repoForCwd, resolveMainWorktreePath } from "../repo-for-cwd.ts";
+
+let root: string;
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "rt-repo-for-cwd-")));
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+function mainRepo(name: string): string {
+  const path = join(root, name);
+  mkdirSync(join(path, ".git", "worktrees"), { recursive: true });
+  return path;
+}
+
+test("a main worktree resolves to its own alias", () => {
+  const main = mainRepo("acme");
+  mkdirSync(join(main, "src"));
+  expect(repoForCwd(join(main, "src"), { "remote:gitlab.com%2Facme%2Facme": main })).toBe("acme");
+});
+
+test("a linked worktree resolves through its .git file to the main repo's alias", () => {
+  const main = mainRepo("acme");
+  mkdirSync(join(main, ".git", "worktrees", "wt-1"));
+  const linked = join(root, "acme-wt-1");
+  mkdirSync(linked);
+  writeFileSync(join(linked, ".git"), `gitdir: ${join(main, ".git", "worktrees", "wt-1")}\n`);
+  expect(resolveMainWorktreePath(linked)).toBe(main);
+  expect(repoForCwd(linked, { "remote:gitlab.com%2Facme%2Facme": main })).toBe("acme");
+});
+
+test("a directory outside any repo resolves to null", () => {
+  const stray = join(root, "stray");
+  mkdirSync(stray);
+  expect(repoForCwd(stray, {})).toBeNull();
+});
+
+test("branchForCwd reads the branch through an injected async exec and never throws", async () => {
+  const exec = async () => ({ stdout: "feat/x\n", stderr: "", exitCode: 0 });
+  expect(await branchForCwd("/anywhere", exec)).toBe("feat/x");
+  const failing = async () => ({ stdout: "", stderr: "", exitCode: 128 });
+  expect(await branchForCwd("/anywhere", failing)).toBeUndefined();
+});
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run: `bun test lib/__tests__/repo-for-cwd.test.ts`
+Expected: FAIL, `Cannot find module "../repo-for-cwd.ts"`.
+
+- [ ] **Step 3: Create the module by moving the four functions out of `commands/chat.ts`**
+
+Create `lib/repo-for-cwd.ts` with the bodies of `safeRealpath`, `findGitRoot`, `resolveMainWorktreePath` and `repoAliasForPath` cut verbatim from `commands/chat.ts:188-274` (keep their comments), exported, plus:
+
+```ts
+import { existsSync, readFileSync, realpathSync, statSync } from "fs";
+import { dirname, join, resolve as resolvePath } from "path";
+import { repoLabel } from "./repo-label.ts";
+import { runCapture } from "./subprocess.ts";
+
+// ... the four moved functions, each with `export` ...
+
+/** cwd to the repo's display label using the repo index alone: no git spawn, so it is safe on the daemon thread. */
+export function repoForCwd(cwd: string, index: Record<string, string>): string | null {
+  const gitRoot = findGitRoot(cwd);
+  if (!gitRoot) return null;
+  const main = resolveMainWorktreePath(gitRoot);
+  if (!main) return null;
+  return repoAliasForPath(main, index);
+}
+
+/** The one git call an unsigned pane needs, async so the daemon loop never blocks. */
+export async function branchForCwd(cwd: string, exec: typeof runCapture = runCapture): Promise<string | undefined> {
+  const res = await exec(["git", "-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"], { timeoutMs: 2_000 });
+  if (res.exitCode !== 0) return undefined;
+  const branch = res.stdout.trim();
+  return branch && branch !== "HEAD" ? branch : undefined;
+}
+```
+
+In `commands/chat.ts`, delete the four function bodies and add `import { findGitRoot, repoAliasForPath, resolveMainWorktreePath, safeRealpath } from "../lib/repo-for-cwd.ts";` (keep only the names chat.ts still uses; drop the now-unused `fs`/`path` imports if eslint or tsc flags them). The `__test__` seam at the bottom of `commands/chat.ts` keeps exporting `findGitRoot`, `resolveMainWorktreePath`, `repoAliasForPath` so `commands/__tests__/chat.test.ts` is untouched.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `bun test lib/__tests__/repo-for-cwd.test.ts commands/__tests__/chat.test.ts`
+Expected: all pass (the chat CLI suite proves the move broke nothing).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/repo-for-cwd.ts lib/__tests__/repo-for-cwd.test.ts commands/chat.ts
+git commit -m "lib: repo-for-cwd, the git-free cwd to repo resolution shared by chat and the pane verbs"
+```
+
+---
+
+### Task 3: `pane:list` and `pane:peek`
+
+**Files:**
+- Modify: `packages/rt-client/src/commands.ts` (types, two `Commands` entries, `COMMAND_NAMES`)
+- Create: `lib/daemon/handlers/pane.ts`
+- Modify: `lib/daemon/command-router.ts` (import + spread)
+- Test: `lib/daemon/__tests__/pane-handlers.test.ts`
+
+**Interfaces:**
+- Produces (rt-client types, exported from `commands.ts`):
+
+```ts
+export type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors the daemon's pane row, which rt-client cannot import. */
+export interface ChatPane {
+  paneId: string;
+  workspace: string;
+  title?: string;
+  cwd?: string;
+  repo?: string;
+  branch?: string;
+  agentStatus: AgentStatus;
+  sessionId?: string;
+  presence?: { handle: string; status: BuddyStatus; rooms: string[] };
+}
+```
+
+  and the catalog entries:
+
+```ts
+  "pane:list": { payload: Record<string, never>; data: { panes: ChatPane[] } };
+  "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
+```
+
+- Produces (handler factory):
+
+```ts
+export function createPaneHandlers(opts: {
+  db: Database;
+  repoIndex: () => Record<string, string>;
+  herdr?: typeof herdrRequest;   // test seam
+  exec?: typeof runCapture;      // test seam
+  now?: () => number;            // test seam
+}): Pick<TypedHandlers, "pane:list" | "pane:peek"> & { db: Database }
+```
+
+  plus an exported `paneRow(pane: HerdrPane, ctx): Promise<ChatPane>` builder Task 5 reuses, and the wire types `HerdrPane`, `HerdrSnapshot`, `HerdrAgent` (the subset of herdr's `PaneInfo`/`AgentInfo`/`SessionSnapshot` fields used).
+
+- Consumes: `herdrRequest`, `HERDR_UNAVAILABLE` (Task 1); `repoForCwd`, `branchForCwd` (Task 2); `listBuddies`, `listRooms` from `lib/state/index.ts`.
+
+- [ ] **Step 1: Add the types and catalog entries to rt-client**
+
+In `packages/rt-client/src/commands.ts`, after the `PresenceRow`/`BuddyStatus` declarations, add the `AgentStatus` and `ChatPane` types above. In the `Commands` interface, after `"chat:dm"`, add the two entries. In `COMMAND_NAMES`, append `"pane:list"`, `"pane:peek"`.
+
+Run: `bun test lib/daemon/__tests__/rt-client-commands.test.ts`
+Expected: FAIL: the exhaustiveness test names `pane:list` and `pane:peek` as catalog entries with no handler. That failure is the contract; Steps 2 to 4 satisfy it.
+
+- [ ] **Step 2: Write the failing handler tests**
+
+Create `lib/daemon/__tests__/pane-handlers.test.ts`:
+
+```ts
+import { afterEach, expect, test } from "bun:test";
+import { tmpdir } from "os";
+import { join } from "path";
+import { HERDR_UNAVAILABLE, herdrRequest } from "../../herdr/client.ts";
+import { fakeHerdr, HerdrFakeError, type FakeHerdrHandler } from "../../herdr/__tests__/fake-herdr.ts";
+import { openStateDb } from "../../state/index.ts";
+import { createChatHandlers } from "../handlers/chat.ts";
+import { createPaneHandlers } from "../handlers/pane.ts";
+
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops) stop();
+  stops.length = 0;
+});
+
+let n = 0;
+function freshDb() {
+  return openStateDb(join(tmpdir(), `pane-h-${process.pid}-${n++}.db`));
+}
+
+const SNAPSHOT = {
+  type: "session_snapshot",
+  snapshot: {
+    version: "0.8.0",
+    protocol: 19,
+    workspaces: [{ workspace_id: "w1", label: "assured", focused: false }],
+    tabs: [],
+    layouts: [],
+    agents: [],
+    panes: [
+      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/assured", foreground_cwd: "/tmp/assured", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
+      { pane_id: "w1:p2", terminal_id: "t2", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "working", cwd: "/tmp/other", terminal_title_stripped: "fred", revision: 1 },
+      { pane_id: "w1:p3", terminal_id: "t3", workspace_id: "w1", tab_id: "w1:t2", focused: false, agent_status: "unknown", cwd: "/tmp", revision: 1 },
+    ],
+  },
+};
+
+function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string, string> } = {}) {
+  const { sock, seen, stop } = fakeHerdr(handler);
+  stops.push(stop);
+  const db = freshDb();
+  const herdr: typeof herdrRequest = (method, params, opts) => herdrRequest(method, params, { ...opts, sockPath: sock });
+  const exec = async () => ({ stdout: "feat/branch\n", stderr: "", exitCode: 0 });
+  const chat = createChatHandlers({ db, emitEvent: () => 0 });
+  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: () => 1_000_000 });
+  return { db, seen, chat, pane };
+}
+
+test("pane:list lists only claude panes, joined to presence by session id, with rooms", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/assured", repo: "assured", branch: "main", pane: "w1:p1" });
+  if (!signed.ok) throw new Error(signed.error);
+  await chat["chat:join"]({ room: "build", handle: signed.data.handle });
+
+  const res = await pane["pane:list"]({});
+  expect(res.ok).toBe(true);
+  if (!res.ok) throw new Error("unreachable");
+  expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p1", "w1:p2"]);
+  const first = res.data.panes[0]!;
+  expect(first).toMatchObject({ workspace: "assured", title: "Evaluate codegen", cwd: "/tmp/assured", repo: "assured", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
+  expect(first.presence).toMatchObject({ handle: "meg", rooms: ["build"] });
+  expect(first.presence!.status).not.toBe("offline");
+});
+
+test("pane:list falls back to the presence row's pane id when herdr has no session id", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-by-pane", baseHandle: "fred", cwd: "/tmp/other", pane: "w1:p2" });
+  if (!signed.ok) throw new Error(signed.error);
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.panes.find((p) => p.paneId === "w1:p2")!.presence?.handle).toBe("fred");
+});
+
+test("pane:list derives repo and branch for an unsigned pane without touching the presence table", async () => {
+  const { pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  const unsigned = res.data.panes.find((p) => p.paneId === "w1:p2")!;
+  expect(unsigned.presence).toBeUndefined();
+  expect(unsigned.branch).toBe("feat/branch");
+  expect(unsigned.repo).toBeUndefined();
+});
+
+test("pane:list sorts listening, idle, deaf, then not signed in", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-p2", baseHandle: "fred", pane: "w1:p2" });
+  if (!signed.ok) throw new Error(signed.error);
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p2", "w1:p1"]);
+});
+
+test("pane:list is herdr unavailable when the socket is missing", async () => {
+  const db = freshDb();
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: join(tmpdir(), "absent-herdr.sock") });
+  const pane = createPaneHandlers({ db, repoIndex: () => ({}), herdr });
+  const res = await pane["pane:list"]({});
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.error.startsWith(HERDR_UNAVAILABLE)).toBe(true);
+});
+
+test("pane:peek reads the visible screen and drops trailing blank lines", async () => {
+  const { pane, seen } = harness((method) =>
+    method === "pane.read"
+      ? { type: "pane_read", read: { pane_id: "w1:p1", workspace_id: "w1", tab_id: "w1:t1", source: "visible", format: "text", text: "⏺ Read(x)\n  ⎿ 12 lines\n❯ \n\n\n", revision: 0, truncated: false } }
+      : new HerdrFakeError("invalid_request", method),
+  );
+  const res = await pane["pane:peek"]({ paneId: "w1:p1", lines: 8 });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data).toEqual({ paneId: "w1:p1", lines: ["⏺ Read(x)", "  ⎿ 12 lines", "❯ "] });
+  expect(seen[0]).toEqual({ method: "pane.read", params: { pane_id: "w1:p1", source: "visible", lines: 8 } });
+});
+
+test("pane:peek passes herdr's pane_not_found through as an error", async () => {
+  const { pane } = harness(() => new HerdrFakeError("pane_not_found", "pane not found"));
+  const res = await pane["pane:peek"]({ paneId: "w9:p9" });
+  expect(res).toEqual({ ok: false, error: "pane_not_found: pane not found" });
+});
+```
+
+- [ ] **Step 3: Run the tests to verify they fail**
+
+Run: `bun test lib/daemon/__tests__/pane-handlers.test.ts`
+Expected: FAIL, `Cannot find module "../handlers/pane.ts"`.
+
+- [ ] **Step 4: Write the handler module**
+
+Create `lib/daemon/handlers/pane.ts`:
+
+```ts
+/**
+ * pane:* daemon handlers: herdr's panes joined to rt's presence.
+ * lib/herdr/client.ts owns the socket; this module owns the join.
+ */
+import type { Database } from "bun:sqlite";
+import type { AgentStatus, BuddyStatus, ChatPane, Commands } from "../../../packages/rt-client/src/commands.ts";
+import { HERDR_UNAVAILABLE, herdrRequest, type HerdrResult } from "../../herdr/client.ts";
+import { branchForCwd, repoForCwd } from "../../repo-for-cwd.ts";
+import { listBuddies, listRooms, type PresenceRow } from "../../state/index.ts";
+import { runCapture } from "../../subprocess.ts";
+import type { CommandResult, TypedHandlers } from "./types.ts";
+
+export interface HerdrPane {
+  pane_id: string;
+  workspace_id: string;
+  tab_id: string;
+  agent?: string;
+  agent_status: AgentStatus;
+  cwd?: string;
+  foreground_cwd?: string;
+  terminal_title?: string;
+  terminal_title_stripped?: string;
+  agent_session?: { source: string; agent: string; kind: "id" | "path"; value: string };
+}
+
+export interface HerdrWorkspace {
+  workspace_id: string;
+  label: string;
+}
+
+export interface HerdrSnapshot {
+  workspaces: HerdrWorkspace[];
+  panes: HerdrPane[];
+}
+
+export interface HerdrAgent extends HerdrPane {
+  state_change_seq?: number;
+}
+
+export interface PaneRowContext {
+  db: Database;
+  repoIndex: () => Record<string, string>;
+  exec: typeof runCapture;
+  now: () => number;
+  workspaces: Map<string, string>;
+  bySession: Map<string, PresenceRow & { status: BuddyStatus }>;
+  byPane: Map<string, PresenceRow & { status: BuddyStatus }>;
+}
+
+const STATUS_ORDER: Record<BuddyStatus | "none", number> = { live: 0, idle: 1, deaf: 2, offline: 3, none: 3 };
+
+export function herdrError(res: { ok: false; code: string; message: string }): { ok: false; error: string } {
+  if (res.code === "unreachable" || res.code === "timeout") return { ok: false, error: res.message.startsWith(HERDR_UNAVAILABLE) ? res.message : `${HERDR_UNAVAILABLE}: ${res.message}` };
+  return { ok: false, error: `${res.code}: ${res.message}` };
+}
+
+/** Presence maps built once per verb call; offline rows are not presence. */
+export function presenceMaps(db: Database, now: number): Pick<PaneRowContext, "bySession" | "byPane"> {
+  const bySession = new Map<string, PresenceRow & { status: BuddyStatus }>();
+  const byPane = new Map<string, PresenceRow & { status: BuddyStatus }>();
+  for (const row of listBuddies(now, db)) {
+    if (row.status === "offline") continue;
+    bySession.set(row.sessionId, row);
+    if (row.pane) byPane.set(row.pane, row);
+  }
+  return { bySession, byPane };
+}
+
+export async function paneRow(pane: HerdrPane, ctx: PaneRowContext): Promise<ChatPane> {
+  const sessionId = pane.agent_session?.kind === "id" ? pane.agent_session.value : undefined;
+  const presence = (sessionId ? ctx.bySession.get(sessionId) : undefined) ?? ctx.byPane.get(pane.pane_id);
+  const cwd = pane.foreground_cwd ?? pane.cwd;
+  let repo = presence?.repo;
+  let branch = presence?.branch;
+  if (!presence && cwd) {
+    repo = repoForCwd(cwd, ctx.repoIndex()) ?? undefined;
+    branch = await branchForCwd(cwd, ctx.exec);
+  }
+  return {
+    paneId: pane.pane_id,
+    workspace: ctx.workspaces.get(pane.workspace_id) ?? pane.workspace_id,
+    title: pane.terminal_title_stripped ?? pane.terminal_title,
+    cwd,
+    repo,
+    branch,
+    agentStatus: pane.agent_status,
+    sessionId,
+    presence: presence
+      ? { handle: presence.handle, status: presence.status, rooms: listRooms(presence.handle, ctx.db).map((r) => r.room) }
+      : undefined,
+  };
+}
+
+export function sortPanes(panes: ChatPane[]): ChatPane[] {
+  return panes
+    .map((p, i) => ({ p, i }))
+    .sort((a, b) => STATUS_ORDER[a.p.presence?.status ?? "none"] - STATUS_ORDER[b.p.presence?.status ?? "none"] || a.i - b.i)
+    .map(({ p }) => p);
+}
+
+export function createPaneHandlers(opts: {
+  db: Database;
+  repoIndex: () => Record<string, string>;
+  herdr?: typeof herdrRequest;
+  exec?: typeof runCapture;
+  now?: () => number;
+}): Pick<TypedHandlers, "pane:list" | "pane:peek"> & { db: Database } {
+  const { db, repoIndex } = opts;
+  const herdr = opts.herdr ?? herdrRequest;
+  const exec = opts.exec ?? runCapture;
+  const now = opts.now ?? Date.now;
+
+  async function snapshot(): Promise<HerdrResult<{ snapshot: HerdrSnapshot }>> {
+    return herdr<{ snapshot: HerdrSnapshot }>("session.snapshot", {});
+  }
+
+  return {
+    db,
+
+    "pane:list": async (): Promise<CommandResult<"pane:list">> => {
+      const snap = await snapshot();
+      if (!snap.ok) return herdrError(snap);
+      const ctx: PaneRowContext = {
+        db, repoIndex, exec, now,
+        workspaces: new Map(snap.result.snapshot.workspaces.map((w) => [w.workspace_id, w.label])),
+        ...presenceMaps(db, now()),
+      };
+      const claude = snap.result.snapshot.panes.filter((p) => p.agent === "claude");
+      const rows = await Promise.all(claude.map((p) => paneRow(p, ctx)));
+      return { ok: true, data: { panes: sortPanes(rows) } };
+    },
+
+    "pane:peek": async (payload: Commands["pane:peek"]["payload"]): Promise<CommandResult<"pane:peek">> => {
+      const params: Record<string, unknown> = { pane_id: payload.paneId, source: "visible" };
+      if (payload.lines !== undefined) params.lines = payload.lines;
+      const res = await herdr<{ read: { text: string } }>("pane.read", params);
+      if (!res.ok) return herdrError(res);
+      const lines = res.result.read.text.split("\n");
+      while (lines.length && lines[lines.length - 1]!.trim() === "") lines.pop();
+      return { ok: true, data: { paneId: payload.paneId, lines } };
+    },
+  };
+}
+```
+
+Check `listBuddies`'s exact export in `lib/state/index.ts` (it is `listBuddies(now, db)` returning `Array<PresenceRow & { status: BuddyStatus }>`) and that `PresenceRow` is exported from the barrel; if the barrel exports it under another name, import that.
+
+- [ ] **Step 5: Register the handlers in the router**
+
+In `lib/daemon/command-router.ts`, add `import { createPaneHandlers } from "./handlers/pane.ts";` beside the chat import, and in `buildRoutedHandlers`, after the `chatHandlers` destructure:
+
+```ts
+  const { db: _paneDb, ...paneHandlers } = createPaneHandlers({ db: opts.chatDb, repoIndex: ctx.repoIndex });
+```
+
+and spread `...paneHandlers,` right after `...chatHandlers,`.
+
+- [ ] **Step 6: Run the tests**
+
+Run: `bun test lib/daemon/__tests__/pane-handlers.test.ts lib/daemon/__tests__/rt-client-commands.test.ts`
+Expected: all pass. If the sort test fails because the signed-in `fred` row reads `deaf` rather than `idle` (no tail, no pulse), that is still ahead of `not signed in`; the expectation only orders presence before no presence.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/rt-client/src/commands.ts lib/daemon/handlers/pane.ts lib/daemon/command-router.ts lib/daemon/__tests__/pane-handlers.test.ts
+git commit -m "daemon: pane:list and pane:peek, herdr panes joined to presence"
+```
+
+---
+
+### Task 4: `pane:accounts` and `pane:directories`
+
+**Files:**
+- Modify: `packages/rt-client/src/commands.ts` (types `PaneAccount`, `PaneDirectory`; two entries; `COMMAND_NAMES`)
+- Create: `lib/cswap.ts`
+- Modify: `lib/daemon/handlers/pane.ts`
+- Test: `lib/__tests__/cswap.test.ts`, `lib/daemon/__tests__/pane-handlers.test.ts`
+
+**Interfaces:**
+- Produces (rt-client):
+
+```ts
+export interface PaneAccount { slot: number; email: string; alias?: string; headroom?: string }
+export interface PaneDirectory { path: string; repo: string; branch?: string }
+  "pane:accounts": { payload: Record<string, never>; data: { accounts: PaneAccount[] } };
+  "pane:directories": { payload: { q?: string }; data: { directories: PaneDirectory[] } };
+```
+
+- Produces (lib): `parseCswapList(text: string): PaneAccount[]`, `cswapBin(): string`, `listCswapAccounts(exec?): Promise<PaneAccount[]>`.
+- Consumes: `loadRegistry(repoName)` from `lib/worktree/registry.ts`, `repoLabel` from `lib/repo-label.ts`, `runCapture`.
+
+- [ ] **Step 1: Catalog entries**
+
+Add the two types and two entries to `packages/rt-client/src/commands.ts` and append `"pane:accounts"`, `"pane:directories"` to `COMMAND_NAMES`.
+
+- [ ] **Step 2: Write the failing cswap parser tests**
+
+Create `lib/__tests__/cswap.test.ts`:
+
+```ts
+import { expect, test } from "bun:test";
+import { listCswapAccounts, parseCswapList } from "../cswap.ts";
+
+const CAPTURED = `
+A newer version of claude-swap is available (0.25.0). You are using 0.23.0. Run \`cswap upgrade\` to update.
+Accounts:
+  1: matthew.goodwin@assured.claims [Assured] (history: shared)
+     ├ $$:    100%   $400.07 / $400.00
+     ├ 5h:      0%
+     ├ 7d:     40%   resets Aug 30 20:00  in 4d 0h
+     └ Fable:  35%   resets Aug 30 20:00  in 4d 0h · 6m ago
+  2: someone@example.com
+     └ 5h:     12%
+`;
+
+test("parses slots, emails, aliases and a compact headroom summary", () => {
+  expect(parseCswapList(CAPTURED)).toEqual([
+    { slot: 1, email: "matthew.goodwin@assured.claims", alias: "Assured", headroom: "5h 0% · 7d 40% · Fable 35%" },
+    { slot: 2, email: "someone@example.com", headroom: "5h 12%" },
+  ]);
+});
+
+test("an empty or unrelated output parses to no accounts", () => {
+  expect(parseCswapList("")).toEqual([]);
+  expect(parseCswapList("cswap: not found")).toEqual([]);
+});
+
+test("listCswapAccounts is empty when the binary is missing or fails", async () => {
+  const missing = async () => ({ stdout: "", stderr: "", exitCode: -1 });
+  expect(await listCswapAccounts(missing)).toEqual([]);
+});
+```
+
+- [ ] **Step 3: Run to verify failure**
+
+Run: `bun test lib/__tests__/cswap.test.ts`
+Expected: FAIL, `Cannot find module "../cswap.ts"`.
+
+- [ ] **Step 4: Write `lib/cswap.ts`**
+
+```ts
+import { homedir } from "os";
+import { join } from "path";
+import type { PaneAccount } from "../packages/rt-client/src/commands.ts";
+import { runCapture } from "./subprocess.ts";
+
+const ACCOUNT_LINE = /^\s*(\d+):\s+(\S+)(?:\s+\[([^\]]+)\])?/;
+// The `$$` row is spend, not rate-limit headroom; it is skipped on purpose.
+const HEADROOM_LINE = /^\s*[├└]\s+([^:$]+):\s+(\d+)%/;
+
+export function parseCswapList(text: string): PaneAccount[] {
+  const accounts: PaneAccount[] = [];
+  const headroom: string[][] = [];
+  for (const line of text.split("\n")) {
+    const acct = ACCOUNT_LINE.exec(line);
+    if (acct) {
+      accounts.push({ slot: Number(acct[1]), email: acct[2]!, ...(acct[3] ? { alias: acct[3] } : {}) });
+      headroom.push([]);
+      continue;
+    }
+    const head = HEADROOM_LINE.exec(line);
+    if (head && headroom.length) headroom[headroom.length - 1]!.push(`${head[1]!.trim()} ${head[2]}%`);
+  }
+  return accounts.map((a, i) => (headroom[i]!.length ? { ...a, headroom: headroom[i]!.join(" · ") } : a));
+}
+
+/** launchd's PATH does not carry ~/.local/bin, so resolve the binary explicitly. */
+export function cswapBin(): string {
+  return Bun.which("cswap") ?? join(homedir(), ".local", "bin", "cswap");
+}
+
+export async function listCswapAccounts(exec: typeof runCapture = runCapture): Promise<PaneAccount[]> {
+  const res = await exec([cswapBin(), "list"], { timeoutMs: 5_000 });
+  if (res.exitCode !== 0) return [];
+  return parseCswapList(res.stdout);
+}
+```
+
+- [ ] **Step 5: Write the failing handler tests**
+
+Append to `lib/daemon/__tests__/pane-handlers.test.ts`:
+
+```ts
+test("pane:accounts parses cswap list through the injected exec", async () => {
+  const db = freshDb();
+  const exec = async (argv: [string, ...string[]]) =>
+    argv[1] === "list"
+      ? { stdout: "Accounts:\n  1: a@b.c [A]\n     └ 5h: 3%\n", stderr: "", exitCode: 0 }
+      : { stdout: "", stderr: "", exitCode: 1 };
+  const pane = createPaneHandlers({ db, repoIndex: () => ({}), exec });
+  const res = await pane["pane:accounts"]({});
+  expect(res).toEqual({ ok: true, data: { accounts: [{ slot: 1, email: "a@b.c", alias: "A", headroom: "5h 3%" }] } });
+});
+
+test("pane:directories lists indexed repos and their registered worktrees, filtered by q", async () => {
+  const db = freshDb();
+  const pane = createPaneHandlers({
+    db,
+    repoIndex: () => ({ "remote:gitlab.com%2Facme%2Facme-dev": "/repos/acme-dev", "remote:github.com%2Fm%2Fchat": "/repos/chat" }),
+    registry: (name) => (name.endsWith("acme-dev") ? [{ path: "/repos/acme-dev-wt-1", branch: "feat/one" }] : []),
+  });
+  const all = await pane["pane:directories"]({});
+  if (!all.ok) throw new Error(all.error);
+  expect(all.data.directories).toEqual([
+    { path: "/repos/acme-dev", repo: "acme-dev" },
+    { path: "/repos/acme-dev-wt-1", repo: "acme-dev", branch: "feat/one" },
+    { path: "/repos/chat", repo: "chat" },
+  ]);
+  const filtered = await pane["pane:directories"]({ q: "wt-1" });
+  if (!filtered.ok) throw new Error(filtered.error);
+  expect(filtered.data.directories.map((d) => d.path)).toEqual(["/repos/acme-dev-wt-1"]);
+});
+```
+
+- [ ] **Step 6: Implement both handlers**
+
+In `lib/daemon/handlers/pane.ts`: extend the factory options with `registry?: (repoName: string) => Array<{ path: string; branch: string | null | undefined }>` (default: `(name) => loadRegistry(name)` imported from `../../worktree/registry.ts`), widen the return type to `Pick<TypedHandlers, "pane:list" | "pane:peek" | "pane:accounts" | "pane:directories">`, import `listCswapAccounts` from `../../cswap.ts` and `repoLabel` from `../../repo-label.ts`, and add:
+
+```ts
+    "pane:accounts": async (): Promise<CommandResult<"pane:accounts">> => {
+      return { ok: true, data: { accounts: await listCswapAccounts(exec) } };
+    },
+
+    "pane:directories": async (payload: Commands["pane:directories"]["payload"]): Promise<CommandResult<"pane:directories">> => {
+      const q = payload.q?.toLowerCase();
+      const seen = new Set<string>();
+      const out: PaneDirectory[] = [];
+      const push = (d: PaneDirectory) => {
+        if (seen.has(d.path)) return;
+        if (q && !d.path.toLowerCase().includes(q)) return;
+        seen.add(d.path);
+        out.push(d);
+      };
+      for (const [name, path] of Object.entries(repoIndex()).sort(([, a], [, b]) => a.localeCompare(b))) {
+        const repo = repoLabel(name);
+        push({ path, repo });
+        for (const tree of registry(name)) push({ path: tree.path, repo, ...(tree.branch ? { branch: tree.branch } : {}) });
+      }
+      return { ok: true, data: { directories: out } };
+    },
+```
+
+(`PaneDirectory` imported from the rt-client commands module.)
+
+- [ ] **Step 7: Run the tests**
+
+Run: `bun test lib/__tests__/cswap.test.ts lib/daemon/__tests__/pane-handlers.test.ts lib/daemon/__tests__/rt-client-commands.test.ts`
+Expected: all pass.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add packages/rt-client/src/commands.ts lib/cswap.ts lib/__tests__/cswap.test.ts lib/daemon/handlers/pane.ts lib/daemon/__tests__/pane-handlers.test.ts
+git commit -m "daemon: pane:accounts (cswap list) and pane:directories (repo index plus worktrees)"
+```
+
+---
+
+### Task 5: the `chat.herdrWorkspace` setting and `pane:spawn`
+
+**Files:**
+- Modify: `packages/rt-client/src/settings/registry-defs.ts` (chat block)
+- Modify: `packages/rt-client/src/commands.ts` (`pane:spawn` entry; `COMMAND_NAMES`)
+- Modify: `lib/daemon/handlers/pane.ts`
+- Test: `lib/daemon/__tests__/pane-handlers.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+  "pane:spawn": {
+    payload: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string };
+    data: { pane: ChatPane; ready: boolean };
+  };
+```
+
+  and the setting row `chat.herdrWorkspace` (string, user scope, default `"chat"`).
+- Consumes: `shellQuote` from `lib/herdr-launch.ts`, `getSetting` from `lib/settings/resolve.ts`, `listCswapAccounts`, `paneRow`.
+
+- [ ] **Step 1: The setting**
+
+In `packages/rt-client/src/settings/registry-defs.ts`, inside the `// --- chat (RT-48 Task 7)` block after `chat.viewerUrl`, add:
+
+```ts
+  {
+    key: "chat.herdrWorkspace",
+    type: "string",
+    scopes: ["user"],
+    default: "chat",
+    merge: "replace",
+    description: "herdr workspace label that rt pane spawn opens new agent tabs in; created when missing.",
+  },
+```
+
+Run: `cd packages/rt-client && bun run build && cd ../.. && bun test packages/rt-client/test`
+Expected: pass (the registry tests accept a string row with a default under the chat block).
+
+- [ ] **Step 2: Catalog entry**
+
+Add the `pane:spawn` entry to `Commands` and `"pane:spawn"` to `COMMAND_NAMES`.
+
+- [ ] **Step 3: Write the failing spawn tests**
+
+Append to `lib/daemon/__tests__/pane-handlers.test.ts`. The scripted fake tracks calls and returns status transitions in order:
+
+```ts
+function spawnFake(script: { statuses: string[]; screen?: string; agentGetFailures?: number }) {
+  let getCalls = 0;
+  let waitCalls = 0;
+  const calls: string[] = [];
+  const paneInfo = (status: string) => ({ pane_id: "w2:p7", terminal_id: "t7", workspace_id: "w2", tab_id: "w2:t3", focused: false, agent: "claude", agent_status: status, cwd: "/repos/acme-dev", terminal_title_stripped: "claude", revision: 3 });
+  const handler: FakeHerdrHandler = (method, params) => {
+    calls.push(method);
+    switch (method) {
+      case "workspace.list":
+        return { type: "workspace_list", workspaces: [{ workspace_id: "w2", label: "chat", focused: false }] };
+      case "workspace.create":
+        return { type: "workspace_created", workspace: { workspace_id: "w3", label: params.label }, tab: { tab_id: "w3:t1" }, root_pane: paneInfo("unknown") };
+      case "tab.create":
+        return { type: "tab_created", tab: { tab_id: "w2:t3", workspace_id: "w2", label: params.label }, root_pane: paneInfo("unknown") };
+      case "pane.send_input":
+      case "pane.send_keys":
+        return { type: "ok" };
+      case "agent.get":
+        if (getCalls++ < (script.agentGetFailures ?? 0)) return new HerdrFakeError("agent_not_found", "agent target w2:p7 not found");
+        return { type: "agent_info", agent: paneInfo(script.statuses[Math.min(waitCalls, script.statuses.length - 1)]!) };
+      case "agent.wait": {
+        const status = script.statuses[Math.min(waitCalls++, script.statuses.length - 1)]!;
+        if (status === "timeout") return new HerdrFakeError("timeout", "timed out waiting for agent status");
+        return { type: "agent_info", agent: paneInfo(status) };
+      }
+      case "pane.read":
+        return { type: "pane_read", read: { pane_id: "w2:p7", workspace_id: "w2", tab_id: "w2:t3", source: "visible", format: "text", text: script.screen ?? "", revision: 0, truncated: false } };
+      case "agent.prompt":
+        return { type: "agent_prompted", agent: paneInfo("working") };
+      case "pane.get":
+        return { type: "pane_info", pane: paneInfo(script.statuses[script.statuses.length - 1] === "timeout" ? "unknown" : script.statuses[script.statuses.length - 1]!) };
+      case "session.snapshot":
+        return { type: "session_snapshot", snapshot: { workspaces: [{ workspace_id: "w2", label: "chat" }], panes: [], tabs: [], layouts: [], agents: [], version: "0.8.0", protocol: 19 } };
+      default:
+        return new HerdrFakeError("invalid_request", method);
+    }
+  };
+  return { handler, calls };
+}
+
+const CSWAP_EXEC = async (argv: [string, ...string[]]) =>
+  argv[1] === "list" ? { stdout: "Accounts:\n  1: me@x.y [Me]\n", stderr: "", exitCode: 0 } : { stdout: "main\n", stderr: "", exitCode: 0 };
+
+test("pane:spawn creates a tab in the chat workspace, launches claude, waits for idle and returns the pane ready", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"], agentGetFailures: 2 });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/acme-dev", account: "Me", model: "claude-fable-5", effort: "high" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(true);
+  expect(res.data.pane).toMatchObject({ paneId: "w2:p7", workspace: "chat", cwd: "/repos/acme-dev", agentStatus: "idle" });
+  const tab = seen.find((s) => s.method === "tab.create")!;
+  expect(tab.params).toMatchObject({ workspace_id: "w2", label: "acme-dev", cwd: "/repos/acme-dev", focus: false });
+  const input = seen.find((s) => s.method === "pane.send_input")!;
+  expect(input.params.text).toBe("cd '/repos/acme-dev' && cswap run 'Me' --share-history -- claude --model 'claude-fable-5' --effort 'high'");
+  expect(input.params.keys).toEqual(["enter"]);
+  expect(calls.filter((c) => c === "agent.get").length).toBeGreaterThanOrEqual(3);
+  expect(calls).not.toContain("workspace.create");
+});
+
+test("pane:spawn creates the workspace when the label is missing and launches plain claude without an account", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"] });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", workspace: "fleet" });
+  if (!res.ok) throw new Error(res.error);
+  expect(calls).toContain("workspace.create");
+  expect(seen.find((s) => s.method === "workspace.create")!.params).toMatchObject({ label: "fleet", focus: false });
+  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd '/repos/chat' && claude");
+});
+
+test("pane:spawn answers the trust dialog once, then sends the opening prompt", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["blocked", "idle"], screen: "Do you trust the files in this folder?" });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", prompt: "read AGENTS.md" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(true);
+  expect(calls.filter((c) => c === "pane.send_keys")).toHaveLength(1);
+  expect(seen.find((s) => s.method === "agent.prompt")!.params).toMatchObject({ target: "w2:p7", text: "read AGENTS.md", wait: { until: ["working"], timeout_ms: 5000 } });
+});
+
+test("pane:spawn returns ready:false with the pane when idle never arrives, and does not send the prompt", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["timeout"] });
+  const { pane } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", prompt: "hi" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(false);
+  expect(res.data.pane.paneId).toBe("w2:p7");
+  expect(calls).not.toContain("agent.prompt");
+});
+
+test("pane:spawn refuses an unknown cswap account before touching herdr", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"] });
+  const { pane } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", account: "nobody" });
+  expect(res).toEqual({ ok: false, error: 'unknown cswap account "nobody"' });
+  expect(calls).toHaveLength(0);
+});
+```
+
+Update `harness()` so its `exec` is `CSWAP_EXEC` (the earlier `branchForCwd` test still passes because `CSWAP_EXEC` answers `main` for git; adjust that test's expectation from `feat/branch` to `main`).
+
+- [ ] **Step 4: Run to verify failure**
+
+Run: `bun test lib/daemon/__tests__/pane-handlers.test.ts`
+Expected: the five new tests FAIL (`pane["pane:spawn"] is not a function`).
+
+- [ ] **Step 5: Implement `pane:spawn`**
+
+In `lib/daemon/handlers/pane.ts`, add imports `import { basename } from "path"; import { getSetting } from "../../settings/resolve.ts"; import { shellQuote } from "../../herdr-launch.ts"; import { waitTimeout } from "../../herdr/client.ts";` (check `shellQuote`'s export in `lib/herdr-launch.ts:52`; if it is not exported, export it), widen the factory's return type with `"pane:spawn"`, and add these module-level constants and the handler:
+
+```ts
+const REGISTER_BUDGET_MS = 10_000;
+const REGISTER_POLL_MS = 250;
+const IDLE_BUDGET_MS = 50_000;
+const TRUST_BUDGET_MS = 15_000;
+const PROMPT_BUDGET_MS = 5_000;
+const SETTLED = ["idle", "done", "blocked"];
+
+export function launchCommand(a: { cwd: string; account?: string; model?: string; effort?: string }): string {
+  const claude = ["claude", ...(a.model ? ["--model", shellQuote(a.model)] : []), ...(a.effort ? ["--effort", shellQuote(a.effort)] : [])].join(" ");
+  const launch = a.account ? `cswap run ${shellQuote(a.account)} --share-history -- ${claude}` : claude;
+  return `cd ${shellQuote(a.cwd)} && ${launch}`;
+}
+```
+
+```ts
+    "pane:spawn": async (payload: Commands["pane:spawn"]["payload"]): Promise<CommandResult<"pane:spawn">> => {
+      const { cwd, account, model, effort, prompt } = payload;
+      if (!cwd || !cwd.startsWith("/")) return { ok: false, error: "cwd must be an absolute path" };
+      if (account) {
+        const accounts = await listCswapAccounts(exec);
+        const known = accounts.some((a) => a.alias === account || a.email === account || String(a.slot) === account);
+        if (!known) return { ok: false, error: `unknown cswap account "${account}"` };
+      }
+
+      const label = payload.workspace ?? getSetting<string>("chat.herdrWorkspace").value;
+      const list = await herdr<{ workspaces: HerdrWorkspace[] }>("workspace.list", {});
+      if (!list.ok) return herdrError(list);
+      let workspaceId = list.result.workspaces.find((w) => w.label === label)?.workspace_id;
+      if (!workspaceId) {
+        const created = await herdr<{ workspace: HerdrWorkspace }>("workspace.create", { label, focus: false });
+        if (!created.ok) return herdrError(created);
+        workspaceId = created.result.workspace.workspace_id;
+      }
+
+      const tab = await herdr<{ root_pane: HerdrPane }>("tab.create", { workspace_id: workspaceId, label: basename(cwd), cwd, focus: false });
+      if (!tab.ok) return herdrError(tab);
+      const paneId = tab.result.root_pane.pane_id;
+
+      const sent = await herdr("pane.send_input", { pane_id: paneId, text: launchCommand({ cwd, account, model, effort }), keys: ["enter"] });
+      if (!sent.ok) return herdrError(sent);
+
+      // herdr registers the agent a few hundred ms after the shell starts claude.
+      const registerDeadline = now() + REGISTER_BUDGET_MS;
+      let registered = false;
+      while (now() < registerDeadline) {
+        const got = await herdr("agent.get", { target: paneId });
+        if (got.ok) { registered = true; break; }
+        await Bun.sleep(REGISTER_POLL_MS);
+      }
+
+      let status: AgentStatus = "unknown";
+      let ready = false;
+      if (registered) {
+        const settled = await herdr<{ agent: HerdrAgent }>("agent.wait", { target: paneId, until: SETTLED, timeout_ms: IDLE_BUDGET_MS }, { timeoutMs: waitTimeout(IDLE_BUDGET_MS) });
+        if (settled.ok) status = settled.result.agent.agent_status;
+        if (status === "blocked") {
+          const screen = await herdr<{ read: { text: string } }>("pane.read", { pane_id: paneId, source: "visible" });
+          if (screen.ok && /trust/i.test(screen.result.read.text)) {
+            await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+            const again = await herdr<{ agent: HerdrAgent }>("agent.wait", { target: paneId, until: SETTLED, timeout_ms: TRUST_BUDGET_MS }, { timeoutMs: waitTimeout(TRUST_BUDGET_MS) });
+            if (again.ok) status = again.result.agent.agent_status;
+          }
+        }
+        ready = status === "idle" || status === "done";
+      }
+
+      if (ready && prompt) {
+        await herdr("agent.prompt", { target: paneId, text: prompt, wait: { until: ["working"], timeout_ms: PROMPT_BUDGET_MS } }, { timeoutMs: waitTimeout(PROMPT_BUDGET_MS) });
+      }
+
+      const info = await herdr<{ pane: HerdrPane }>("pane.get", { pane_id: paneId });
+      const raw: HerdrPane = info.ok ? info.result.pane : { ...tab.result.root_pane, agent: "claude", agent_status: status };
+      const ctx: PaneRowContext = { db, repoIndex, exec, now, workspaces: new Map([[workspaceId, label]]), ...presenceMaps(db, now()) };
+      const pane = await paneRow({ ...raw, agent_status: info.ok ? raw.agent_status : status }, ctx);
+      return { ok: true, data: { pane, ready } };
+    },
+```
+
+`now` is `Date.now` in production; the tests pass a fixed `now`, so replace the register loop's `now() < registerDeadline` with a counter when `opts.now` is injected: simplest is to compute attempts as `Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS)` and loop by count with `Bun.sleep(REGISTER_POLL_MS)`, which works under both. Use the count loop.
+
+- [ ] **Step 6: Run the tests**
+
+Run: `bun test lib/daemon/__tests__/pane-handlers.test.ts lib/daemon/__tests__/rt-client-commands.test.ts`
+Expected: all pass. The `agentGetFailures: 2` test takes about 0.5s of real sleep; fine.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/rt-client/src/settings/registry-defs.ts packages/rt-client/src/commands.ts lib/daemon/handlers/pane.ts lib/daemon/__tests__/pane-handlers.test.ts
+git commit -m "daemon: pane:spawn starts claude in a herdr tab; chat.herdrWorkspace setting"
+```
+
+---
+
+### Task 6: `chat:invite`
+
+**Files:**
+- Modify: `packages/rt-client/src/commands.ts` (`InviteResult`, entry, `COMMAND_NAMES`)
+- Modify: `lib/daemon/handlers/chat.ts` (`CHAT_COMMANDS`, the handler, a `herdr` seam on the factory)
+- Modify: `lib/daemon/command-router.ts` (nothing new: the chat factory already spreads)
+- Test: `lib/daemon/__tests__/chat-handlers.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export interface InviteResult { paneId: string; delivered: "accepted" | "queued" | "refused"; reason?: string }
+  "chat:invite": { payload: { paneId: string; room: string; note?: string; from: string; callerPane?: string }; data: InviteResult };
+```
+
+  and `inviteText(room: string, from: string, note?: string): string` exported from `lib/daemon/handlers/chat.ts`.
+- Consumes: `herdrRequest`, `waitTimeout`, `HERDR_UNAVAILABLE`, `herdrError` (from `pane.ts`).
+
+- [ ] **Step 1: Catalog entry**
+
+Add `InviteResult` and the `chat:invite` entry to `Commands`, and `"chat:invite"` to `COMMAND_NAMES`.
+
+- [ ] **Step 2: Write the failing tests**
+
+Append to `lib/daemon/__tests__/chat-handlers.test.ts` (add imports `import { herdrRequest } from "../../herdr/client.ts"; import { fakeHerdr, HerdrFakeError, type FakeHerdrHandler } from "../../herdr/__tests__/fake-herdr.ts"; import { inviteText } from "../handlers/chat.ts";` and an `afterEach` that stops fakes, as in the pane tests):
+
+```ts
+function inviteHarness(handler: FakeHerdrHandler) {
+  const { sock, seen, stop } = fakeHerdr(handler);
+  stops.push(stop);
+  const db = openStateDb(join(tmpdir(), `chat-inv-${process.pid}-${n++}.db`));
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: sock });
+  return { h: createChatHandlers({ db, emitEvent: () => 0, herdr }), seen };
+}
+
+const agent = (status: string) => ({ type: "agent_info", agent: { pane_id: "w1:p1", terminal_id: "t", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: status, revision: 1 } });
+
+test("inviteText is one line: the slash command, then the attributed note with newlines collapsed", () => {
+  expect(inviteText("build", "matt")).toBe("/chat:join build");
+  expect(inviteText("build", "fred", "take the\nserver half\n")).toBe("/chat:join build note from fred: take the server half");
+});
+
+test("chat:invite prompts an idle pane and reports accepted when it reaches working", async () => {
+  const { h, seen } = inviteHarness((method, params) => {
+    if (method === "agent.get") return agent("idle");
+    if (method === "agent.prompt") return { type: "agent_prompted", agent: { ...agent("working").agent, text: params.text } };
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt", note: "you own vite" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "accepted" } });
+  const prompt = seen.find((s) => s.method === "agent.prompt")!;
+  expect(prompt.params).toEqual({ target: "w1:p1", text: "/chat:join build note from matt: you own vite", wait: { until: ["working"], timeout_ms: 5000 } });
+});
+
+test("chat:invite queues into a working pane without waiting", async () => {
+  const { h, seen } = inviteHarness((method) => {
+    if (method === "agent.get") return agent("working");
+    if (method === "agent.prompt") return { type: "agent_prompted", agent: agent("working").agent };
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "queued" } });
+  expect(seen.find((s) => s.method === "agent.prompt")!.params).toEqual({ target: "w1:p1", text: "/chat:join build" });
+});
+
+test("chat:invite refuses a blocked pane without sending anything", async () => {
+  const { h, seen } = inviteHarness((method) => (method === "agent.get" ? agent("blocked") : new HerdrFakeError("invalid_request", method)));
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "at a prompt" } });
+  expect(seen.map((s) => s.method)).toEqual(["agent.get"]);
+});
+
+test("chat:invite nudges Enter once on a stalled prompt, then reports accepted or queued honestly", async () => {
+  let prompts = 0;
+  const { h, seen } = inviteHarness((method) => {
+    if (method === "agent.get") return agent("idle");
+    if (method === "agent.prompt") { prompts++; return new HerdrFakeError("agent_prompt_stalled", "no state change"); }
+    if (method === "pane.send_keys") return { type: "ok" };
+    if (method === "agent.wait") return new HerdrFakeError("timeout", "timed out waiting for agent status");
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "queued" } });
+  expect(prompts).toBe(1);
+  expect(seen.filter((s) => s.method === "pane.send_keys")).toHaveLength(1);
+});
+
+test("chat:invite refuses a pane that is not a claude pane, the caller's own pane, and a bad room", async () => {
+  const { h } = inviteHarness((method) => (method === "agent.get" ? new HerdrFakeError("agent_not_found", "agent target w1:p1 not found") : new HerdrFakeError("invalid_request", method)));
+  expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "not a claude pane" } });
+  expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt", callerPane: "w1:p1" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "that is this pane" } });
+  const bad = await h["chat:invite"]({ paneId: "w1:p1", room: "Bad Room", from: "matt" });
+  expect(bad.ok).toBe(false);
+});
+
+test("chat:invite is herdr unavailable when the socket is missing", async () => {
+  const db = openStateDb(join(tmpdir(), `chat-inv-${process.pid}-${n++}.db`));
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: join(tmpdir(), "absent-herdr.sock") });
+  const h = createChatHandlers({ db, emitEvent: () => 0, herdr });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.error.startsWith("herdr unavailable")).toBe(true);
+});
+```
+
+- [ ] **Step 3: Run to verify failure**
+
+Run: `bun test lib/daemon/__tests__/chat-handlers.test.ts`
+Expected: the new tests FAIL (`inviteText` not exported; `chat:invite` not a function).
+
+- [ ] **Step 4: Implement**
+
+In `lib/daemon/handlers/chat.ts`: add `"chat:invite"` to `CHAT_COMMANDS`; add `herdr?: typeof herdrRequest` to the factory options (`const herdr = opts.herdr ?? herdrRequest;`); import `herdrRequest`, `waitTimeout` from `../../herdr/client.ts` and `herdrError` from `./pane.ts`; and add:
+
+```ts
+const INVITE_WAIT_MS = 5_000;
+
+/** One line, because Claude Code dispatches a slash command from the first line only. */
+export function inviteText(room: string, from: string, note?: string): string {
+  const head = `/chat:join ${room}`;
+  const body = note?.replace(/\s*\n+\s*/g, " ").trim();
+  return body ? `${head} note from ${from}: ${body}` : head;
+}
+```
+
+```ts
+    "chat:invite": async (payload: Commands["chat:invite"]["payload"]): Promise<CommandResult<"chat:invite">> => {
+      const { paneId, room, note, from, callerPane } = payload;
+      if (!isValidChatName(room)) return { ok: false, error: `invalid room "${room}"` };
+      if (!isValidChatName(from)) return { ok: false, error: `invalid handle "${from}"` };
+      const refused = (reason: string): CommandResult<"chat:invite"> => ({ ok: true, data: { paneId, delivered: "refused", reason } });
+      if (callerPane && callerPane === paneId) return refused("that is this pane");
+
+      const probe = await herdr<{ agent: { agent_status: string } }>("agent.get", { target: paneId });
+      if (!probe.ok) {
+        if (probe.code === "agent_not_found" || probe.code === "agent_target_ambiguous") return refused("not a claude pane");
+        return herdrError(probe);
+      }
+      const status = probe.result.agent.agent_status;
+      if (status === "blocked") return refused("at a prompt");
+
+      const text = inviteText(room, from, note);
+      if (status === "working") {
+        const queued = await herdr("agent.prompt", { target: paneId, text });
+        if (!queued.ok) return queued.code === "agent_blocked" ? refused("at a prompt") : herdrError(queued);
+        return { ok: true, data: { paneId, delivered: "queued" } };
+      }
+
+      const prompted = await herdr("agent.prompt", { target: paneId, text, wait: { until: ["working"], timeout_ms: INVITE_WAIT_MS } }, { timeoutMs: waitTimeout(INVITE_WAIT_MS) });
+      if (prompted.ok) return { ok: true, data: { paneId, delivered: "accepted" } };
+      if (prompted.code === "agent_blocked") return refused("at a prompt");
+      if (prompted.code !== "timeout" && prompted.code !== "agent_prompt_stalled") return herdrError(prompted);
+
+      // The Claude TUI can absorb the bundled Enter into the composer; one nudge, one more wait.
+      await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+      const nudged = await herdr("agent.wait", { target: paneId, until: ["working"], timeout_ms: INVITE_WAIT_MS }, { timeoutMs: waitTimeout(INVITE_WAIT_MS) });
+      return { ok: true, data: { paneId, delivered: nudged.ok ? "accepted" : "queued" } };
+    },
+```
+
+`pane.ts` importing nothing from `chat.ts` and `chat.ts` importing `herdrError` from `pane.ts` keeps the dependency one-way.
+
+- [ ] **Step 5: Run the tests**
+
+Run: `bun test lib/daemon/__tests__/chat-handlers.test.ts lib/daemon/__tests__/rt-client-commands.test.ts`
+Expected: all pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/rt-client/src/commands.ts lib/daemon/handlers/chat.ts lib/daemon/__tests__/chat-handlers.test.ts
+git commit -m "daemon: chat:invite types /chat:join into a herdr pane"
+```
+
+---
+
+### Task 7: rt-client wrappers
+
+**Files:**
+- Modify: `packages/rt-client/src/client.ts`
+- Modify: `packages/rt-client/src/index.ts` (function block, type block)
+- Modify: `packages/rt-client/README.md` (the Chat table)
+- Test: `packages/rt-client/test/client.test.ts`, `packages/rt-client/test/index-surface.test.ts`
+
+**Interfaces:**
+- Produces:
+
+```ts
+paneList(o?: RtClientOptions): Promise<RtResponse<{ panes: ChatPane[] }>>
+panePeek(a: { paneId: string; lines?: number }, o?: RtClientOptions): Promise<RtResponse<{ paneId: string; lines: string[] }>>
+paneSpawn(a: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string }, o?: RtClientOptions): Promise<RtResponse<{ pane: ChatPane; ready: boolean }>>   // timeoutMs default 90_000
+paneAccounts(o?: RtClientOptions): Promise<RtResponse<{ accounts: PaneAccount[] }>>
+paneDirectories(a: { q?: string }, o?: RtClientOptions): Promise<RtResponse<{ directories: PaneDirectory[] }>>
+chatInvite(a: { paneId: string; room: string; note?: string; from: string; callerPane?: string }, o?: RtClientOptions): Promise<RtResponse<InviteResult>>   // timeoutMs default 30_000
+```
+
+  and type re-exports `AgentStatus`, `ChatPane`, `PaneAccount`, `PaneDirectory`, `InviteResult`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `packages/rt-client/test/client.test.ts` (the file already imports `fakeDaemon` and keeps a `stops` list):
+
+```ts
+import { chatInvite, paneDirectories, paneList, panePeek, paneSpawn } from "../src/client.ts";
+
+describe("pane wrappers", () => {
+  test("paneList sends an empty payload; panePeek and paneDirectories omit undefined fields", async () => {
+    const { sock, seen, stop } = fakeDaemon({
+      "pane:list": { ok: true, data: { panes: [] } },
+      "pane:peek": { ok: true, data: { paneId: "w1:p1", lines: [] } },
+      "pane:directories": { ok: true, data: { directories: [] } },
+    });
+    stops.push(stop);
+    await paneList({ sockPath: sock });
+    await panePeek({ paneId: "w1:p1" }, { sockPath: sock });
+    await paneDirectories({}, { sockPath: sock });
+    expect(seen.map((s) => [s.cmd, s.payload])).toEqual([
+      ["pane:list", {}],
+      ["pane:peek", { paneId: "w1:p1" }],
+      ["pane:directories", {}],
+    ]);
+  });
+
+  test("paneSpawn and chatInvite outlive rt-client's 15s default", async () => {
+    const { sock, stop } = fakeDaemon({});
+    stops.push(stop);
+    // fakeDaemon answers instantly; the assertion is on the timeout the wrapper hands rtCommand,
+    // captured through the AbortSignal it builds. Spy on AbortSignal.timeout.
+    const spy = spyOn(AbortSignal, "timeout");
+    await paneSpawn({ cwd: "/x" }, { sockPath: sock });
+    await chatInvite({ paneId: "w1:p1", room: "build", from: "matt" }, { sockPath: sock });
+    expect(spy.mock.calls.map((c) => c[0])).toEqual([90_000, 30_000]);
+    spy.mockRestore();
+  });
+});
+```
+
+(Add `spyOn` to the `bun:test` import at the top of the file.)
+
+Append to `packages/rt-client/test/index-surface.test.ts` a check that `paneList`, `panePeek`, `paneSpawn`, `paneAccounts`, `paneDirectories`, `chatInvite` are functions on the barrel, in the file's existing style.
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bun test packages/rt-client/test/client.test.ts packages/rt-client/test/index-surface.test.ts`
+Expected: FAIL on the missing exports.
+
+- [ ] **Step 3: Write the wrappers**
+
+In `packages/rt-client/src/client.ts`, after the chat wrappers:
+
+```ts
+// ─── Panes (rt chat invite) ────────────────────────────────────────────────
+// herdr-facing verbs; the daemon answers `herdr unavailable` without herdr.
+
+export function paneList(o: RtClientOptions = {}): Promise<RtResponse<{ panes: ChatPane[] }>> {
+  return rtCommand<{ panes: ChatPane[] }>("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function panePeek(a: { paneId: string; lines?: number }, o: RtClientOptions = {}): Promise<RtResponse<{ paneId: string; lines: string[] }>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId };
+  if (a.lines !== undefined) payload.lines = a.lines;
+  return rtCommand<{ paneId: string; lines: string[] }>("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** The spawn waits on claude starting, so its budget is minutes, not seconds. */
+export function paneSpawn(
+  a: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ pane: ChatPane; ready: boolean }>> {
+  const payload: Record<string, unknown> = { cwd: a.cwd };
+  for (const k of ["account", "model", "effort", "prompt", "workspace"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<{ pane: ChatPane; ready: boolean }>("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90_000 });
+}
+
+export function paneAccounts(o: RtClientOptions = {}): Promise<RtResponse<{ accounts: PaneAccount[] }>> {
+  return rtCommand<{ accounts: PaneAccount[] }>("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function paneDirectories(a: { q?: string }, o: RtClientOptions = {}): Promise<RtResponse<{ directories: PaneDirectory[] }>> {
+  const payload: Record<string, unknown> = {};
+  if (a.q !== undefined) payload.q = a.q;
+  return rtCommand<{ directories: PaneDirectory[] }>("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatInvite(
+  a: { paneId: string; room: string; note?: string; from: string; callerPane?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<InviteResult>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId, room: a.room, from: a.from };
+  if (a.note !== undefined) payload.note = a.note;
+  if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
+  return rtCommand<InviteResult>("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
+```
+
+Import the types from `./commands.ts`. In `packages/rt-client/src/index.ts`, add the six functions to the function re-export block and the five types to the type block. In `packages/rt-client/README.md`'s Chat table, add a row: `paneList / panePeek / paneSpawn / paneAccounts / paneDirectories` with "herdr panes: list with presence joined, peek a screen, start claude in a tab, cswap accounts, directory suggestions" and a row `chatInvite` with "type `/chat:join <room>` into a pane; `accepted`, `queued` or `refused`".
+
+- [ ] **Step 4: Build and test**
+
+Run: `cd packages/rt-client && bun run build && cd ../.. && bun test packages/rt-client/test`
+Expected: all pass, including dist-freshness.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/rt-client
+git commit -m "rt-client: pane and invite wrappers with their own timeouts"
+```
+
+---
+
+### Task 8: the `rt pane` CLI group
+
+**Files:**
+- Create: `commands/pane.ts`
+- Modify: `lib/command-tree-def.ts` (a `pane` group with five subcommands)
+- Modify: `lib/module-registry.ts` (one entry)
+- Test: `commands/__tests__/pane.test.ts`
+- Regenerate: `website/docs/reference` via `bun scripts/gen-docs.ts`
+
+**Interfaces:**
+- Produces: `paneList`, `panePeek`, `paneSpawn`, `paneAccounts`, `paneDirectories` exports, each `(args: string[]) => Promise<void>`.
+  - `rt pane list [--json]`
+  - `rt pane peek <pane> [--lines 8] [--json]`
+  - `rt pane spawn --cwd <path> [--account <a>] [--model <m>] [--effort <e>] [--prompt <text>] [--workspace <label>] [--json]`
+  - `rt pane accounts [--json]`
+  - `rt pane directories [--q <text>] [--json]`
+- Consumes: the Task 7 wrappers.
+
+- [ ] **Step 1: Write the failing CLI tests**
+
+Create `commands/__tests__/pane.test.ts`, modelled on the fake daemon in `packages/rt-client/test/fake-daemon.ts` and the `process.exit` sentinel harness in `commands/__tests__/chat.test.ts:141-183` (copy `runRaw` from there, calling the pane exports):
+
+```ts
+import { afterEach, beforeEach, expect, spyOn, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { paneAccounts, paneDirectories, paneList, panePeek, paneSpawn } from "../pane.ts";
+
+let home: string;
+let origHome: string | undefined;
+let server: ReturnType<typeof Bun.serve> | undefined;
+let seen: Array<{ cmd: string; payload: unknown }> = [];
+let replies: Record<string, unknown> = {};
+
+beforeEach(() => {
+  origHome = process.env.HOME;
+  home = realpathSync(mkdtempSync(join(tmpdir(), "rt-pane-cli-")));
+  process.env.HOME = home;
+  const sockDir = join(home, ".mattstack", "rt");
+  mkdirSync(sockDir, { recursive: true });
+  seen = [];
+  server = Bun.serve({
+    unix: join(sockDir, "rt.sock"),
+    async fetch(req) {
+      const cmd = new URL(req.url).pathname.slice(1);
+      const payload = req.method === "POST" ? await req.json() : {};
+      seen.push({ cmd, payload });
+      return Response.json(replies[cmd] ?? { ok: false, error: `unknown command: ${cmd}` });
+    },
+  });
+});
+
+afterEach(() => {
+  server?.stop(true);
+  process.env.HOME = origHome;
+});
+
+async function run(fn: (args: string[]) => Promise<void>, args: string[]) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const logSpy = spyOn(console, "log").mockImplementation((...a: unknown[]) => { out.push(a.map(String).join(" ")); });
+  const errSpy = spyOn(console, "error").mockImplementation((...a: unknown[]) => { err.push(a.map(String).join(" ")); });
+  const exitSpy = spyOn(process, "exit").mockImplementation(() => { throw new Error("process.exit sentinel"); });
+  let code = 0;
+  try {
+    await fn(args);
+  } catch (e) {
+    if (e instanceof Error && e.message === "process.exit sentinel") code = (exitSpy.mock.calls.at(-1)?.[0] as number | undefined) ?? 1;
+    else throw e;
+  } finally {
+    logSpy.mockRestore(); errSpy.mockRestore(); exitSpy.mockRestore();
+  }
+  return { code, stdout: out.join("\n"), stderr: err.join("\n") };
+}
+
+const PANE = { paneId: "w1:p1", workspace: "assured", title: "Evaluate codegen", cwd: "/repos/assured", repo: "assured", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
+
+test("pane list --json prints the rows; plain prints one line per pane", async () => {
+  replies = { "pane:list": { ok: true, data: { panes: [PANE, { ...PANE, paneId: "w1:p2", presence: undefined, title: "fred" }] } } };
+  const json = await run(paneList, ["--json"]);
+  expect(JSON.parse(json.stdout)).toEqual({ ok: true, panes: replies["pane:list"]!["data"]["panes"] });
+  const plain = await run(paneList, []);
+  expect(plain.stdout).toContain("w1:p1");
+  expect(plain.stdout).toContain("meg");
+  expect(plain.stdout).toContain("not signed in");
+});
+
+test("pane list reports herdr unavailable and exits 1", async () => {
+  replies = { "pane:list": { ok: false, error: "herdr unavailable: no socket" } };
+  const r = await run(paneList, []);
+  expect(r.code).toBe(1);
+  expect(r.stderr).toContain("herdr unavailable");
+});
+
+test("pane peek passes the pane id and --lines", async () => {
+  replies = { "pane:peek": { ok: true, data: { paneId: "w1:p1", lines: ["a", "b"] } } };
+  const r = await run(panePeek, ["w1:p1", "--lines", "2"]);
+  expect(seen[0]).toEqual({ cmd: "pane:peek", payload: { paneId: "w1:p1", lines: 2 } });
+  expect(r.stdout).toBe("a\nb");
+});
+
+test("pane spawn passes every flag and prints the pane and readiness", async () => {
+  replies = { "pane:spawn": { ok: true, data: { pane: PANE, ready: true } } };
+  const r = await run(paneSpawn, ["--cwd", "/repos/assured", "--account", "Assured", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
+  expect(seen[0]!.payload).toEqual({ cwd: "/repos/assured", account: "Assured", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
+  expect(JSON.parse(r.stdout)).toMatchObject({ ok: true, ready: true, pane: { paneId: "w1:p1" } });
+});
+
+test("pane spawn requires --cwd", async () => {
+  const r = await run(paneSpawn, []);
+  expect(r.code).toBe(1);
+  expect(r.stderr).toContain("--cwd");
+});
+
+test("pane accounts and directories render", async () => {
+  replies = {
+    "pane:accounts": { ok: true, data: { accounts: [{ slot: 1, email: "a@b.c", alias: "A", headroom: "5h 3%" }] } },
+    "pane:directories": { ok: true, data: { directories: [{ path: "/repos/chat", repo: "chat" }] } },
+  };
+  expect((await run(paneAccounts, [])).stdout).toContain("A");
+  const d = await run(paneDirectories, ["--q", "chat"]);
+  expect(seen.at(-1)).toEqual({ cmd: "pane:directories", payload: { q: "chat" } });
+  expect(d.stdout).toContain("/repos/chat");
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bun test commands/__tests__/pane.test.ts`
+Expected: FAIL, `Cannot find module "../pane.ts"`.
+
+- [ ] **Step 3: Write `commands/pane.ts`**
+
+```ts
+/**
+ * rt pane: herdr panes as rt sees them (joined to chat presence).
+ *
+ *   rt pane list [--json]                                         claude panes, presence joined
+ *   rt pane peek <pane> [--lines 8] [--json]                      the last lines of a pane's screen
+ *   rt pane spawn --cwd <path> [--account <a>] [--model <m>]
+ *                 [--effort <e>] [--prompt <text>] [--workspace <label>] [--json]
+ *   rt pane accounts [--json]                                     cswap accounts with headroom
+ *   rt pane directories [--q <text>] [--json]                     repos and worktrees for --cwd
+ *
+ * Every verb needs herdr; without it the daemon answers "herdr unavailable".
+ */
+import type { ChatPane, RtResponse } from "../packages/rt-client/src/index.ts";
+import { paneAccounts as paneAccountsRt, paneDirectories as paneDirectoriesRt, paneList as paneListRt, panePeek as panePeekRt, paneSpawn as paneSpawnRt } from "../packages/rt-client/src/index.ts";
+
+const FLAGS_WITH_VALUES = new Set(["--lines", "--cwd", "--account", "--model", "--effort", "--prompt", "--workspace", "--q", "--sock"]);
+
+function positional(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith("--")) {
+      if (FLAGS_WITH_VALUES.has(a)) i++;
+      continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
+function flagValue(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+function fail(msg: string): never {
+  console.error(`rt pane: ${msg}`);
+  process.exit(1);
+}
+
+function unwrap<T>(res: RtResponse<T>, label: string): T {
+  if (!res.ok || res.data === undefined) fail(res.error ?? `${label} failed`);
+  return res.data;
+}
+
+function opts(args: string[]) {
+  const sockPath = flagValue(args, "--sock");
+  return sockPath ? { sockPath } : {};
+}
+
+function renderPane(p: ChatPane): string {
+  const who = p.presence ? `${p.presence.handle} (${p.presence.status})` : "not signed in";
+  const where = [p.repo, p.branch].filter(Boolean).join(" · ");
+  const title = p.title && p.title !== p.presence?.handle ? ` · ${p.title}` : "";
+  const rooms = p.presence?.rooms.length ? `  #${p.presence.rooms.join(" #")}` : "";
+  return `${p.paneId.padEnd(8)} ${p.agentStatus.padEnd(8)} ${who.padEnd(22)} ${p.workspace}${title}${where ? `  ${where}` : ""}${rooms}`;
+}
+
+export async function paneList(args: string[]): Promise<void> {
+  const data = unwrap(await paneListRt(opts(args)), "pane list");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, panes: data.panes }));
+  if (data.panes.length === 0) return void console.log("no claude panes");
+  console.log(data.panes.map(renderPane).join("\n"));
+}
+
+export async function panePeek(args: string[]): Promise<void> {
+  const paneId = positional(args);
+  if (!paneId) fail("usage: rt pane peek <pane> [--lines 8]");
+  const linesRaw = flagValue(args, "--lines");
+  let lines: number | undefined;
+  if (linesRaw !== undefined) {
+    lines = Number(linesRaw);
+    if (!Number.isInteger(lines) || lines <= 0) fail(`--lines must be a positive integer (got "${linesRaw}")`);
+  }
+  const data = unwrap(await panePeekRt({ paneId, lines }, opts(args)), "pane peek");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, ...data }));
+  console.log(data.lines.join("\n"));
+}
+
+export async function paneSpawn(args: string[]): Promise<void> {
+  const cwd = flagValue(args, "--cwd");
+  if (!cwd) fail("usage: rt pane spawn --cwd <path> [--account <a>] [--model <m>] [--effort <e>] [--prompt <text>] [--workspace <label>]");
+  const data = unwrap(
+    await paneSpawnRt(
+      { cwd, account: flagValue(args, "--account"), model: flagValue(args, "--model"), effort: flagValue(args, "--effort"), prompt: flagValue(args, "--prompt"), workspace: flagValue(args, "--workspace") },
+      opts(args),
+    ),
+    "pane spawn",
+  );
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, ...data }));
+  console.log(`${data.ready ? "ready" : "not ready"}  ${renderPane(data.pane)}`);
+}
+
+export async function paneAccounts(args: string[]): Promise<void> {
+  const data = unwrap(await paneAccountsRt(opts(args)), "pane accounts");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, accounts: data.accounts }));
+  if (data.accounts.length === 0) return void console.log("no cswap accounts");
+  console.log(data.accounts.map((a) => `${String(a.slot).padStart(2)}: ${a.alias ?? a.email}${a.alias ? `  ${a.email}` : ""}${a.headroom ? `  ${a.headroom}` : ""}`).join("\n"));
+}
+
+export async function paneDirectories(args: string[]): Promise<void> {
+  const data = unwrap(await paneDirectoriesRt({ q: flagValue(args, "--q") }, opts(args)), "pane directories");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, directories: data.directories }));
+  console.log(data.directories.map((d) => `${d.path}  ${d.repo}${d.branch ? ` · ${d.branch}` : ""}`).join("\n"));
+}
+```
+
+Check how `commands/chat.ts` imports rt-client (it imports from `../packages/rt-client/src/client.ts` or the barrel); match it. The wrappers' `a.lines === undefined` handling means passing `undefined` fields is safe.
+
+- [ ] **Step 4: Register the group**
+
+In `lib/command-tree-def.ts`, add beside `secrets`:
+
+```ts
+  pane: {
+    description: "herdr panes as rt sees them: list with chat presence, peek, spawn claude, cswap accounts, directory suggestions",
+    subcommands: {
+      list: {
+        description: "Claude panes with their chat handle, status and rooms joined in (needs herdr)",
+        module: "./commands/pane.ts",
+        fn: "paneList",
+        args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON instead of one line per pane" }],
+      },
+      peek: {
+        description: "The last lines of a pane's visible screen",
+        module: "./commands/pane.ts",
+        fn: "panePeek",
+        args: [
+          { name: "Pane", type: "text", placeholder: "w7A:pY", hint: "herdr pane id" },
+          { name: "Lines", flag: "--lines", type: "text", optional: true, placeholder: "8", hint: "How many lines from the bottom" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+      spawn: {
+        description: "Open a herdr tab in a directory and start claude in it, optionally under a cswap account",
+        module: "./commands/pane.ts",
+        fn: "paneSpawn",
+        args: [
+          { name: "Directory", flag: "--cwd", type: "text", placeholder: "~/Documents/GitHub/chat", hint: "Absolute directory to start in" },
+          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Assured", hint: "cswap alias, email or slot" },
+          { name: "Model", flag: "--model", type: "text", optional: true, placeholder: "claude-fable-5", hint: "claude --model" },
+          { name: "Effort", flag: "--effort", type: "text", optional: true, placeholder: "high", hint: "claude --effort" },
+          { name: "Prompt", flag: "--prompt", type: "text", optional: true, placeholder: "read AGENTS.md", hint: "Typed once claude is idle" },
+          { name: "Workspace", flag: "--workspace", type: "text", optional: true, placeholder: "chat", hint: "herdr workspace label; default chat.herdrWorkspace" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+      accounts: {
+        description: "cswap accounts with rate-limit headroom, for spawn --account",
+        module: "./commands/pane.ts",
+        fn: "paneAccounts",
+        args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" }],
+      },
+      directories: {
+        description: "Repos and worktrees rt knows, as suggestions for spawn --cwd",
+        module: "./commands/pane.ts",
+        fn: "paneDirectories",
+        args: [
+          { name: "Filter", flag: "--q", type: "text", optional: true, placeholder: "chat", hint: "Substring of the path" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+    },
+  },
+```
+
+In `lib/module-registry.ts`, add `"./commands/pane.ts": () => import("../commands/pane.ts"),`.
+
+- [ ] **Step 5: Run the tests and regenerate the docs**
+
+Run: `bun test commands/__tests__/pane.test.ts && bun scripts/gen-docs.ts && bun scripts/check-docs.ts`
+Expected: tests pass; docs regenerate; check passes. Then `rt pane list --json` against the live machine as a smoke test (`bun cli.ts pane list --json`): either rows or `herdr unavailable`, never a stack trace.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add commands/pane.ts commands/__tests__/pane.test.ts lib/command-tree-def.ts lib/module-registry.ts website/docs/reference
+git commit -m "cli: rt pane list, peek, spawn, accounts, directories"
+```
+
+---
+
+### Task 9: `rt chat invite` and `rt chat read --last N`
+
+**Files:**
+- Modify: `commands/chat.ts` (`FLAGS_WITH_VALUES`, `runRead`, new `runInvite`, `VERBS`, `USAGE`)
+- Modify: `lib/command-tree-def.ts` (the `chat` entry's Verb placeholder and a `--last`/`--note` arg row)
+- Test: `commands/__tests__/chat.test.ts`
+- Regenerate docs.
+
+**Interfaces:**
+- Produces: `rt chat read <room> --last N [--json]`, `rt chat invite <pane> --room <room> [--note <text>] [--json]`.
+- Consumes: `chatMessages`, `chatMark`, `chatInvite` wrappers; `readChatSession`/`currentSessionId` from `lib/chat-session.ts`; `getSetting("chat.humanHandle")`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `commands/__tests__/chat.test.ts` (its fake daemon dispatches to the real chat handlers; add a `canned` map consulted before the handlers so `chat:invite` can be scripted: in the `fetch`, `if (cmd in canned) return Response.json(canned[cmd]);` with `let canned: Record<string, unknown> = {}` reset in `beforeEach`):
+
+```ts
+test("read --last N shows the newest N messages regardless of the cursor, then marks read", async () => {
+  await runChat(["join", "build", "--as", "alice"]);
+  await runChat(["post", "build", "seed one", "--as", "alice"]);
+  await runChat(["post", "build", "seed two", "--as", "alice"]);
+  await runChat(["join", "build", "--as", "bob"]);
+  const nothing = await runChat(["read", "build", "--as", "bob", "--json"]);
+  expect(JSON.parse(nothing).rooms[0]?.messages ?? []).toHaveLength(0);
+  const last = await runChat(["read", "build", "--last", "5", "--as", "bob", "--json"]);
+  expect(JSON.parse(last).rooms[0].messages.map((m: { body: string }) => m.body)).toEqual(["seed one", "seed two"]);
+  const again = await runChat(["read", "build", "--as", "bob", "--json"]);
+  expect(JSON.parse(again).rooms[0]?.messages ?? []).toHaveLength(0);
+});
+
+test("read --last refuses --since and a non-positive N", async () => {
+  await runChat(["join", "build", "--as", "alice"]);
+  expect((await runChatRaw(["read", "build", "--last", "5", "--since", "5m", "--as", "alice"])).code).toBe(1);
+  expect((await runChatRaw(["read", "build", "--last", "0", "--as", "alice"])).code).toBe(1);
+});
+
+test("read --last requires a room", async () => {
+  expect((await runChatRaw(["read", "--last", "5", "--as", "alice"])).code).toBe(1);
+});
+
+test("invite sends the pane, room, note, the human handle when not signed in, and the caller pane", async () => {
+  canned = { "chat:invite": { ok: true, data: { paneId: "w1:p1", delivered: "accepted" } } };
+  process.env.HERDR_PANE_ID = "w9:p9";
+  const out = await runChat(["invite", "w1:p1", "--room", "build", "--note", "take vite"]);
+  expect(out).toContain("accepted");
+  const sent = seen.find((s) => s.cmd === "chat:invite")!;
+  expect(sent.payload).toEqual({ paneId: "w1:p1", room: "build", note: "take vite", from: "matt", callerPane: "w9:p9" });
+});
+
+test("invite uses the session's own handle when signed in, and reports refusals with exit 0", async () => {
+  await runChat(["sign-in", "--as", "carol", "--session", "sess-c", "--no-room"]);
+  canned = { "chat:invite": { ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "at a prompt" } } };
+  const r = await runChatRaw(["invite", "w1:p1", "--room", "build", "--session", "sess-c"]);
+  expect(r.code).toBe(0);
+  expect(r.stdout).toContain("refused: at a prompt");
+  expect((seen.find((s) => s.cmd === "chat:invite")!.payload as { from: string }).from).toBe("carol");
+});
+
+test("invite requires a pane and --room", async () => {
+  expect((await runChatRaw(["invite"])).code).toBe(1);
+  expect((await runChatRaw(["invite", "w1:p1"])).code).toBe(1);
+});
+```
+
+The harness needs `seen` recorded in its `fetch` (`seen.push({ cmd, payload })`, declared beside `canned`). Sign-in in this suite may need `CLAUDE_CODE_SESSION_ID` unset (the suite already clears it) and `--session` given, as above.
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bun test commands/__tests__/chat.test.ts`
+Expected: the six new tests FAIL (`unknown verb "invite"`; `--last` ignored so the read shows nothing).
+
+- [ ] **Step 3: Implement**
+
+In `commands/chat.ts`:
+
+1. Add `"--last"`, `"--note"` to `FLAGS_WITH_VALUES`.
+2. In `runRead`, after `sinceMs` parsing:
+
+```ts
+  const lastRaw = flagValue(args, "--last");
+  if (lastRaw !== undefined) {
+    if (sinceRaw !== undefined) fail("--last and --since are mutually exclusive");
+    if (!room) fail("--last needs a room");
+    const n = Number(lastRaw);
+    if (!Number.isInteger(n) || n <= 0) fail(`--last must be a positive integer (got "${lastRaw}")`);
+    const page = unwrap(await chatMessages({ room, limit: n }, sockOpts(args)), "read");
+    unwrap(await chatMark({ handle, room }, sockOpts(args)), "mark");
+    const rooms = [{ room, messages: page.messages }];
+    if (args.includes("--json")) {
+      console.log(JSON.stringify({ ok: true, rooms }));
+      return;
+    }
+    const headingFor = await dmHeadingsFor(handle);
+    console.log(renderReadRooms(rooms, args.includes("--full"), headingFor));
+    return;
+  }
+```
+
+   where `sockOpts(args)` is a small helper `const sockPath = flagValue(args, "--sock"); return sockPath ? { sockPath } : {};` (chatTail already builds this inline; hoist it). Confirm `chatMessages` returns messages oldest-first; if it returns newest-first, reverse before rendering so `--last` reads top to bottom like a plain read. Import `chatMessages` beside `chatMark`.
+3. Add `runInvite`:
+
+```ts
+async function runInvite(args: string[]): Promise<void> {
+  const paneId = positional(args);
+  if (!paneId) fail("usage: rt chat invite <pane> --room <room> [--note <text>]");
+  const room = flagValue(args, "--room");
+  if (!room) fail("--room is required");
+  requireValidName("room", room);
+  const note = flagValue(args, "--note");
+  const session = readChatSession(currentSessionId(args));
+  const from = session?.handle ?? getSetting<string>("chat.humanHandle").value;
+  const callerPane = process.env.HERDR_PANE_ID;
+  const res = await chatInvite({ paneId, room, note, from, callerPane }, sockOpts(args));
+  const data = unwrap(res, "invite");
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ok: true, ...data }));
+    return;
+  }
+  console.log(data.delivered === "refused" ? `${paneId}: refused: ${data.reason ?? "unknown"}` : `${paneId}: ${data.delivered}`);
+}
+```
+
+   Check the exact names exported by `lib/chat-session.ts` (`readChatSession`, `currentSessionId`); `commands/chat.ts` already imports them for `resolveHandle`. `readChatSession` takes the session id (undefined when there is none) and returns `null`/`undefined` when no file exists.
+4. Add `invite: runInvite` to `VERBS` and `invite` to `USAGE`.
+5. In `lib/command-tree-def.ts`'s `chat` entry, add `invite` to the Verb placeholder and two arg rows: `{ name: "Last", flag: "--last", type: "text", optional: true, placeholder: "10", hint: "read: the newest N messages regardless of your cursor, then mark read" }` and `{ name: "Note", flag: "--note", type: "text", optional: true, placeholder: "you own the vite side", hint: "invite: a one-line note appended to the /chat:join command" }`, plus `{ name: "Pane", ... }` only if the tree's Room arg cannot double for the pane id (its hint already says "the target handle for dm"; extend it with "the pane id for invite").
+
+- [ ] **Step 4: Run the tests and regenerate the docs**
+
+Run: `bun test commands/__tests__/chat.test.ts && bun scripts/gen-docs.ts && bun scripts/check-docs.ts`
+Expected: all pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add commands/chat.ts commands/__tests__/chat.test.ts lib/command-tree-def.ts website/docs/reference
+git commit -m "cli: rt chat invite, rt chat read --last N"
+```
+
+---
+
+### Task 10: `lib/herdr-agent.ts`: `herdr wait` became `herdr agent wait`
+
+**Files:**
+- Modify: `lib/herdr-agent.ts:88-93, 117-124, 126-138`
+- Modify: `lib/__tests__/herdr-agent.test.ts` (lines 147-219, the `wait-agent-status` keys and argv assertions)
+
+**Interfaces:** unchanged (`startClaude`, `waitAgentWorking`, `waitAgentIdle` keep their signatures; callers `lib/repo-index.ts` and `lib/rebase-escalation.ts` untouched).
+
+- [ ] **Step 1: Update the tests first**
+
+In `lib/__tests__/herdr-agent.test.ts`, every `setExit("wait-agent-status", ...)` / `setExitSequence("wait-agent-status", ...)` becomes the key `"agent-wait"`, and every assertion on the recorded argv that starts with `wait agent-status <pane> --status <s> --timeout <ms>` becomes `agent wait <pane> --until <s> --timeout <ms>`.
+
+Run: `bun test lib/__tests__/herdr-agent.test.ts`
+Expected: FAIL (the code still calls `wait agent-status`).
+
+- [ ] **Step 2: Rename the three call sites**
+
+In `lib/herdr-agent.ts`, each argv `["wait", "agent-status", pane.paneId, "--status", <s>, "--timeout", <ms>]` becomes `["agent", "wait", pane.paneId, "--until", <s>, "--timeout", <ms>]` (herdr 0.7.5 replaced the top-level `wait` group; `agent wait --until` is exact-match, so pass exactly the one status each site waited for).
+
+- [ ] **Step 3: Run the tests**
+
+Run: `bun test lib/__tests__/herdr-agent.test.ts lib/__tests__`
+Expected: pass.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add lib/herdr-agent.ts lib/__tests__/herdr-agent.test.ts
+git commit -m "herdr-agent: herdr agent wait replaces the removed top-level wait"
+```
+
+---
+
+### Task 11: skill docs
+
+**Files:**
+- Modify: `skills/rt-chat/SKILL.md`
+
+- [ ] **Step 1: Edit the skill**
+
+1. Frontmatter `description`: append `, or when asked to put you and another agent into a room together (recruiting through herdr).` before the closing quote-less end of the line.
+2. In `## Reading`, add a bullet after the `--since` one:
+
+   ```markdown
+   - `rt chat read <room> --last N` shows the newest N messages of a room
+     regardless of your cursor, then marks the room read. Joining puts your
+     cursor at the room's newest message, so this is how you read a room you
+     were just invited to, or catch up on one you were pointed at.
+   ```
+3. In the verb table, add after the `rt chat post` row:
+
+   ```markdown
+   | `rt chat invite <pane> --room <room> [--note <text>]` | type `/chat:join <room>` into one herdr pane, so that agent joins itself; needs herdr. Reports `accepted` \| `queued` \| `refused`; never changes membership. The note is attributed to you |
+   ```
+   and after the table a short paragraph: `rt pane list`, `rt pane peek <pane>`, `rt pane spawn --cwd <path> [...]`, `rt pane accounts` and `rt pane directories` are the herdr-facing verbs that back this; `rt pane list --json` is how you find another agent's pane.
+4. Add a new section before `## Announce before you take something`:
+
+   ````markdown
+   ## Recruiting another agent
+
+   When Matt says "add you and the agent working on foo into a room so you can
+   coordinate" (or anything that means: put me and another pane in a room),
+   this is the flow. It needs herdr; every step that touches another pane is
+   gated on a form.
+
+   1. `rt pane list --json`. If it errors with `herdr unavailable`, say this
+      needs herdr and stop.
+   2. Match *foo* against each pane's `title`, `repo`, `branch`, `cwd` and
+      `presence.handle`. Exclude your own pane (`HERDR_PANE_ID`) and panes
+      whose `presence.rooms` already includes the target room.
+   3. **Always a form.** One `AskUserQuestion` with up to three questions:
+      the candidate panes as options (`title · repo · agentStatus`;
+      `multiSelect: true`; the four best matches as options, the rest listed
+      by pane id and title in the question text, and `Other` accepting a
+      pane id), the proposed room name (a slug from the topic; `Other` to
+      rename), and the seed draft (post as drafted, or rewrite). Touch no pane
+      before the form returns.
+   4. Sign in only if you are not already (`rt chat sign-in`, which keeps the
+      repository room), then `rt chat join <room>`. Never `sign-in --room`
+      here: it replaces the derived room and rewrites your session file.
+      Post the seed as yourself with a heredoc. Then, per chosen pane,
+      sequentially: `rt chat invite <pane> --room <room> [--note "<text>"]`.
+   5. Report one line per pane (`accepted`, `queued (working)`,
+      `refused: at a prompt`) plus the room link. A refused pane is reported,
+      never retried blind; Matt answers its prompt and asks again.
+   ````
+
+- [ ] **Step 2: Check and commit**
+
+Run: `grep -n '—\|–' skills/rt-chat/SKILL.md | head` (the file already contains em dashes from earlier authors; do not add new ones in the inserted text: `grep -c` before and after must match).
+
+```bash
+git add skills/rt-chat/SKILL.md
+git commit -m "rt-chat skill: read --last, rt chat invite, the rt pane group, recruiting flow"
+```
+
+---
+
+### Task 12: full suite, version bump, PR
+
+**Files:**
+- Modify: `packages/rt-client/package.json` (`0.6.1` to `0.6.2`)
+
+- [ ] **Step 1: The whole suite**
+
+Run: `bun test lib commands packages scripts && bun scripts/check-docs.ts`
+Expected: green.
+
+- [ ] **Step 2: Bump rt-client**
+
+Set `"version": "0.6.2"` in `packages/rt-client/package.json` (additive surface; the viewer's `^0.6` pin picks it up), run `cd packages/rt-client && bun run build && cd ../.. && bun test packages/rt-client/test`, and grep the built bundle for the new verbs: `grep -c 'pane:spawn\|chat:invite' packages/rt-client/dist/index.js` must be at least 2.
+
+```bash
+git add packages/rt-client/package.json
+git commit -m "rt-client: 0.6.2, pane and invite wrappers"
+```
+
+- [ ] **Step 3: Rebase and open the PR**
+
+```bash
+git fetch origin && git rebase origin/main
+bun test lib commands packages scripts
+git push -u origin spec/rt-chat-invite
+gh pr create --title "rt chat invite: pane verbs, chat:invite, read --last" --body-file - <<'EOF'
+## rt chat invite, part 1: the rt primitives
+
+Adds the herdr-facing verbs the chat viewer's pane picker and the recruiting flow stand on. Spec: docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md.
+
+### What changed
+
+**herdr client** (`lib/herdr/`)
+
+- NDJSON unix-socket client, one connection per call, with a fake server for tests
+- 5s plain timeout; waiting calls get their own budget plus 5s
+
+**Daemon verbs** (`lib/daemon/handlers/pane.ts`, `chat.ts`)
+
+- `pane:list` joins herdr's claude panes to presence by session id, pane id as fallback
+- `pane:peek`, `pane:accounts` (cswap list, async), `pane:directories` (repo index plus worktrees, no git)
+- `pane:spawn` opens a tab in `chat.herdrWorkspace`, starts claude, waits for idle, answers the trust dialog once
+- `chat:invite` types `/chat:join <room>` into a pane; `accepted`, `queued` or `refused`
+
+**CLI and client**
+
+- `rt pane list|peek|spawn|accounts|directories`, `rt chat invite`, `rt chat read --last N`
+- rt-client 0.6.2: six wrappers, five types, `chat.herdrWorkspace`
+
+**Also**
+
+- `lib/herdr-agent.ts` calls `herdr agent wait` (the top-level `wait` went away in herdr 0.7.5)
+- `lib/repo-for-cwd.ts` extracted from `commands/chat.ts` so the daemon resolves a cwd without git
+
+### Follow-up
+
+- Publishing 0.6.2 is release-class: from `main`, after merge, never `--ignore-scripts`.
+- Migrating `lib/herdr-agent.ts` onto the socket client is out of scope (spec, Out of scope).
+EOF
+```
+
+Publishing to npm is not part of this plan's automated steps: it is a push-class side effect done from `main` after merge (CLAUDE.md). Stop and ask before `npm publish`.
+
+---
+
+## Self-review
+
+**Spec coverage.** Gate and socket timeouts: Task 1. `pane:list` shape, session-id join, pane-id fallback, sort, presence-row-first repo/branch with async git and MAT-222: Tasks 2 and 3. `pane:peek`: Task 3. `pane:accounts`, `pane:directories`: Task 4. `chat.herdrWorkspace`, `pane:spawn` (workspace create-or-reuse, tab, launch line with cswap, registration poll, idle wait, trust dialog once, prompt, `ready: false` returns the pane): Task 5. `chat:invite` (one-line text with attributed note, `agent.get` first, queued/accepted/refused, nudge, `callerPane`): Task 6. rt-client wrappers with `timeoutMs` 90s/30s and types: Task 7. `rt pane` group: Task 8. `rt chat invite` and `read --last` via `chat:messages` plus `chat:mark`, exclusive with `--since`: Task 9. `herdr agent wait` rename with callers untouched: Task 10. Skill verb table, `--last`, `rt pane` pointer, recruiting section with the four-option form rule: Task 11. Publish rt-client: Task 12 (gated on asking).
+
+**Placeholders.** None; every step carries code or exact commands. The one deliberate defer is `npm publish`, which the plan says to ask about.
+
+**Type consistency.** `ChatPane`, `PaneAccount`, `PaneDirectory`, `InviteResult`, `AgentStatus` are declared once in Task 3/4/6 and referenced by those names in Tasks 5, 7, 8. `herdrRequest` / `HerdrResult` / `waitTimeout` / `HERDR_UNAVAILABLE` (Task 1) are the names Tasks 3 to 6 import. `paneRow`, `presenceMaps`, `herdrError` are exported from `pane.ts` in Task 3 and used in Tasks 5 and 6. The CLI functions in Task 8 are `paneList`/`panePeek`/`paneSpawn`/`paneAccounts`/`paneDirectories`, matching `command-tree-def.ts`'s `fn` fields.
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
new file mode 100644
index 00000000..3d741a12
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
@@ -0,0 +1,1919 @@
+# rt chat invite, part 2: the viewer (chat)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** From the chat viewer, create a room, seed it, and invite or spawn herdr panes into it through a standalone pane picker; refresh members as they arrive; ship the artboards and audit that pin the new UI.
+
+**Architecture:** The Hono server gains `/api/panes*` routes over rt-client's new pane wrappers and two `POST` chat routes (`rooms`, `invite`), all with fixtures. The client gains `PanePicker` (a provider-hosted modal with a promise-returning `usePanePicker()` hook, owning fetch, filter, sort, peek, selection and the New pane form), `NewRoomModal` (name, seed, wake mode, picked panes with notes), a `+` in the rooms rail, `add agents` in the page bar, a `who` refetch on `chat/<room>/msg` frames, and a notice row at the transcript's edge. The design artboards fold into `design/build.py`, and `audit.mjs` gains targets for every new component.
+
+**Tech Stack:** Bun + Hono server, React 19 + Mantine 9.5 through the mantine-kit facades (`@ui/*`), vitest + Testing Library, `@mattstack/rt-client` 0.6.2, the design toolchain (`build.py`, `extract-spec.py`, `audit.mjs`, Fast Browser).
+
+**Spec:** `~/Documents/GitHub/repo-tools-chat-invite/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md` (sections "Data flow", "Web viewer", "Failure modes", "Testing").
+
+## Global Constraints
+
+- Work in a worktree: `git -C ~/Documents/GitHub/chat worktree add ~/Documents/GitHub/chat-invite -b feat/pane-invite && cd ~/Documents/GitHub/chat-invite && bun install`. Never in `~/Documents/GitHub/chat` itself.
+- Import walls (AGENTS.md, enforced by eslint): app code under `src/app/**` imports only `@ui/*`; code under `src/ui/**` may import `@mantine/core` directly except `Table`, `TextInput`, `CopyButton`, which come from `@ui/core`. Icons only through `@ui/icons` (`<Icon name="..." />`). Notifications through `@ui/notifications`.
+- Mantine props come from the docs (`docs/mantine-llms.txt` or the `mantine` MCP), never from memory.
+- No colour literals: `var(--tk-*)`, `var(--mantine-color-*)`, or `color-mix` off them, as `Composer.tsx:23-52` and `RoomRail.tsx:17-22` do. The values that matter are the artboards' (7.2px, 9.6px, 11.2px, 10.56px, 12.16px, 34px rows, 44px phone controls, 8px dots); the audit checks them.
+- Paths render as `headTruncatePath(cwd)` from `src/ui/presence-bits.tsx` (`…/leaf`), never `direction: rtl`.
+- Every request body is hand-parsed with `c.req.json()` in a try/catch (never `validator('json')`), and rt-client is branched on `ok`, never caught, exactly as `src/server/chat.ts:238-282`.
+- `GET /api/panes` reports herdr absence as `{ available: false, panes: [] }` with 200. Every other rt failure is a 502 with `{ error }`.
+- No em dashes or en dashes in new code, copy, comments, or commit messages (use `·`, `:` or a plain sentence). Comments only for constraints the code cannot show.
+- Tests: `bunx vitest run <file>` while working; `bun run typecheck && bun run lint && bunx vitest run` before every commit. `bun run build` before the PR.
+- Commit after every task with a short imperative message.
+
+---
+
+### Task 1: worktree and the rt-client with pane wrappers
+
+**Files:**
+- Modify: `package.json` (`@mattstack/rt-client` pin), `bun.lock`
+
+**Interfaces:**
+- Consumes: part 1's rt-client (`paneList`, `panePeek`, `paneSpawn`, `paneAccounts`, `paneDirectories`, `chatInvite`, types `ChatPane`, `AgentStatus`, `PaneAccount`, `PaneDirectory`, `InviteResult`).
+
+- [ ] **Step 1: Create the worktree**
+
+```bash
+git -C ~/Documents/GitHub/chat worktree add ~/Documents/GitHub/chat-invite -b feat/pane-invite
+cd ~/Documents/GitHub/chat-invite && bun install
+```
+
+- [ ] **Step 2: Point at the rt-client that has the wrappers**
+
+If `npm view @mattstack/rt-client version` prints `0.6.2` or later: `bun add @mattstack/rt-client@^0.6.2`. Otherwise (part 1 merged but not yet published) build it locally and link it for the duration of this plan:
+
+```bash
+(cd ~/Documents/GitHub/repo-tools-chat-invite/packages/rt-client && bun run build)
+bun add @mattstack/rt-client@file:../repo-tools-chat-invite/packages/rt-client
+```
+
+Verify: `grep -c 'paneSpawn\|chatInvite' node_modules/@mattstack/rt-client/dist/index.d.ts` prints at least 2, and `grep -c 'pane:spawn' node_modules/@mattstack/rt-client/dist/index.js` prints at least 1 (types without runtime is the failure mode CLAUDE.md in repo-tools warns about).
+
+- [ ] **Step 3: Baseline**
+
+Run: `bun run typecheck && bunx vitest run`
+Expected: green before any change.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add package.json bun.lock
+git commit -m "deps: rt-client with the pane and invite wrappers"
+```
+
+(If the `file:` form was used, Task 10 swaps it back to a published pin before the PR.)
+
+---
+
+### Task 2: fixtures for panes, accounts, directories, invites
+
+**Files:**
+- Modify: `src/server/fixtures.ts`
+- Test: `src/server/fixtures.test.ts`
+
+**Interfaces:**
+- Produces: `fixturePanes(): ChatPane[]`, `fixtureAccounts(): PaneAccount[]`, `fixtureDirectories(q?: string): PaneDirectory[]`, `fixtureInvite(paneId: string): InviteResult`, `fixtureSpawn(cwd: string): { pane: ChatPane; ready: boolean }`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/server/fixtures.test.ts`:
+
+```ts
+import { fixtureAccounts, fixtureDirectories, fixtureInvite, fixturePanes, fixtureSpawn } from './fixtures';
+
+test('the pane fixtures cover every row state the picker artboard draws', () => {
+  const panes = fixturePanes();
+  const states = new Set(panes.map(p => (p.presence ? p.presence.status : 'none')));
+  expect(states).toEqual(new Set(['live', 'idle', 'deaf', 'none']));
+  expect(panes.some(p => p.agentStatus === 'working')).toBe(true);
+  expect(panes.some(p => p.agentStatus === 'blocked')).toBe(true);
+  expect(panes.some(p => p.presence?.rooms.includes('build'))).toBe(true);
+  expect(panes.every(p => p.paneId && p.workspace)).toBe(true);
+});
+
+test('invite fixtures answer per pane: a working pane queues, a blocked one refuses', () => {
+  const working = fixturePanes().find(p => p.agentStatus === 'working')!;
+  const blocked = fixturePanes().find(p => p.agentStatus === 'blocked')!;
+  const idle = fixturePanes().find(p => p.agentStatus === 'idle' && !p.presence)!;
+  expect(fixtureInvite(working.paneId).delivered).toBe('queued');
+  expect(fixtureInvite(blocked.paneId)).toMatchObject({ delivered: 'refused', reason: 'at a prompt' });
+  expect(fixtureInvite(idle.paneId).delivered).toBe('accepted');
+});
+
+test('directories filter by substring; accounts carry headroom; spawn returns a ready pane', () => {
+  expect(fixtureDirectories('assured').every(d => d.path.includes('assured'))).toBe(true);
+  expect(fixtureDirectories().length).toBeGreaterThan(fixtureDirectories('assured').length);
+  expect(fixtureAccounts()[0]).toMatchObject({ slot: 1, alias: 'Assured' });
+  expect(fixtureSpawn('/Users/matt/Documents/GitHub/chat')).toMatchObject({ ready: true, pane: { cwd: '/Users/matt/Documents/GitHub/chat', agentStatus: 'idle' } });
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/server/fixtures.test.ts`
+Expected: FAIL, the named exports do not exist.
+
+- [ ] **Step 3: Add the fixtures**
+
+In `src/server/fixtures.ts`, add the type imports `ChatPane, InviteResult, PaneAccount, PaneDirectory` to the existing `import type { ... } from '@mattstack/rt-client'`, and append (the table is the mockup's `PANES`, so the picker fixture matches the artboard):
+
+```ts
+/** The picker artboard's rows: one per state it draws. Keep in step with
+    design/build.py's PANES table. */
+export function fixturePanes(): ChatPane[] {
+  return [
+    { paneId: 'w3f:p2', workspace: 'repo-tools', title: 'fred', cwd: '/Users/matt/Documents/GitHub/repo-tools/.claude/worktrees/rt-63-68-locate', repo: 'repo-tools', branch: 'rt-63-68-locate', agentStatus: 'working', sessionId: 'fixture-fred', presence: { handle: 'fred', status: 'live', rooms: ['repo-tools'] } },
+    { paneId: 'w3f:p4', workspace: 'chat', title: 'meg', cwd: '/Users/matt/Documents/GitHub/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-meg', presence: { handle: 'meg', status: 'live', rooms: ['build', 'chat'] } },
+    { paneId: 'w9c:p3', workspace: 'gitq', title: 'june', cwd: '/Users/matt/Documents/GitHub/gitq', repo: 'gitq', branch: 'main', agentStatus: 'blocked', sessionId: 'fixture-june', presence: { handle: 'june', status: 'idle', rooms: ['gitq'] } },
+    { paneId: 'w2d:p1', workspace: 'deck', title: 'otis', cwd: '/Users/matt/Documents/GitHub/deck', repo: 'deck', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-otis', presence: { handle: 'otis', status: 'deaf', rooms: ['deck'] } },
+    { paneId: 'w7A:pY', workspace: 'assured', title: 'Evaluate house codegen plugin for bundle optimization', cwd: '/Users/matt/Documents/GitHub/assured', repo: 'assured', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-assured' },
+    { paneId: 'wB1:p1', workspace: 'mr-board', title: 'Fix invite onboarding modal focus trap', cwd: '/Users/matt/Documents/GitHub/mr-board-wt-invite-onboarding', repo: 'mr-board', branch: 'invite-onboarding', agentStatus: 'working', sessionId: 'fixture-mrboard' },
+  ];
+}
+
+export function fixturePeek(paneId: string): string[] {
+  if (paneId === 'w7A:pY') {
+    return ['⏺ Read(src/plugins/house-codegen/index.ts)', '  ⎿  Read 212 lines', '⏺ The plugin emits one chunk per island; the split itself', '  happens in vite manualChunks, not here. Checking that next.', '❯ '];
+  }
+  return ['❯ '];
+}
+
+export function fixtureAccounts(): PaneAccount[] {
+  return [{ slot: 1, email: 'matthew.goodwin@assured.claims', alias: 'Assured', headroom: '5h 0% · 7d 40% · Fable 35%' }];
+}
+
+export function fixtureDirectories(q?: string): PaneDirectory[] {
+  const all: PaneDirectory[] = [
+    { path: '/Users/matt/Documents/GitHub/assured', repo: 'assured', branch: 'main' },
+    { path: '/Users/matt/Documents/GitHub/assured-wt-codegen-split', repo: 'assured', branch: 'perf/codegen-split' },
+    { path: '/Users/matt/Documents/GitHub/repo-tools', repo: 'repo-tools', branch: 'main' },
+    { path: '/Users/matt/Documents/GitHub/chat', repo: 'chat', branch: 'main' },
+  ];
+  const needle = q?.toLowerCase();
+  return needle ? all.filter(d => d.path.toLowerCase().includes(needle)) : all;
+}
+
+/** The three outcomes the invite flow renders, keyed off the pane's state. */
+export function fixtureInvite(paneId: string): InviteResult {
+  const pane = fixturePanes().find(p => p.paneId === paneId);
+  if (!pane) return { paneId, delivered: 'refused', reason: 'not a claude pane' };
+  if (pane.agentStatus === 'blocked') return { paneId, delivered: 'refused', reason: 'at a prompt' };
+  if (pane.agentStatus === 'working') return { paneId, delivered: 'queued' };
+  return { paneId, delivered: 'accepted' };
+}
+
+let spawned = 0;
+export function fixtureSpawn(cwd: string): { pane: ChatPane; ready: boolean } {
+  spawned += 1;
+  const leaf = cwd.split('/').filter(Boolean).at(-1) ?? 'pane';
+  return {
+    ready: true,
+    pane: { paneId: `wC2:p${spawned}`, workspace: 'chat', title: 'claude', cwd, repo: leaf, branch: 'main', agentStatus: 'idle' },
+  };
+}
+```
+
+- [ ] **Step 4: Run the tests**
+
+Run: `bunx vitest run src/server/fixtures.test.ts`
+Expected: pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/fixtures.ts src/server/fixtures.test.ts
+git commit -m "fixtures: panes, peek, accounts, directories, invite and spawn answers"
+```
+
+---
+
+### Task 3: the `/api/panes*` routes
+
+**Files:**
+- Create: `src/server/panes.ts`
+- Modify: `src/server/app.ts` (mount)
+- Test: `src/server/panes.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `GET /api/panes` → `{ available: boolean; panes: ChatPane[] }`
+  - `GET /api/panes/accounts` → `{ accounts: PaneAccount[] }`
+  - `GET /api/panes/directories?q=` → `{ directories: PaneDirectory[] }`
+  - `GET /api/panes/:id/peek?lines=8` → `{ paneId, lines }`
+  - `POST /api/panes` `{ cwd, account?, model?, effort?, prompt?, workspace? }` → `{ pane, ready }`; 400 on a missing/relative `cwd` or an unknown-account error from rt.
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `src/server/panes.test.ts`:
+
+```ts
+import { beforeEach, expect, test, vi } from 'vitest';
+
+vi.mock('@mattstack/rt-client', () => ({
+  chatRooms: vi.fn(),
+  chatWho: vi.fn(),
+  chatMessages: vi.fn(),
+  chatMark: vi.fn(),
+  chatBuddies: vi.fn(),
+  chatJoin: vi.fn(),
+  chatPost: vi.fn(),
+  chatDm: vi.fn(),
+  chatInvite: vi.fn(),
+  paneList: vi.fn(),
+  panePeek: vi.fn(),
+  paneSpawn: vi.fn(),
+  paneAccounts: vi.fn(),
+  paneDirectories: vi.fn(),
+  daemonHealth: vi.fn(),
+  getSetting: vi.fn(() => ({ value: 'matt' })),
+}));
+const rt = await import('@mattstack/rt-client');
+const { app } = await import('./app');
+
+beforeEach(() => vi.resetAllMocks());
+
+const PANE = { paneId: 'w1:p1', workspace: 'chat', agentStatus: 'idle' as const };
+
+test('GET /api/panes passes the rows through', async () => {
+  vi.mocked(rt.paneList).mockResolvedValueOnce({ ok: true, data: { panes: [PANE] } });
+  const res = await app.request('/api/panes');
+  expect(res.status).toBe(200);
+  expect(await res.json()).toEqual({ available: true, panes: [PANE] });
+});
+
+test('GET /api/panes reports herdr absence as available:false with 200, and other failures as 502', async () => {
+  vi.mocked(rt.paneList).mockResolvedValueOnce({ ok: false, error: 'herdr unavailable: no socket at /x' });
+  const absent = await app.request('/api/panes');
+  expect(absent.status).toBe(200);
+  expect(await absent.json()).toEqual({ available: false, panes: [] });
+  vi.mocked(rt.paneList).mockResolvedValueOnce({ ok: false, error: 'rt daemon unreachable at /x/rt.sock: ECONNREFUSED' });
+  expect((await app.request('/api/panes')).status).toBe(502);
+});
+
+test('GET /api/panes/:id/peek forwards lines and returns the screen', async () => {
+  vi.mocked(rt.panePeek).mockResolvedValueOnce({ ok: true, data: { paneId: 'w1:p1', lines: ['❯ '] } });
+  const res = await app.request('/api/panes/w1:p1/peek?lines=4');
+  expect(res.status).toBe(200);
+  expect(rt.panePeek).toHaveBeenCalledWith({ paneId: 'w1:p1', lines: 4 }, expect.anything());
+  expect(await res.json()).toEqual({ paneId: 'w1:p1', lines: ['❯ '] });
+});
+
+test('GET /api/panes/accounts and /directories pass through; directories forwards q', async () => {
+  vi.mocked(rt.paneAccounts).mockResolvedValueOnce({ ok: true, data: { accounts: [] } });
+  vi.mocked(rt.paneDirectories).mockResolvedValueOnce({ ok: true, data: { directories: [] } });
+  expect((await app.request('/api/panes/accounts')).status).toBe(200);
+  expect((await app.request('/api/panes/directories?q=chat')).status).toBe(200);
+  expect(rt.paneDirectories).toHaveBeenCalledWith({ q: 'chat' }, expect.anything());
+});
+
+test('POST /api/panes spawns with every field and answers pane plus ready', async () => {
+  vi.mocked(rt.paneSpawn).mockResolvedValueOnce({ ok: true, data: { pane: PANE, ready: true } });
+  const res = await app.request('/api/panes', {
+    method: 'POST',
+    body: JSON.stringify({ cwd: '/repos/chat', account: 'Assured', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }),
+  });
+  expect(res.status).toBe(200);
+  expect(rt.paneSpawn).toHaveBeenCalledWith({ cwd: '/repos/chat', account: 'Assured', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }, expect.anything());
+  expect(await res.json()).toEqual({ pane: PANE, ready: true });
+});
+
+test('POST /api/panes rejects a missing or relative cwd, and maps an unknown account to 400', async () => {
+  expect((await app.request('/api/panes', { method: 'POST', body: JSON.stringify({}) })).status).toBe(400);
+  expect((await app.request('/api/panes', { method: 'POST', body: JSON.stringify({ cwd: 'relative' }) })).status).toBe(400);
+  vi.mocked(rt.paneSpawn).mockResolvedValueOnce({ ok: false, error: 'unknown cswap account "nobody"' });
+  const res = await app.request('/api/panes', { method: 'POST', body: JSON.stringify({ cwd: '/x', account: 'nobody' }) });
+  expect(res.status).toBe(400);
+  expect(await res.json()).toEqual({ error: 'unknown cswap account "nobody"' });
+});
+```
+
+Also add `chatInvite`, `paneList`, `panePeek`, `paneSpawn`, `paneAccounts`, `paneDirectories` to the `vi.mock` factory in `src/server/chat.test.ts` (the app now imports them, and a missing mock export is `undefined` at call time).
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/server/panes.test.ts`
+Expected: FAIL (404s: no routes).
+
+- [ ] **Step 3: Write the routes**
+
+Create `src/server/panes.ts`:
+
+```ts
+import {
+  paneAccounts,
+  paneDirectories,
+  paneList,
+  panePeek,
+  paneSpawn,
+  type RtClientOptions,
+} from '@mattstack/rt-client';
+import { Hono } from 'hono';
+
+import {
+  fixtureAccounts,
+  fixtureDirectories,
+  fixturePanes,
+  fixturePeek,
+  fixtureSpawn,
+  fixturesEnabled,
+} from './fixtures';
+
+function rtOpts(): RtClientOptions {
+  return { sockPath: process.env.RT_SOCK_PATH };
+}
+
+const HERDR_UNAVAILABLE = 'herdr unavailable';
+
+function parseIntParam(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  return Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
+
+export const panes = new Hono()
+  // herdr absent is a state the UI hides behind, not an error it shows.
+  .get('/api/panes', async c => {
+    if (fixturesEnabled()) return c.json({ available: true, panes: fixturePanes() }, 200);
+    const res = await paneList(rtOpts());
+    if (!res.ok) {
+      if (res.error?.startsWith(HERDR_UNAVAILABLE)) return c.json({ available: false, panes: [] }, 200);
+      return c.json({ error: res.error }, 502);
+    }
+    return c.json({ available: true, panes: res.data?.panes ?? [] }, 200);
+  })
+  .get('/api/panes/accounts', async c => {
+    if (fixturesEnabled()) return c.json({ accounts: fixtureAccounts() }, 200);
+    const res = await paneAccounts(rtOpts());
+    if (!res.ok) return c.json({ error: res.error }, 502);
+    return c.json(res.data, 200);
+  })
+  .get('/api/panes/directories', async c => {
+    const q = c.req.query('q');
+    if (fixturesEnabled()) return c.json({ directories: fixtureDirectories(q) }, 200);
+    const res = await paneDirectories(q ? { q } : {}, rtOpts());
+    if (!res.ok) return c.json({ error: res.error }, 502);
+    return c.json(res.data, 200);
+  })
+  .get('/api/panes/:id/peek', async c => {
+    const paneId = c.req.param('id');
+    const lines = parseIntParam(c.req.query('lines'));
+    if (fixturesEnabled()) return c.json({ paneId, lines: fixturePeek(paneId) }, 200);
+    const res = await panePeek(lines === undefined ? { paneId } : { paneId, lines }, rtOpts());
+    if (!res.ok) return c.json({ error: res.error }, 502);
+    return c.json(res.data, 200);
+  })
+  .post('/api/panes', async c => {
+    let raw: Record<string, unknown>;
+    try {
+      raw = await c.req.json();
+    } catch {
+      return c.json({ error: 'Malformed JSON in request body' }, 400);
+    }
+    const str = (k: string) => (typeof raw?.[k] === 'string' && (raw[k] as string).length > 0 ? (raw[k] as string) : undefined);
+    const cwd = str('cwd');
+    if (!cwd || !cwd.startsWith('/')) return c.json({ error: 'cwd must be an absolute path' }, 400);
+    const args = { cwd, account: str('account'), model: str('model'), effort: str('effort'), prompt: str('prompt'), workspace: str('workspace') };
+    if (fixturesEnabled()) return c.json(fixtureSpawn(cwd), 200);
+    const res = await paneSpawn(args, rtOpts());
+    if (!res.ok) {
+      const status = res.error?.startsWith('unknown cswap account') || res.error?.startsWith('cwd must be') ? 400 : 502;
+      return c.json({ error: res.error }, status);
+    }
+    return c.json(res.data, 200);
+  });
+```
+
+The test expects `paneSpawn` called with `undefined` for absent fields; `toHaveBeenCalledWith` treats `{ cwd, account: undefined }` as equal to `{ cwd }`, so either shape passes. Mount in `src/server/app.ts`: `import { panes } from './panes';` and `.route('/', panes)` between `chat` and `health`.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `bunx vitest run src/server`
+Expected: all pass, including `app.test.ts`'s "importable without the Bun global".
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/panes.ts src/server/panes.test.ts src/server/app.ts src/server/chat.test.ts
+git commit -m "server: /api/panes routes over rt-client's pane wrappers"
+```
+
+---
+
+### Task 4: `POST /api/chat/rooms` and `POST /api/chat/invite`
+
+**Files:**
+- Modify: `src/server/chat.ts`
+- Test: `src/server/chat.test.ts`
+
+**Interfaces:**
+- Produces:
+  - `POST /api/chat/rooms` `{ room, seed?, wakeOn? }` → `{ room, seedId? }`; 400 on a name outside `^[a-z0-9._-]+$`.
+  - `POST /api/chat/invite` `{ room, panes: [{ paneId, note? }] }` → `{ results: InviteResult[] }`, sequential, 200 even when some are refused; 400 on an empty list or bad room.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/server/chat.test.ts`:
+
+```ts
+test('POST /api/chat/rooms joins as the human (creating the room), posts the seed, returns its id', async () => {
+  vi.mocked(rt.chatJoin).mockResolvedValueOnce({ ok: true, data: { handle: 'matt', memberCount: 1, unread: 0 } });
+  vi.mocked(rt.chatPost).mockResolvedValueOnce({ ok: true, data: { id: 42, recipients: [] } });
+  const res = await app.request('/api/chat/rooms', { method: 'POST', body: JSON.stringify({ room: 'codegen-split', seed: 'Goal: halve the bundle', wakeOn: 'all' }) });
+  expect(res.status).toBe(200);
+  expect(await res.json()).toEqual({ room: 'codegen-split', seedId: 42 });
+  expect(rt.chatJoin).toHaveBeenCalledWith({ room: 'codegen-split', handle: 'matt', wakeOn: 'all' }, expect.anything());
+  expect(rt.chatPost).toHaveBeenCalledWith({ room: 'codegen-split', handle: 'matt', body: 'Goal: halve the bundle' }, expect.anything());
+  expect(vi.mocked(rt.chatJoin).mock.invocationCallOrder[0]).toBeLessThan(vi.mocked(rt.chatPost).mock.invocationCallOrder[0]);
+});
+
+test('POST /api/chat/rooms without a seed only joins; a bad name is 400; a failed seed is 502 after the room exists', async () => {
+  vi.mocked(rt.chatJoin).mockResolvedValueOnce({ ok: true, data: { handle: 'matt', memberCount: 1, unread: 0 } });
+  const bare = await app.request('/api/chat/rooms', { method: 'POST', body: JSON.stringify({ room: 'quiet' }) });
+  expect(await bare.json()).toEqual({ room: 'quiet' });
+  expect(rt.chatPost).not.toHaveBeenCalled();
+  expect((await app.request('/api/chat/rooms', { method: 'POST', body: JSON.stringify({ room: 'Bad Room' }) })).status).toBe(400);
+  vi.mocked(rt.chatJoin).mockResolvedValueOnce({ ok: true, data: { handle: 'matt', memberCount: 1, unread: 0 } });
+  vi.mocked(rt.chatPost).mockResolvedValueOnce({ ok: false, error: 'post refused' });
+  const failed = await app.request('/api/chat/rooms', { method: 'POST', body: JSON.stringify({ room: 'x', seed: 's' }) });
+  expect(failed.status).toBe(502);
+  expect(await failed.json()).toEqual({ error: 'post refused', room: 'x' });
+});
+
+test('POST /api/chat/invite invites each pane in order with the human as from, and returns every result', async () => {
+  vi.mocked(rt.chatInvite)
+    .mockResolvedValueOnce({ ok: true, data: { paneId: 'w1:p1', delivered: 'accepted' } })
+    .mockResolvedValueOnce({ ok: true, data: { paneId: 'w1:p2', delivered: 'refused', reason: 'at a prompt' } });
+  const res = await app.request('/api/chat/invite', { method: 'POST', body: JSON.stringify({ room: 'build', panes: [{ paneId: 'w1:p1', note: 'vite' }, { paneId: 'w1:p2' }] }) });
+  expect(res.status).toBe(200);
+  expect(await res.json()).toEqual({ results: [{ paneId: 'w1:p1', delivered: 'accepted' }, { paneId: 'w1:p2', delivered: 'refused', reason: 'at a prompt' }] });
+  expect(vi.mocked(rt.chatInvite).mock.calls[0]![0]).toEqual({ paneId: 'w1:p1', room: 'build', note: 'vite', from: 'matt' });
+  expect(vi.mocked(rt.chatInvite).mock.calls[1]![0]).toEqual({ paneId: 'w1:p2', room: 'build', from: 'matt' });
+});
+
+test('POST /api/chat/invite turns an rt failure for one pane into a refused result rather than failing the batch', async () => {
+  vi.mocked(rt.chatInvite)
+    .mockResolvedValueOnce({ ok: false, error: 'herdr unavailable: gone' })
+    .mockResolvedValueOnce({ ok: true, data: { paneId: 'w1:p2', delivered: 'queued' } });
+  const res = await app.request('/api/chat/invite', { method: 'POST', body: JSON.stringify({ room: 'build', panes: [{ paneId: 'w1:p1' }, { paneId: 'w1:p2' }] }) });
+  expect(await res.json()).toEqual({ results: [{ paneId: 'w1:p1', delivered: 'refused', reason: 'herdr unavailable: gone' }, { paneId: 'w1:p2', delivered: 'queued' }] });
+  expect((await app.request('/api/chat/invite', { method: 'POST', body: JSON.stringify({ room: 'build', panes: [] }) })).status).toBe(400);
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/server/chat.test.ts`
+Expected: the four new tests FAIL with 404.
+
+- [ ] **Step 3: Add the routes**
+
+In `src/server/chat.ts`, add `chatInvite` and `type InviteResult` to the rt-client import, and after the `/api/chat/dm` route:
+
+```ts
+  // Join-creates, so "create a room" is the human joining it; the seed is
+  // the first post. A room whose seed fails still exists, so the error
+  // carries the room name and the client keeps the draft.
+  .post('/api/chat/rooms', async c => {
+    let raw: { room?: unknown; seed?: unknown; wakeOn?: unknown };
+    try {
+      raw = await c.req.json();
+    } catch {
+      return c.json({ error: 'Malformed JSON in request body' }, 400);
+    }
+    const room = typeof raw?.room === 'string' ? raw.room : '';
+    if (!ROOM_NAME.test(room)) return c.json({ error: 'room must match ^[a-z0-9._-]+$' }, 400);
+    const seed = typeof raw?.seed === 'string' && raw.seed.trim() ? raw.seed : undefined;
+    const wakeOn = raw?.wakeOn === 'all' || raw?.wakeOn === 'mention' || raw?.wakeOn === 'none' ? raw.wakeOn : undefined;
+    const handle = humanHandle(c);
+    const joinRes = await chatJoin(wakeOn ? { room, handle, wakeOn } : { room, handle }, rtOpts());
+    if (!joinRes.ok) return c.json({ error: joinRes.error }, 502);
+    if (!seed) return c.json({ room }, 200);
+    const postRes = await chatPost({ room, handle, body: seed }, rtOpts());
+    if (!postRes.ok) return c.json({ error: postRes.error, room }, 502);
+    return c.json({ room, seedId: postRes.data?.id }, 200);
+  })
+  // Sequential on purpose: each invite types into a live terminal.
+  .post('/api/chat/invite', async c => {
+    let raw: { room?: unknown; panes?: unknown };
+    try {
+      raw = await c.req.json();
+    } catch {
+      return c.json({ error: 'Malformed JSON in request body' }, 400);
+    }
+    const room = typeof raw?.room === 'string' ? raw.room : '';
+    if (!ROOM_NAME.test(room)) return c.json({ error: 'room must match ^[a-z0-9._-]+$' }, 400);
+    const panes = Array.isArray(raw?.panes)
+      ? raw.panes.flatMap((p): { paneId: string; note?: string }[] =>
+          p && typeof p === 'object' && typeof (p as { paneId?: unknown }).paneId === 'string'
+            ? [{ paneId: (p as { paneId: string }).paneId, ...(typeof (p as { note?: unknown }).note === 'string' && (p as { note: string }).note.trim() ? { note: (p as { note: string }).note } : {}) }]
+            : []
+        )
+      : [];
+    if (panes.length === 0) return c.json({ error: 'panes must name at least one pane' }, 400);
+    const from = humanHandle(c);
+    const results: InviteResult[] = [];
+    for (const p of panes) {
+      const res = await chatInvite({ paneId: p.paneId, room, from, ...(p.note ? { note: p.note } : {}) }, rtOpts());
+      results.push(res.ok && res.data ? res.data : { paneId: p.paneId, delivered: 'refused', reason: res.error ?? 'invite failed' });
+    }
+    return c.json({ results }, 200);
+  });
+```
+
+with `const ROOM_NAME = /^[a-z0-9._-]+$/;` near the top of the file (rt's `isValidChatName` charset). Add the four routes to the API table in `ARCHITECTURE.md`.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `bunx vitest run src/server`
+Expected: pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/server/chat.ts src/server/chat.test.ts ARCHITECTURE.md
+git commit -m "server: POST /api/chat/rooms creates and seeds; POST /api/chat/invite types into panes"
+```
+
+---
+
+### Task 5: members refresh on `chat/<room>/msg`
+
+**Files:**
+- Modify: `src/app/App.tsx:247-284` (`useRoomMembers`)
+- Test: `src/app/App.test.tsx`
+
+**Interfaces:**
+- `useRoomMembers(room, seed)` keeps its signature; it now also refetches `/api/chat/who/<room>` whenever a frame with `topic === \`chat/${room}/msg\`` arrives on `/ws`.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/app/App.test.tsx` (the file already installs `FakeWebSocket`; import `FakeWebSocket` from `@ui/test-utils` if not already):
+
+```tsx
+test('a chat/<room>/msg frame refetches the open room\'s members', async () => {
+  installFetchMock();
+  fetchMock.mockImplementation(async (url: string) =>
+    new Response(JSON.stringify(url.startsWith('/api/chat/who/') ? { members: [{ room: 'build', handle: 'fred', joinedAt: 1, lastReadId: 0, wakeOn: 'mention', status: 'live' }] } : {}))
+  );
+  renderAt('/r/build');
+  await act(async () => {
+    renderWithProviders(<App initialState={{ ...twoRooms, members: [] }} />);
+  });
+  const before = fetchMock.mock.calls.filter(([u]) => String(u).startsWith('/api/chat/who/build')).length;
+  await act(async () => {
+    for (const socket of FakeWebSocket.instances) socket.onmessage?.({ data: JSON.stringify({ topic: 'chat/build/msg', payload: { id: 7 } }) });
+  });
+  const after = fetchMock.mock.calls.filter(([u]) => String(u).startsWith('/api/chat/who/build')).length;
+  expect(after).toBeGreaterThan(before);
+});
+```
+
+(Use the file's existing `renderAt` helper only once; drop the duplicate render if `renderAt` already mounts `<App />`: mount with `renderWithProviders(<App initialState={{ ...twoRooms, members: [] }} />)` after `window.history.replaceState(null, '', '/r/build')`.)
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/app/App.test.tsx -t "refetches"`
+Expected: FAIL (`after` equals `before`).
+
+- [ ] **Step 3: Refactor the hook**
+
+In `src/app/App.tsx`, rewrite `useRoomMembers` so the fetch is a `useCallback` keyed on `room`, the room-change effect calls it (keeping the seed one-shot rule), and a second effect opens a socket for the exact topic, the same shape `Transcript.tsx:506-530` uses:
+
+```ts
+function useRoomMembers(room: string | undefined, seed: ChatMember[] | undefined): string[] {
+  const [members, setMembers] = useState<ChatMember[]>(seed ?? []);
+  const seedPending = useRef(seed !== undefined);
+  const roomRef = useRef(room);
+  roomRef.current = room;
+
+  const fetchMembers = useCallback(() => {
+    if (!room) return;
+    fetch(`/api/chat/who/${room}`)
+      .then(res => res.json())
+      .then((data: { members?: ChatMember[] }) => {
+        if (roomRef.current === room) setMembers(data.members ?? []);
+      })
+      .catch(() => {});
+  }, [room]);
+
+  useEffect(() => {
+    if (!room) {
+      if (!seedPending.current) setMembers([]);
+      return;
+    }
+    if (seedPending.current) {
+      seedPending.current = false;
+      return;
+    }
+    setMembers([]);
+    fetchMembers();
+  }, [room, fetchMembers]);
+
+  // A post is the one signal an arriving member makes: the join skill's
+  // first line. The daemon emits no membership frame, so this is the hook.
+  useEffect(() => {
+    if (!room) return;
+    const expectedTopic = `chat/${room}/msg`;
+    const socket = new WebSocket(wsUrl());
+    socket.onmessage = event => {
+      let frame: { topic?: unknown } | undefined;
+      try {
+        frame = JSON.parse(String((event as { data: unknown }).data));
+      } catch {
+        return;
+      }
+      if (frame?.topic === expectedTopic) fetchMembers();
+    };
+    return () => socket.close();
+  }, [room, fetchMembers]);
+
+  return members.map(m => m.handle);
+}
+```
+
+- [ ] **Step 4: Run the suite**
+
+Run: `bunx vitest run src/app src/ui/Transcript.test.tsx`
+Expected: pass. If a Transcript test that pushes a frame to `FakeWebSocket.instances.at(-1)` now hits the members socket instead, change that helper in `src/ui/test-utils.tsx` to fan the frame to every instance.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/app/App.tsx src/app/App.test.tsx src/ui/test-utils.tsx
+git commit -m "app: refetch the room's members on every chat/<room>/msg frame"
+```
+
+---
+
+### Task 6: `PanePicker`
+
+**Files:**
+- Modify: `src/ui/icons/Icons.ts` (add `UserPlus` import and `userPlus` entry)
+- Create: `src/ui/PanePicker/types.ts`, `src/ui/PanePicker/PanePickerProvider.tsx`, `src/ui/PanePicker/PanePickerModal.tsx`, `src/ui/PanePicker/PaneRow.tsx`, `src/ui/PanePicker/NewPaneForm.tsx`, `src/ui/PanePicker/index.ts`
+- Test: `src/ui/PanePicker/PanePicker.test.tsx`, `src/ui/icons/Icons.test.ts` (unchanged, guards the new icon)
+
+**Interfaces:**
+- Produces:
+
+```ts
+// src/ui/PanePicker/types.ts
+export type { AgentStatus, ChatPane, InviteResult, PaneAccount, PaneDirectory } from '@mattstack/rt-client';
+export interface PickPanesOptions {
+  context?: string;
+  multiple?: boolean;                            // default true
+  disable?: (pane: ChatPane) => string | null;
+  preselected?: string[];
+  allowCreate?: boolean;                         // default false
+}
+export type PickPanes = (opts?: PickPanesOptions) => Promise<ChatPane[] | null>;
+
+// src/ui/PanePicker/index.ts
+export { PanePickerProvider, usePanePicker } from './PanePickerProvider';
+export { PaneRow } from './PaneRow';
+export type { PickPanes, PickPanesOptions } from './types';
+```
+
+  `PanePickerProvider` mounts one modal host; `usePanePicker()` returns `PickPanes`. `PaneRow` is exported because `NewRoomModal` (Task 7) reuses its top two lines for the picked list.
+- Consumes: `GET /api/panes`, `GET /api/panes/:id/peek?lines=8`, `GET /api/panes/accounts`, `GET /api/panes/directories?q=`, `POST /api/panes`.
+
+- [ ] **Step 1: The icon**
+
+In `src/ui/icons/Icons.ts`, add `UserPlus` to the lucide import list and `userPlus: /* @__PURE__ */ lucideWrapperFn(UserPlus),` to `MiscIcons` beside `users`. Run `bunx vitest run src/ui/icons` (the registry guard passes).
+
+- [ ] **Step 2: Write the failing tests**
+
+Create `src/ui/PanePicker/PanePicker.test.tsx`:
+
+```tsx
+import { act, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, expect, test } from 'vitest';
+
+import { renderWithProviders } from '@ui/storybook/test-utils';
+import { fetchMock, installFetchMock } from '@ui/test-utils';
+import { PanePickerProvider, usePanePicker, type PickPanesOptions } from './index';
+import type { ChatPane } from './types';
+
+const PANES: ChatPane[] = [
+  { paneId: 'w1:p1', workspace: 'repo-tools', title: 'fred', cwd: '/r/repo-tools', repo: 'repo-tools', branch: 'main', agentStatus: 'working', presence: { handle: 'fred', status: 'live', rooms: ['repo-tools'] } },
+  { paneId: 'w1:p2', workspace: 'chat', title: 'meg', cwd: '/r/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', presence: { handle: 'meg', status: 'live', rooms: ['build'] } },
+  { paneId: 'w1:p3', workspace: 'gitq', title: 'june', cwd: '/r/gitq', repo: 'gitq', branch: 'main', agentStatus: 'blocked', presence: { handle: 'june', status: 'idle', rooms: [] } },
+  { paneId: 'w1:p4', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', repo: 'assured', branch: 'main', agentStatus: 'idle' },
+];
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), { status });
+}
+
+function route(handlers: Record<string, (init?: RequestInit) => Response | Promise<Response>>) {
+  fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+    const path = String(url).split('?')[0]!;
+    const key = `${init?.method ?? 'GET'} ${path}`;
+    const handler = handlers[key] ?? handlers[`${init?.method ?? 'GET'} ${path.replace(/\/w\d:p\d\/peek$/, '/:id/peek')}`];
+    if (!handler) return json({}, 404);
+    return handler(init);
+  });
+}
+
+function Harness({ opts, onDone }: { opts?: PickPanesOptions; onDone: (r: ChatPane[] | null) => void }) {
+  const pick = usePanePicker();
+  return (
+    <button type="button" onClick={() => void pick(opts).then(onDone)}>
+      open
+    </button>
+  );
+}
+
+function mount(opts?: PickPanesOptions) {
+  const results: Array<ChatPane[] | null> = [];
+  renderWithProviders(
+    <PanePickerProvider>
+      <Harness opts={opts} onDone={r => results.push(r)} />
+    </PanePickerProvider>
+  );
+  return results;
+}
+
+beforeEach(() => {
+  installFetchMock();
+  route({ 'GET /api/panes': () => json({ available: true, panes: PANES }) });
+});
+
+test('lists claude panes sorted listening, idle, deaf, not signed in, with handle or not signed in', async () => {
+  mount();
+  await userEvent.click(screen.getByText('open'));
+  const rows = await screen.findAllByTestId(/^pane-row-/);
+  expect(rows.map(r => r.getAttribute('data-testid'))).toEqual(['pane-row-w1:p1', 'pane-row-w1:p2', 'pane-row-w1:p3', 'pane-row-w1:p4']);
+  expect(within(rows[0]!).getByText('fred')).toBeInTheDocument();
+  expect(within(rows[3]!).getByText('not signed in')).toBeInTheDocument();
+  expect(within(rows[3]!).getByText('…/assured')).toBeInTheDocument();
+});
+
+test('the filter matches handle, workspace, title, repo and path', async () => {
+  mount();
+  await userEvent.click(screen.getByText('open'));
+  await screen.findAllByTestId(/^pane-row-/);
+  await userEvent.type(screen.getByTestId('pane-filter'), 'codegen');
+  expect(screen.getAllByTestId(/^pane-row-/)).toHaveLength(1);
+  await userEvent.clear(screen.getByTestId('pane-filter'));
+  await userEvent.type(screen.getByTestId('pane-filter'), '/r/gitq');
+  expect(screen.getAllByTestId(/^pane-row-/).map(r => r.getAttribute('data-testid'))).toEqual(['pane-row-w1:p3']);
+});
+
+test("the caller's disable reason renders inline and the row cannot be selected", async () => {
+  const results = mount({ disable: p => (p.presence?.rooms.includes('build') ? 'in #build' : null) });
+  await userEvent.click(screen.getByText('open'));
+  const meg = await screen.findByTestId('pane-row-w1:p2');
+  expect(within(meg).getByText('in #build')).toBeInTheDocument();
+  await userEvent.click(within(meg).getByTestId('pane-check-w1:p2'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  expect(results).toEqual([[]]);
+});
+
+test('the eye fetches the peek for that row only, once opened', async () => {
+  route({
+    'GET /api/panes': () => json({ available: true, panes: PANES }),
+    'GET /api/panes/:id/peek': () => json({ paneId: 'w1:p4', lines: ['⏺ Read(x)', '❯ '] }),
+  });
+  mount();
+  await userEvent.click(screen.getByText('open'));
+  await screen.findByTestId('pane-row-w1:p4');
+  expect(fetchMock.mock.calls.some(([u]) => String(u).includes('/peek'))).toBe(false);
+  await userEvent.click(screen.getByTestId('pane-peek-button-w1:p4'));
+  expect(await screen.findByTestId('pane-peek-w1:p4')).toHaveTextContent('Read(x)');
+  expect(fetchMock.mock.calls.filter(([u]) => String(u).includes('/peek'))).toHaveLength(1);
+});
+
+test('resolves with the picked rows verbatim; cancel resolves null', async () => {
+  const results = mount({ context: 'to invite to #build' });
+  await userEvent.click(screen.getByText('open'));
+  expect(await screen.findByText('to invite to #build')).toBeInTheDocument();
+  await userEvent.click(screen.getByTestId('pane-check-w1:p1'));
+  await userEvent.click(screen.getByTestId('pane-check-w1:p4'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  expect(results).toEqual([[PANES[0], PANES[3]]]);
+  await userEvent.click(screen.getByText('open'));
+  await screen.findByTestId('pane-row-w1:p1');
+  await userEvent.click(screen.getByTestId('pane-cancel'));
+  expect(results[1]).toBeNull();
+});
+
+test('multiple:false keeps one selection', async () => {
+  const results = mount({ multiple: false });
+  await userEvent.click(screen.getByText('open'));
+  await userEvent.click(await screen.findByTestId('pane-check-w1:p1'));
+  await userEvent.click(screen.getByTestId('pane-check-w1:p4'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  expect(results).toEqual([[PANES[3]]]);
+});
+
+test('new pane is hidden without allowCreate and present with it; the form posts and lists the pane as starting until ready', async () => {
+  let release: (r: Response) => void = () => {};
+  route({
+    'GET /api/panes': () => json({ available: true, panes: PANES }),
+    'GET /api/panes/accounts': () => json({ accounts: [{ slot: 1, email: 'a@b.c', alias: 'Assured', headroom: '5h 0%' }] }),
+    'GET /api/panes/directories': () => json({ directories: [{ path: '/r/assured-wt', repo: 'assured', branch: 'perf' }] }),
+    'POST /api/panes': () => new Promise<Response>(r => (release = r)),
+  });
+  mount();
+  await userEvent.click(screen.getByText('open'));
+  await screen.findByTestId('pane-row-w1:p1');
+  expect(screen.queryByTestId('pane-new')).toBeNull();
+  await userEvent.click(screen.getByTestId('pane-cancel'));
+
+  const results = mount({ allowCreate: true });
+  await userEvent.click(screen.getAllByText('open')[1]!);
+  await userEvent.click(await screen.findByTestId('pane-new'));
+  await userEvent.type(screen.getByLabelText('Directory'), '/r/assured-wt');
+  await userEvent.click(screen.getByTestId('pane-start'));
+  expect(await screen.findByText(/starting/)).toBeInTheDocument();
+  const body = JSON.parse(String(fetchMock.mock.calls.find(([, i]) => (i as RequestInit)?.method === 'POST')![1]!.body));
+  expect(body).toMatchObject({ cwd: '/r/assured-wt', account: 'Assured' });
+  await act(async () => {
+    release(json({ pane: { paneId: 'w9:p1', workspace: 'chat', cwd: '/r/assured-wt', agentStatus: 'idle' }, ready: true }));
+  });
+  const row = await screen.findByTestId('pane-row-w9:p1');
+  expect(within(row).getByTestId('pane-check-w9:p1')).toHaveAttribute('aria-checked', 'true');
+  await userEvent.click(screen.getByTestId('pane-use'));
+  expect(results[0]).toEqual([{ paneId: 'w9:p1', workspace: 'chat', cwd: '/r/assured-wt', agentStatus: 'idle' }]);
+});
+
+test('a ready:false spawn keeps the row, unselectable, with its state', async () => {
+  route({
+    'GET /api/panes': () => json({ available: true, panes: [] }),
+    'GET /api/panes/accounts': () => json({ accounts: [] }),
+    'GET /api/panes/directories': () => json({ directories: [] }),
+    'POST /api/panes': () => json({ pane: { paneId: 'w9:p2', workspace: 'chat', cwd: '/r/x', agentStatus: 'unknown' }, ready: false }),
+  });
+  mount({ allowCreate: true });
+  await userEvent.click(screen.getByText('open'));
+  await userEvent.click(await screen.findByTestId('pane-new'));
+  expect(screen.queryByLabelText('Account')).toBeNull();
+  await userEvent.type(screen.getByLabelText('Directory'), '/r/x');
+  await userEvent.click(screen.getByTestId('pane-start'));
+  const row = await screen.findByTestId('pane-row-w9:p2');
+  expect(within(row).getByText(/never reached idle/)).toBeInTheDocument();
+  expect(within(row).getByTestId('pane-check-w9:p2')).toHaveAttribute('aria-disabled', 'true');
+});
+
+test('herdr unavailable shows a notice and only cancel', async () => {
+  route({ 'GET /api/panes': () => json({ available: false, panes: [] }) });
+  const results = mount();
+  await userEvent.click(screen.getByText('open'));
+  expect(await screen.findByText(/herdr/)).toBeInTheDocument();
+  expect(screen.queryByTestId('pane-use')).toBeNull();
+  await userEvent.click(screen.getByTestId('pane-cancel'));
+  expect(results).toEqual([null]);
+});
+```
+
+- [ ] **Step 3: Run to verify failure**
+
+Run: `bunx vitest run src/ui/PanePicker`
+Expected: FAIL, module not found.
+
+- [ ] **Step 4: Write the types and the provider**
+
+`src/ui/PanePicker/types.ts` exactly as in Interfaces. `src/ui/PanePicker/PanePickerProvider.tsx`:
+
+```tsx
+import { createContext, useCallback, useContext, useState, type ReactNode } from 'react';
+
+import { PanePickerModal } from './PanePickerModal';
+import type { ChatPane, PickPanes, PickPanesOptions } from './types';
+
+const PickContext = createContext<PickPanes | null>(null);
+
+interface PendingPick {
+  opts: PickPanesOptions;
+  resolve: (r: ChatPane[] | null) => void;
+}
+
+/** Hosts the one picker modal, inside the app's providers, so any caller
+    below can `usePanePicker()` and await a result. */
+export function PanePickerProvider({ children }: { children: ReactNode }) {
+  const [pending, setPending] = useState<PendingPick | null>(null);
+  const pick = useCallback<PickPanes>(
+    opts =>
+      new Promise(resolve => {
+        setPending(prev => {
+          prev?.resolve(null);
+          return { opts: opts ?? {}, resolve };
+        });
+      }),
+    []
+  );
+  return (
+    <PickContext.Provider value={pick}>
+      {children}
+      {pending && (
+        <PanePickerModal
+          opts={pending.opts}
+          onDone={result => {
+            pending.resolve(result);
+            setPending(null);
+          }}
+        />
+      )}
+    </PickContext.Provider>
+  );
+}
+
+export function usePanePicker(): PickPanes {
+  const pick = useContext(PickContext);
+  if (!pick) throw new Error('usePanePicker needs a PanePickerProvider above it');
+  return pick;
+}
+```
+
+- [ ] **Step 5: Write `PaneRow`**
+
+`src/ui/PanePicker/PaneRow.tsx`. Anatomy from the artboard: a 16px checkbox (`aria-checked`, `aria-disabled`, `data-testid="pane-check-<id>"`), the 8px dot (colour from `DOT_COLOR[presence.status]`, hollow when there is no presence), the handle or `not signed in`, `·`, the workspace plus ` · title` when the title differs from the handle, the right-hand reason or state, a 22px eye button (`data-testid="pane-peek-button-<id>"`), a second line `repo · branch` with `Tag`s for rooms, the `headTruncatePath(cwd)` line, an optional `note` slot, and the peek block (`data-testid="pane-peek-<id>"`) when open.
+
+```tsx
+import type { ReactNode } from 'react';
+import { Box, Group, Stack, Text, UnstyledButton } from '@mantine/core';
+
+import { Icon } from '@ui/icons';
+import { DOT_COLOR, headTruncatePath, Tag } from '../presence-bits';
+import type { AgentStatus, ChatPane } from './types';
+
+const MUTED = 'var(--tk-muted-text)';
+const BORDER = 'var(--tk-border)';
+const BORDER_SOFT = 'var(--tk-border-soft)';
+const ACCENT_TEXT = 'var(--mantine-color-accent-text)';
+const ACCENT_WASH = `color-mix(in srgb, ${ACCENT_TEXT} var(--tk-wash), transparent)`;
+const ACCENT_DEEP = 'light-dark(var(--mantine-color-accent-7), var(--mantine-color-accent-text))';
+const ACCENT_ON = 'light-dark(var(--mantine-color-white), var(--tk-bg))';
+
+const STATE_COLOR: Record<AgentStatus, string> = {
+  working: 'var(--mantine-color-warn-text)',
+  blocked: 'var(--mantine-color-bad-text)',
+  idle: MUTED,
+  done: MUTED,
+  unknown: MUTED,
+};
+
+export function agentStateLabel(status: AgentStatus): string {
+  if (status === 'working') return 'working · queues until its turn ends';
+  if (status === 'blocked') return 'at a prompt · answer it first';
+  return status;
+}
+
+export interface PaneRowProps {
+  pane: ChatPane;
+  /** Absent: no checkbox (the picked list in New room). */
+  selected?: boolean;
+  disabledReason?: string | null;
+  onToggle?: () => void;
+  onPeek?: () => void;
+  peek?: string[] | 'loading';
+  /** Rendered under the path: the note input, or the remove control. */
+  extra?: ReactNode;
+  trailing?: ReactNode;
+}
+
+export function PaneRow({ pane, selected, disabledReason, onToggle, onPeek, peek, extra, trailing }: PaneRowProps) {
+  const disabled = !!disabledReason;
+  const handle = pane.presence?.handle;
+  const sub = handle && pane.title === handle ? pane.workspace : `${pane.workspace}${pane.title ? ` · ${pane.title}` : ''}`;
+  const where = [pane.repo, pane.branch].filter(Boolean).join(' · ');
+  return (
+    <Box
+      data-testid={`pane-row-${pane.paneId}`}
+      style={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: 'var(--mantine-spacing-md)',
+        padding: '8.4px var(--mantine-spacing-md)',
+        borderRadius: 'var(--mantine-radius-md)',
+        minWidth: 0,
+        background: selected ? ACCENT_WASH : undefined,
+        opacity: disabled ? 0.55 : 1,
+      }}
+    >
+      {onToggle && (
+        <UnstyledButton
+          role="checkbox"
+          aria-checked={!!selected}
+          aria-disabled={disabled}
+          aria-label={`select ${handle ?? pane.paneId}`}
+          data-testid={`pane-check-${pane.paneId}`}
+          onClick={() => {
+            if (!disabled) onToggle();
+          }}
+          style={{
+            width: 16,
+            height: 16,
+            marginTop: 2,
+            flex: 'none',
+            borderRadius: 4,
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            border: `1px solid ${disabled ? MUTED : selected ? ACCENT_DEEP : BORDER}`,
+            background: disabled ? 'var(--ui-bg-4)' : selected ? ACCENT_DEEP : 'var(--tk-bg)',
+            color: ACCENT_ON,
+            cursor: disabled ? 'default' : 'pointer',
+          }}
+        >
+          {selected && !disabled && <Icon name="check" size={11} />}
+        </UnstyledButton>
+      )}
+      <Stack gap={1} style={{ flex: 1, minWidth: 0 }}>
+        <Group gap="xs" wrap="nowrap">
+          <Box
+            component="span"
+            data-testid={`pane-dot-${pane.paneId}`}
+            style={{
+              width: 8,
+              height: 8,
+              marginTop: 5,
+              flex: 'none',
+              borderRadius: '50%',
+              background: pane.presence ? DOT_COLOR[pane.presence.status as 'live' | 'idle' | 'deaf'] : 'transparent',
+              border: pane.presence ? undefined : `1px solid ${BORDER}`,
+            }}
+          />
+          {handle ? (
+            <Text component="span" size="sm" fw={600}>
+              {handle}
+            </Text>
+          ) : (
+            <Text component="span" size="sm" style={{ color: MUTED }}>
+              not signed in
+            </Text>
+          )}
+          <Text component="span" size="xs" style={{ color: MUTED }}>
+            ·
+          </Text>
+          <Text component="span" size="xs" truncate style={{ color: MUTED, flex: 1 }}>
+            {sub}
+          </Text>
+          {disabledReason ? (
+            <Text component="span" size="xs" style={{ color: STATE_COLOR.blocked, flex: 'none' }}>
+              {disabledReason}
+            </Text>
+          ) : (
+            <Text component="span" size="xs" style={{ color: STATE_COLOR[pane.agentStatus], fontWeight: 500, flex: 'none' }}>
+              {agentStateLabel(pane.agentStatus)}
+            </Text>
+          )}
+          {trailing}
+          {onPeek && (
+            <UnstyledButton
+              aria-label="Peek at pane"
+              data-testid={`pane-peek-button-${pane.paneId}`}
+              onClick={onPeek}
+              style={{ width: 22, height: 22, flex: 'none', display: 'inline-flex', alignItems: 'center', justifyContent: 'center', borderRadius: 'var(--mantine-radius-md)', color: MUTED }}
+            >
+              <Icon name="eye" size={13} />
+            </UnstyledButton>
+          )}
+        </Group>
+        <Group gap={6} wrap="nowrap">
+          <Text component="span" size="xs" style={{ color: MUTED }}>
+            {where}
+          </Text>
+          {pane.presence?.rooms.map(room => <Tag key={room} handle={handle ?? pane.paneId} room={room} />)}
+        </Group>
+        {pane.cwd && (
+          <Text component="span" size="xs" truncate style={{ color: MUTED }}>
+            {headTruncatePath(pane.cwd)}
+          </Text>
+        )}
+        {extra}
+        {peek && (
+          <Box
+            component="pre"
+            data-testid={`pane-peek-${pane.paneId}`}
+            style={{
+              margin: '4.8px 0 0',
+              padding: '7.2px var(--mantine-spacing-md)',
+              background: 'var(--tk-bg)',
+              border: `1px solid ${BORDER}`,
+              borderRadius: 4,
+              fontFamily: 'inherit',
+              fontSize: '11.2px',
+              lineHeight: 1.5,
+              whiteSpace: 'pre',
+              overflowX: 'auto',
+              color: MUTED,
+            }}
+          >
+            {peek === 'loading' ? 'reading the pane…' : peek.join('\n')}
+          </Box>
+        )}
+      </Stack>
+      <Box component="span" style={{ display: 'none', borderTop: `1px solid ${BORDER_SOFT}` }} />
+    </Box>
+  );
+}
+```
+
+Row separators: the list container draws `border-top: 1px solid var(--tk-border-soft)` between rows (`.pane + .pane`), so give the list's rows `[data-testid^="pane-row-"] + [data-testid^="pane-row-"] { border-top ... }` through an inline style on every row except the first (pass `first` from the list and set `borderTop` accordingly); drop the hidden trailing span above once that is in place.
+
+- [ ] **Step 6: Write `NewPaneForm`**
+
+`src/ui/PanePicker/NewPaneForm.tsx`: directory (a `TextInput` from `@ui/core`, `label="Directory"`, with suggestions fetched from `/api/panes/directories?q=` on each change, rendered as a list of 34px `.opt`-style buttons under the input that fill the field when clicked), account (`Select` from `@mantine/core`, `label="Account"`, options `${alias ?? email} · ${headroom}` with value `alias ?? email`, hidden when `/api/panes/accounts` answers empty, defaulting to the first account), model (`Select`, `label="Model"`, options `claude-fable-5`, `claude-opus-5`, `claude-sonnet-5`, default `claude-fable-5`), effort (`Select`, `label="Effort"`, options blank, `low`, `medium`, `high`, `max`, default blank), workspace (`TextInput`, `label="Workspace"`, default `chat`), opening prompt (`Textarea`, `label="Opening prompt"`), a hint line showing the launch command it will run (`cswap run <account> --share-history -- claude --model <m> [--effort <e>]` or `claude ...` without an account), and a footer with `Back` (`data-testid="pane-back"`) and `Start pane` (`data-testid="pane-start"`, disabled until the directory starts with `/`). Props: `{ onBack: () => void; onStart: (args: { cwd; account?; model?; effort?; prompt?; workspace? }) => void }`. Fetch accounts once on mount.
+
+- [ ] **Step 7: Write `PanePickerModal`**
+
+`src/ui/PanePicker/PanePickerModal.tsx`:
+
+```tsx
+import { useEffect, useMemo, useState } from 'react';
+import { Box, Button, Group, Modal, Stack, Text } from '@mantine/core';
+
+import { TextInput } from '@ui/core';
+import { useIsMobile } from '@ui/hooks';
+import { Icon } from '@ui/icons';
+import { notifications } from '@ui/notifications';
+import { NewPaneForm } from './NewPaneForm';
+import { PaneRow } from './PaneRow';
+import type { ChatPane, PickPanesOptions } from './types';
+
+const ORDER: Record<string, number> = { live: 0, idle: 1, deaf: 2 };
+
+export function sortPanes(panes: ChatPane[]): ChatPane[] {
+  return panes
+    .map((p, i) => ({ p, i }))
+    .sort((a, b) => (ORDER[a.p.presence?.status ?? ''] ?? 3) - (ORDER[b.p.presence?.status ?? ''] ?? 3) || a.i - b.i)
+    .map(({ p }) => p);
+}
+
+export function matchesFilter(pane: ChatPane, q: string): boolean {
+  const needle = q.trim().toLowerCase();
+  if (!needle) return true;
+  return [pane.presence?.handle, pane.workspace, pane.title, pane.repo, pane.cwd, pane.paneId]
+    .filter((v): v is string => typeof v === 'string')
+    .some(v => v.toLowerCase().includes(needle));
+}
+
+interface Starting {
+  key: string;
+  cwd: string;
+}
+
+export function PanePickerModal({ opts, onDone }: { opts: PickPanesOptions; onDone: (r: ChatPane[] | null) => void }) {
+  const multiple = opts.multiple ?? true;
+  const [available, setAvailable] = useState<boolean | null>(null);
+  const [panes, setPanes] = useState<ChatPane[]>([]);
+  const [notReady, setNotReady] = useState<Set<string>>(new Set());
+  const [starting, setStarting] = useState<Starting[]>([]);
+  const [selected, setSelected] = useState<Set<string>>(new Set(opts.preselected ?? []));
+  const [filter, setFilter] = useState('');
+  const [peeks, setPeeks] = useState<Record<string, string[] | 'loading'>>({});
+  const [view, setView] = useState<'list' | 'new'>('list');
+  const mobile = useIsMobile();
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/panes')
+      .then(res => res.json())
+      .then((data: { available?: boolean; panes?: ChatPane[] }) => {
+        if (cancelled) return;
+        setAvailable(data.available !== false);
+        setPanes(sortPanes(data.panes ?? []));
+      })
+      .catch(() => {
+        if (!cancelled) setAvailable(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const visible = useMemo(() => panes.filter(p => matchesFilter(p, filter)), [panes, filter]);
+
+  function reasonFor(pane: ChatPane): string | null {
+    if (notReady.has(pane.paneId)) return 'never reached idle · peek to see why';
+    return opts.disable?.(pane) ?? null;
+  }
+
+  function toggle(pane: ChatPane) {
+    setSelected(prev => {
+      const next = new Set(multiple ? prev : []);
+      if (prev.has(pane.paneId)) next.delete(pane.paneId);
+      else next.add(pane.paneId);
+      return next;
+    });
+  }
+
+  function peek(pane: ChatPane) {
+    if (peeks[pane.paneId]) {
+      setPeeks(prev => {
+        const next = { ...prev };
+        delete next[pane.paneId];
+        return next;
+      });
+      return;
+    }
+    setPeeks(prev => ({ ...prev, [pane.paneId]: 'loading' }));
+    fetch(`/api/panes/${encodeURIComponent(pane.paneId)}/peek?lines=8`)
+      .then(res => res.json())
+      .then((data: { lines?: string[] }) => setPeeks(prev => ({ ...prev, [pane.paneId]: data.lines ?? [] })))
+      .catch(() => setPeeks(prev => ({ ...prev, [pane.paneId]: ['(could not read the pane)'] })));
+  }
+
+  function start(args: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string }) {
+    const key = `starting-${Date.now()}`;
+    setStarting(prev => [...prev, { key, cwd: args.cwd }]);
+    setView('list');
+    fetch('/api/panes', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(args) })
+      .then(async res => {
+        if (!res.ok) throw new Error(((await res.json()) as { error?: string }).error ?? 'spawn failed');
+        return (await res.json()) as { pane: ChatPane; ready: boolean };
+      })
+      .then(({ pane, ready }) => {
+        setStarting(prev => prev.filter(s => s.key !== key));
+        setPanes(prev => sortPanes([...prev.filter(p => p.paneId !== pane.paneId), pane]));
+        if (ready) setSelected(prev => new Set(multiple ? [...prev, pane.paneId] : [pane.paneId]));
+        else setNotReady(prev => new Set([...prev, pane.paneId]));
+      })
+      .catch((err: Error) => {
+        setStarting(prev => prev.filter(s => s.key !== key));
+        notifications.error(`Couldn't start the pane: ${err.message}`);
+      });
+  }
+
+  const picked = panes.filter(p => selected.has(p.paneId) && !reasonFor(p));
+  const title = (
+    <Group gap="xs" wrap="nowrap">
+      <Icon name="terminal" size={18} />
+      <Text size="xl" fw={700}>
+        {view === 'new' ? 'New pane' : 'Pick herdr panes'}
+      </Text>
+      {opts.context && view === 'list' && (
+        <Text size="sm" style={{ color: 'var(--tk-muted-text)' }}>
+          {opts.context}
+        </Text>
+      )}
+    </Group>
+  );
+
+  return (
+    <Modal opened onClose={() => onDone(null)} title={title} size={640} fullScreen={mobile} data-testid="pane-picker" closeButtonProps={{ 'aria-label': 'Close' }}>
+      {view === 'new' ? (
+        <NewPaneForm onBack={() => setView('list')} onStart={start} />
+      ) : (
+        <Stack gap="xs">
+          {available === false ? (
+            <Text size="sm">herdr is not running, so there are no panes to list.</Text>
+          ) : (
+            <>
+              <TextInput size="xs" placeholder="filter by handle, workspace, title, repo, path" leftSection={<Icon name="search" size={13} />} value={filter} onChange={e => setFilter(e.currentTarget.value)} data-testid="pane-filter" aria-label="Filter panes" />
+              <Group justify="space-between" wrap="nowrap">
+                <Text size="xs" style={{ color: 'var(--tk-muted-text)' }}>
+                  {panes.length} panes running Claude · sorted listening, idle, deaf, not signed in
+                </Text>
+                <Group gap="xs" wrap="nowrap">
+                  <Text size="xs" style={{ color: 'var(--tk-muted-text)' }}>
+                    {picked.length} selected
+                  </Text>
+                  {opts.allowCreate && (
+                    <Button size="xs" variant="default" leftSection={<Icon name="plus" size={14} />} onClick={() => setView('new')} data-testid="pane-new">
+                      new pane
+                    </Button>
+                  )}
+                </Group>
+              </Group>
+              <Stack gap={0} style={{ border: '1px solid var(--tk-border)', borderRadius: 'var(--mantine-radius-md)', background: 'var(--tk-panel)', maxHeight: mobile ? undefined : 560, overflow: 'auto', padding: '2px 0' }}>
+                {starting.map(s => (
+                  <PaneRow key={s.key} pane={{ paneId: s.key, workspace: 'chat', cwd: s.cwd, agentStatus: 'unknown' }} disabledReason="starting claude · selectable when idle" onToggle={() => {}} />
+                ))}
+                {visible.map(pane => (
+                  <PaneRow key={pane.paneId} pane={pane} selected={selected.has(pane.paneId)} disabledReason={reasonFor(pane)} onToggle={() => toggle(pane)} onPeek={() => peek(pane)} peek={peeks[pane.paneId]} />
+                ))}
+              </Stack>
+            </>
+          )}
+          <Group justify="flex-end" gap="xs" style={{ borderTop: '1px solid var(--tk-border-soft)', paddingTop: 'var(--mantine-spacing-xs)' }}>
+            <Text size="xs" style={{ color: 'var(--tk-muted-text)', flex: 1 }}>
+              the eye peeks at a pane's last lines when a title is not enough
+            </Text>
+            <Button variant="default" size="sm" onClick={() => onDone(null)} data-testid="pane-cancel">
+              Cancel
+            </Button>
+            {available !== false && (
+              <Button size="sm" leftSection={<Icon name="check" size={14} />} onClick={() => onDone(picked)} data-testid="pane-use">
+                Use {picked.length} {picked.length === 1 ? 'pane' : 'panes'}
+              </Button>
+            )}
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}
+```
+
+Look up `Modal`'s `fullScreen`, `size`, `closeButtonProps` and `Button`'s `leftSection`/`variant` props in the Mantine docs before relying on them. On the phone, buttons take `size="md"` and the row's controls 44px (`mobile ? 44 : 22` for the eye, `mobile ? 24 : 16` for the checkbox).
+
+- [ ] **Step 8: Run the tests**
+
+Run: `bunx vitest run src/ui/PanePicker src/ui/icons`
+Expected: pass. Then `bun run typecheck && bun run lint`.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/ui/icons/Icons.ts src/ui/PanePicker
+git commit -m "ui: PanePicker, a standalone picker over /api/panes with peek and spawn"
+```
+
+---
+
+### Task 7: `NewRoomModal`
+
+**Files:**
+- Create: `src/ui/NewRoomModal.tsx`
+- Test: `src/ui/NewRoomModal.test.tsx`
+
+**Interfaces:**
+- Produces:
+
+```ts
+export interface NewRoomModalProps {
+  opened: boolean;
+  onClose: () => void;
+  /** After a successful create: the room, and the invite results when any were sent. */
+  onCreated: (room: string, results: InviteResult[]) => void;
+  daemonReachable?: boolean;
+}
+```
+
+  Uses `usePanePicker()` with `{ context: 'to invite to #<room>', allowCreate: true, disable }` where `disable` marks `agentStatus === 'blocked'` as `at a prompt · answer it first` and a pane whose `presence.rooms` contains the room as `in #<room>`.
+- Consumes: `POST /api/chat/rooms`, `POST /api/chat/invite`, `PaneRow` (without a checkbox, with the note input and a remove control in `extra`/`trailing`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `src/ui/NewRoomModal.test.tsx`:
+
+```tsx
+import { screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, expect, test, vi } from 'vitest';
+
+import { renderWithProviders } from '@ui/storybook/test-utils';
+import { fetchMock, installFetchMock } from '@ui/test-utils';
+import { NewRoomModal } from './NewRoomModal';
+import { PanePickerProvider } from './PanePicker';
+
+const PANES = [
+  { paneId: 'w1:p1', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', repo: 'assured', branch: 'main', agentStatus: 'idle' },
+  { paneId: 'w1:p2', workspace: 'chat', title: 'meg', cwd: '/r/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', presence: { handle: 'meg', status: 'live', rooms: ['codegen-split'] } },
+];
+
+function json(body: unknown, status = 200) {
+  return new Response(JSON.stringify(body), { status });
+}
+
+function mount(onCreated = vi.fn(), onClose = vi.fn()) {
+  renderWithProviders(
+    <PanePickerProvider>
+      <NewRoomModal opened onClose={onClose} onCreated={onCreated} />
+    </PanePickerProvider>
+  );
+  return { onCreated, onClose };
+}
+
+beforeEach(() => {
+  installFetchMock();
+  fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+    const path = String(url).split('?')[0];
+    if (path === '/api/panes') return json({ available: true, panes: PANES });
+    if (path === '/api/chat/rooms') return json({ room: JSON.parse(String(init?.body)).room, seedId: 9 });
+    if (path === '/api/chat/invite') return json({ results: [{ paneId: 'w1:p1', delivered: 'accepted' }] });
+    return json({});
+  });
+});
+
+test('the name field enforces the room charset before anything is sent', async () => {
+  mount();
+  await userEvent.type(screen.getByLabelText('Room'), 'Bad Room');
+  expect(screen.getByTestId('new-room-create')).toBeDisabled();
+  expect(await screen.findByText(/lowercase, digits, dashes/)).toBeInTheDocument();
+  expect(fetchMock.mock.calls.some(([u]) => String(u) === '/api/chat/rooms')).toBe(false);
+});
+
+test('pick panes opens the picker with the room as context and disables panes already in it; picked rows get a note', async () => {
+  mount();
+  await userEvent.type(screen.getByLabelText('Room'), 'codegen-split');
+  await userEvent.click(screen.getByTestId('new-room-pick'));
+  expect(await screen.findByText('to invite to #codegen-split')).toBeInTheDocument();
+  expect(within(screen.getByTestId('pane-row-w1:p2')).getByText('in #codegen-split')).toBeInTheDocument();
+  await userEvent.click(screen.getByTestId('pane-check-w1:p1'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  const picked = await screen.findByTestId('picked-w1:p1');
+  await userEvent.type(within(picked).getByLabelText('note for this pane'), 'you own vite');
+  expect(screen.getByTestId('new-room-create')).toHaveTextContent('invite 1');
+});
+
+test('submit creates, seeds, then invites in order, and reports the room and results', async () => {
+  const { onCreated } = mount();
+  await userEvent.type(screen.getByLabelText('Room'), 'codegen-split');
+  await userEvent.type(screen.getByLabelText('Seed'), 'Goal: halve the bundle');
+  await userEvent.click(screen.getByTestId('new-room-pick'));
+  await userEvent.click(await screen.findByTestId('pane-check-w1:p1'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  await userEvent.type(within(await screen.findByTestId('picked-w1:p1')).getByLabelText('note for this pane'), 'you own vite');
+  await userEvent.click(screen.getByTestId('new-room-create'));
+  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('codegen-split', [{ paneId: 'w1:p1', delivered: 'accepted' }]));
+  const calls = fetchMock.mock.calls.map(([u, i]) => [String(u), i as RequestInit | undefined] as const);
+  const rooms = calls.findIndex(([u]) => u === '/api/chat/rooms');
+  const invite = calls.findIndex(([u]) => u === '/api/chat/invite');
+  expect(rooms).toBeGreaterThan(-1);
+  expect(invite).toBeGreaterThan(rooms);
+  expect(JSON.parse(String(calls[rooms]![1]!.body))).toEqual({ room: 'codegen-split', seed: 'Goal: halve the bundle', wakeOn: 'mention' });
+  expect(JSON.parse(String(calls[invite]![1]!.body))).toEqual({ room: 'codegen-split', panes: [{ paneId: 'w1:p1', note: 'you own vite' }] });
+});
+
+test('create without inviting skips the invite route', async () => {
+  const { onCreated } = mount();
+  await userEvent.type(screen.getByLabelText('Room'), 'quiet');
+  await userEvent.click(screen.getByTestId('new-room-create-only'));
+  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('quiet', []));
+  expect(fetchMock.mock.calls.some(([u]) => String(u) === '/api/chat/invite')).toBe(false);
+});
+
+test('a failed create keeps the draft and reports the error', async () => {
+  fetchMock.mockImplementation(async (url: string) =>
+    String(url) === '/api/chat/rooms' ? json({ error: 'rt daemon unreachable' }, 502) : json({ available: true, panes: [] })
+  );
+  const { onCreated } = mount();
+  await userEvent.type(screen.getByLabelText('Room'), 'x');
+  await userEvent.type(screen.getByLabelText('Seed'), 'keep me');
+  await userEvent.click(screen.getByTestId('new-room-create-only'));
+  expect(await screen.findByText(/rt daemon unreachable/)).toBeInTheDocument();
+  expect(screen.getByLabelText('Seed')).toHaveValue('keep me');
+  expect(onCreated).not.toHaveBeenCalled();
+});
+```
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/ui/NewRoomModal.test.tsx`
+Expected: FAIL, module not found.
+
+- [ ] **Step 3: Write the modal**
+
+`src/ui/NewRoomModal.tsx`, built on `useForm` + `zodResolver` from `@ui/forms` (schema: `room` matching `/^[a-z0-9._-]+$/` with the message `lowercase, digits, dashes`, `seed` any string, `wakeOn` enum `mention | all`), `FormContainer` with `plain` and `hideChrome`, `TextInput` (`label="Room"`, `leftSection` a muted `#`, the hint `lowercase, digits, dashes · the room exists once you post the seed`), `Textarea` (`label="Seed"`, `autosize`, `minRows={4}`, the two hints `posted as matt · every invitee is told to read it first` and `markdown subset · blank line between points`), a `Select` for `wakeOn` (`aria-label="Wakes"`, data `mention`/`all`, hint `all = a war room, nobody has to @here`), the Agents section (header `AGENTS · N to invite`, a `pick panes` button `data-testid="new-room-pick"` that calls `pickPanes({ context: \`to invite to #${room || '…'}\`, allowCreate: true, disable, preselected: picked.map(p => p.paneId) })` and replaces the picked list with the result when it is not `null`), one `PaneRow` per picked pane inside `data-testid={\`picked-${paneId}\`}` with `extra` = a `TextInput` (`aria-label="note for this pane"`, placeholder `note for this pane (optional)`) and `trailing` = a remove `UnstyledButton` (`aria-label="Remove"`, the `close` icon), and the footer: `Create without inviting` (`data-testid="new-room-create-only"`) and `Create #<room> · invite N` (`data-testid="new-room-create"`), both disabled while the form is invalid or a submit is in flight. Submit:
+
+```ts
+async function submit(invite: boolean) {
+  setBusy(true);
+  setError(undefined);
+  try {
+    const res = await fetch('/api/chat/rooms', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ room: values.room, seed: values.seed || undefined, wakeOn: values.wakeOn }) });
+    if (!res.ok) throw new Error(((await res.json()) as { error?: string }).error ?? 'create failed');
+    let results: InviteResult[] = [];
+    if (invite && picked.length > 0) {
+      const inv = await fetch('/api/chat/invite', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ room: values.room, panes: picked.map(p => ({ paneId: p.paneId, ...(notes[p.paneId]?.trim() ? { note: notes[p.paneId] } : {}) })) }) });
+      if (!inv.ok) throw new Error(((await inv.json()) as { error?: string }).error ?? 'invite failed');
+      results = ((await inv.json()) as { results: InviteResult[] }).results;
+    }
+    onCreated(values.room, results);
+    form.reset();
+    setPicked([]);
+    setNotes({});
+  } catch (err) {
+    setError(err instanceof Error ? err.message : String(err));
+  } finally {
+    setBusy(false);
+  }
+}
+```
+
+The error renders as `<Text size="xs" c="bad">` under the footer (`hideChrome` means the form owns error display). The modal is a Mantine `Modal` (`size={680}`, `fullScreen` on `useIsMobile()`), title `New room` with the `hash` icon, `closeOnClickOutside`/`closeOnEscape` false while `busy`. `daemonReachable === false` disables both submit buttons with the hint `rt daemon unreachable · the draft is kept`.
+
+- [ ] **Step 4: Run the tests**
+
+Run: `bunx vitest run src/ui/NewRoomModal.test.tsx && bun run typecheck && bun run lint`
+Expected: pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ui/NewRoomModal.tsx src/ui/NewRoomModal.test.tsx
+git commit -m "ui: NewRoomModal creates, seeds and invites through the pane picker"
+```
+
+---
+
+### Task 8: entry points, the notice line, and App wiring
+
+**Files:**
+- Modify: `src/ui/RoomRail.tsx` (props `daemonReachable?`, `onNewRoom?`; the 24px `+`)
+- Modify: `src/ui/PageBar.tsx` (prop `onAddAgents?`; the `add agents` button before `mark read`)
+- Modify: `src/ui/Transcript.tsx` (prop `notice?: ReactNode`, rendered as an edge row above `OlderEdge`)
+- Modify: `src/app/App.tsx` (`usePanesAvailable`, `PanePickerProvider`, `NewRoomModal` state, `add agents` flow, the notice state)
+- Test: `src/ui/RoomRail.test.tsx`, `src/ui/PageBar.test.tsx`, `src/ui/Transcript.test.tsx`, `src/app/App.test.tsx`
+
+**Interfaces:**
+- `RoomRailProps` gains `daemonReachable?: boolean` (default `true`) and `onNewRoom?: () => void`; the `+` renders only when `onNewRoom` is given, disabled when `daemonReachable` is false, `aria-label="New room"`, `data-testid="new-room-button"`.
+- `PageBarProps` gains `onAddAgents?: () => void`; the button renders only when given, disabled when `reachable` is false, `aria-label` `Add agents to #<room>`, `data-testid="add-agents-button"`.
+- `TranscriptProps` gains `notice?: ReactNode`; rendered in `data-testid="transcript-notice"` with the `.edge` values (`padding: 6px 0 4px`, 10.56px, muted) but `textAlign: left`.
+- App: `usePanesAvailable()` polls `GET /api/panes` once on mount and every 30s, returns `boolean | undefined`; both entry points are passed only when it is `true`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/ui/RoomRail.test.tsx`:
+
+```tsx
+test('the + renders only with onNewRoom, disables with the daemon down, and fires', async () => {
+  const onNewRoom = vi.fn();
+  const rooms = [{ room: 'build', memberCount: 1, unread: 0, mentions: 0 }];
+  const { rerender } = renderWithProviders(<RoomRail rooms={rooms} />);
+  expect(screen.queryByTestId('new-room-button')).toBeNull();
+  rerender(<RoomRail rooms={rooms} onNewRoom={onNewRoom} daemonReachable={false} />);
+  expect(screen.getByTestId('new-room-button')).toBeDisabled();
+  rerender(<RoomRail rooms={rooms} onNewRoom={onNewRoom} />);
+  await userEvent.click(screen.getByRole('button', { name: 'New room' }));
+  expect(onNewRoom).toHaveBeenCalled();
+});
+```
+
+Append to `src/ui/PageBar.test.tsx` (mirror its existing render helper):
+
+```tsx
+test('add agents sits before mark read, only when wired, disabled while the daemon is down', async () => {
+  const onAddAgents = vi.fn();
+  const room = { room: 'build', memberCount: 2, unread: 3, mentions: 0 };
+  const { rerender } = renderWithProviders(<PageBar room={room} buddies={[]} />);
+  expect(screen.queryByTestId('add-agents-button')).toBeNull();
+  rerender(<PageBar room={room} buddies={[]} onAddAgents={onAddAgents} reachable={false} />);
+  expect(screen.getByTestId('add-agents-button')).toBeDisabled();
+  rerender(<PageBar room={room} buddies={[]} onAddAgents={onAddAgents} onMarkRead={() => {}} />);
+  const buttons = screen.getAllByRole('button').map(b => b.getAttribute('data-testid'));
+  expect(buttons.indexOf('add-agents-button')).toBeLessThan(buttons.indexOf('mark-read-button'));
+  await userEvent.click(screen.getByRole('button', { name: 'Add agents to #build' }));
+  expect(onAddAgents).toHaveBeenCalled();
+});
+```
+
+Append to `src/ui/Transcript.test.tsx` (use the file's own render helper):
+
+```tsx
+test('a notice renders at the edge, above the older-messages row', () => {
+  renderTranscript({ notice: <span>invited 2 · assured accepted</span> });
+  const notice = screen.getByTestId('transcript-notice');
+  expect(notice).toHaveTextContent('invited 2 · assured accepted');
+  expect(notice.compareDocumentPosition(screen.getByTestId('transcript-edge')) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+});
+```
+
+Append to `src/app/App.test.tsx`:
+
+```tsx
+test('the entry points hide while herdr is unavailable and show once /api/panes says available', async () => {
+  installFetchMock();
+  fetchMock.mockImplementation(async (url: string) => new Response(JSON.stringify(String(url).startsWith('/api/panes') ? { available: false, panes: [] } : {})));
+  window.history.replaceState(null, '', '/r/build');
+  const { unmount } = renderWithProviders(<App initialState={twoRooms} />);
+  await act(async () => {});
+  expect(screen.queryByTestId('new-room-button')).toBeNull();
+  expect(screen.queryByTestId('add-agents-button')).toBeNull();
+  unmount();
+  fetchMock.mockImplementation(async (url: string) => new Response(JSON.stringify(String(url).startsWith('/api/panes') ? { available: true, panes: [] } : {})));
+  renderWithProviders(<App initialState={twoRooms} />);
+  expect(await screen.findByTestId('new-room-button')).toBeInTheDocument();
+  expect(screen.getByTestId('add-agents-button')).toBeInTheDocument();
+});
+
+test('add agents invites the picked panes and shows the result line on the transcript edge', async () => {
+  installFetchMock();
+  fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
+    const path = String(url).split('?')[0];
+    if (path === '/api/panes') return new Response(JSON.stringify({ available: true, panes: [{ paneId: 'w1:p4', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', agentStatus: 'idle' }] }));
+    if (path === '/api/chat/invite' && init?.method === 'POST') return new Response(JSON.stringify({ results: [{ paneId: 'w1:p4', delivered: 'accepted' }] }));
+    return new Response(JSON.stringify({}));
+  });
+  window.history.replaceState(null, '', '/r/build');
+  renderWithProviders(<App initialState={{ ...twoRooms, messages: [{ id: 1, room: 'build', handle: 'meg', body: 'hi', postedAt: 1 }] }} />);
+  await userEvent.click(await screen.findByTestId('add-agents-button'));
+  await userEvent.click(await screen.findByTestId('pane-check-w1:p4'));
+  await userEvent.click(screen.getByTestId('pane-use'));
+  expect(await screen.findByTestId('transcript-notice')).toHaveTextContent('invited 1 · assured pane accepted');
+});
+```
+
+(Adjust the seeded message's shape to the `ChatMessage` fields the file already uses.)
+
+- [ ] **Step 2: Run to verify failure**
+
+Run: `bunx vitest run src/ui/RoomRail.test.tsx src/ui/PageBar.test.tsx src/ui/Transcript.test.tsx src/app/App.test.tsx`
+Expected: the new tests FAIL.
+
+- [ ] **Step 3: RoomRail and PageBar**
+
+`RoomRail.tsx`: add the two props; in the header `Group`'s right side, wrap the count and a 24px `UnstyledButton` (`data-testid="new-room-button"`, `aria-label="New room"`, `disabled={!daemonReachable}`, `onClick={onNewRoom}`, `<Icon name="plus" size={14} />`, the `.aicon` treatment: 6px radius, muted colour, `bg4` on hover) in a `Group gap={2} wrap="nowrap"`.
+
+`PageBar.tsx`: in `controls`, before the `mark read` button, when `onAddAgents`:
+
+```tsx
+      {onAddAgents && (
+        <Button
+          variant="default"
+          size="xs"
+          radius="md"
+          data-testid="add-agents-button"
+          aria-label={`Add agents to #${room.room}`}
+          onClick={onAddAgents}
+          disabled={!reachable}
+          leftSection={<Icon name="userPlus" size={14} />}
+          styles={{ root: CONTROL_SURFACE }}
+        >
+          add agents
+        </Button>
+      )}
+```
+
+with a 7.2px gap to the next control (`mr={7.2}` on the button or a spacer `Box w={7.2}`).
+
+- [ ] **Step 4: Transcript notice**
+
+In `Transcript.tsx`, add `notice?: ReactNode` to `TranscriptProps` and render, above the `OlderEdge` mount:
+
+```tsx
+            {notice && (
+              <Box
+                data-testid="transcript-notice"
+                style={{ padding: '6px 0 4px', textAlign: 'left', fontSize: '10.56px', color: 'var(--tk-muted-text)' }}
+              >
+                {notice}
+              </Box>
+            )}
+```
+
+- [ ] **Step 5: App wiring**
+
+In `src/app/App.tsx`:
+
+1. `usePanesAvailable()`:
+
+```ts
+function usePanesAvailable(): boolean | undefined {
+  const [available, setAvailable] = useState<boolean | undefined>(undefined);
+  const probe = useCallback(() => {
+    fetch('/api/panes')
+      .then(res => res.json())
+      .then((data: { available?: boolean }) => setAvailable(data.available === true))
+      .catch(() => setAvailable(false));
+  }, []);
+  useEffect(() => {
+    probe();
+  }, [probe]);
+  useInterval(probe, 30_000);
+  return available;
+}
+```
+
+2. State: `const panesAvailable = usePanesAvailable(); const [newRoomOpen, setNewRoomOpen] = useState(false); const [notice, setNotice] = useState<{ room: string; node: ReactNode } | null>(null);` and `const pickPanes = usePanePicker();` inside a child component that lives under `PanePickerProvider` (wrap the existing `AppChrome` subtree: `<BuddiesProvider ...><PanePickerProvider><AppChrome>...` and move the room page body into an inner component `ChatPage` that can call `usePanePicker()`), or keep App flat and put the `add agents` handler in a small `AddAgentsButtonHost`. The simplest: make `PanePickerProvider` wrap `<AppChrome>` inside `BuddiesProvider`, and move the JSX from `chatRoute ? (...)` into `function ChatPage(props)` rendered inside the provider.
+3. `resultLine(results: InviteResult[], panes: ChatPane[])`:
+
+```tsx
+export function resultLine(results: InviteResult[], panes: ChatPane[]): ReactNode {
+  const label = (r: InviteResult) => {
+    const pane = panes.find(p => p.paneId === r.paneId);
+    const name = pane?.presence?.handle ?? (pane?.workspace ? `${pane.workspace} pane` : r.paneId);
+    if (r.delivered === 'accepted') return <span key={r.paneId} style={{ color: 'var(--mantine-color-ok-text)' }}>{name} accepted</span>;
+    if (r.delivered === 'queued') return <span key={r.paneId} style={{ color: 'var(--mantine-color-warn-text)' }}>{name} queued (working)</span>;
+    return <span key={r.paneId} style={{ color: 'var(--mantine-color-bad-text)' }}>{name} refused: {r.reason ?? 'unknown'}</span>;
+  };
+  return (
+    <>
+      invited {results.length}
+      {results.map(r => (<span key={r.paneId}> · {label(r)}</span>))}
+      {' · members appear as they sign in'}
+    </>
+  );
+}
+```
+
+4. `add agents` handler on the open room:
+
+```ts
+async function addAgents() {
+  if (!activeRoom) return;
+  const picked = await pickPanes({
+    context: `to invite to #${activeRoom}`,
+    allowCreate: true,
+    disable: p => (p.agentStatus === 'blocked' ? 'at a prompt · answer it first' : p.presence?.rooms.includes(activeRoom) ? `in #${activeRoom}` : null),
+  });
+  if (!picked || picked.length === 0) return;
+  try {
+    const res = await fetch('/api/chat/invite', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ room: activeRoom, panes: picked.map(p => ({ paneId: p.paneId })) }) });
+    if (!res.ok) throw new Error('invite failed');
+    const { results } = (await res.json()) as { results: InviteResult[] };
+    setNotice({ room: activeRoom, node: resultLine(results, picked) });
+  } catch {
+    notifications.error("Couldn't invite; nothing was typed into any pane.");
+  }
+}
+```
+
+5. `NewRoomModal` mounted with `opened={newRoomOpen}`, `onClose={() => setNewRoomOpen(false)}`, `daemonReachable={daemon.reachable}`, `onCreated={(room, results) => { setNewRoomOpen(false); refetchRooms(); selectRoom(room); if (results.length) setNotice({ room, node: resultLine(results, []) }); }}`. Since `NewRoomModal` knows the picked panes, extend `onCreated` to pass them too (`onCreated(room, results, picked)`) so names resolve; update the Task 7 interface accordingly.
+6. Pass `onNewRoom={panesAvailable ? () => setNewRoomOpen(true) : undefined}` and `daemonReachable={daemon.reachable}` to `RoomRail`; `onAddAgents={panesAvailable ? addAgents : undefined}` to `PageBar`; `notice={notice?.room === activeRoom ? notice.node : undefined}` to `Transcript`. Clear the notice when the room changes: `useEffect(() => { if (notice && notice.room !== activeRoom) setNotice(null); }, [activeRoom, notice]);` (drop this if the `room ===` gate above is enough for the tests; the spec says the line lasts until the next room change).
+
+- [ ] **Step 6: Run the suite**
+
+Run: `bunx vitest run && bun run typecheck && bun run lint`
+Expected: pass.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/ui/RoomRail.tsx src/ui/PageBar.tsx src/ui/Transcript.tsx src/app/App.tsx src/ui/RoomRail.test.tsx src/ui/PageBar.test.tsx src/ui/Transcript.test.tsx src/app/App.test.tsx src/ui/NewRoomModal.tsx
+git commit -m "app: + in the rail, add agents in the page bar, invite results at the transcript edge"
+```
+
+---
+
+### Task 9: artboards, anatomy, audit
+
+**Files:**
+- Modify: `design/build.py` (CSS block, ICON dict, four generators, canvas entries), `design/artboards/*.dc.html` (regenerated), `design/canvas.json`, `design/spec.json` (regenerated), `design/ANATOMY.md`, `design/audit.mjs`, `design/README.md`
+
+**Interfaces:**
+- Produces: artboards `NewRoom.dc.html`, `PanePicker.dc.html`, `NewPane.dc.html`, `EntryPoints.dc.html`; `TARGETS` for `.pop` (the picker modal shell), `.pane`, `.cb`, `.peek`, `.btn.sm` (`add agents`), the rail `+` (`.aicon`), and the notice row (`.edge`).
+
+- [ ] **Step 1: Fold the mockup generator into `design/build.py`**
+
+The mockup generator is `/private/tmp/claude-501/-Users-matt-Documents-GitHub-chat/cb0994ad-4a10-49da-9f0f-b84d14861d54/scratchpad/pane-browser/build.py` (if that path is gone, the canvas at https://claude.ai/code/artifact/93d55ea7-54c1-4866-9685-bdc3b605661b holds the same four artboards; re-derive the generators from their markup). Into `design/build.py`:
+
+1. Append its `EXTRA` CSS rules to the `CSS = r"""..."""` block (inside it; `extract-spec.py` only parses that block). Keep `.pane + .pane` as the row separator rule.
+2. Add its five `ICON` entries (`plus`, `x`, `eye`, `userplus`, `search`) to the `ICON` dict.
+3. Paste its `PANES` table and the functions `pane_row`, `pane_list`, `picked_row`, `picked_list`, `new_room`, `picker`, `new_pane`, `entry_points` as module-level defs, using the repo's own `head()`/`tail()` (dark default `false`), and renaming the New room output to `NewRoom.dc.html`.
+4. Add four `write_text` lines and four `canvas` entries placed below `y: 3060` (the laws note): `NewRoom` at `(0, 3200, 900, 900)`, `PanePicker` at `(1000, 3200, 820, 960)`, `NewPane` at `(1920, 3200, 720, 760)`, `EntryPoints` at `(0, 4300, 900, 560)`, plus the two annotations (`brief`, `states`) with matching `y` offsets. Update the final `print` count.
+
+Run from `design/artboards`: `python3 ../build.py && cd .. && python3 extract-spec.py`. Expected: the four new files exist, `spec.json` gains the new selectors (`grep -c '"\.pane"' design/spec.json` is 1).
+
+- [ ] **Step 2: ANATOMY**
+
+Add to `design/ANATOMY.md`, after the Composer section:
+
+```markdown
+## Pane picker — Task 6
+
+A `.pop` modal, 640px (a full-height drawer on phones). Header: the terminal
+icon, `Pick herdr panes` at 20px / 700, the caller's context in `.sm.muted`.
+Then the filter `.input` (30px, 11.2px, search icon), a count line in
+`.xs.muted` (`N panes running Claude · sorted listening, idle, deaf, not
+signed in`) with `N selected` and, with `allowCreate`, a `.btn.sm` `new pane`
+on the right. The list is a `.card` on `bg2`, `padding: 2px 0`, rows
+separated by `--border-soft`.
+
+Each row is a `.pane` (`gap: 9.6px`, `padding: 8.4px 9.6px`, radius 6px,
+`align-items: flex-start`); `.pane.on` carries the accent wash, `.pane.na`
+is `opacity: 0.55; cursor: default`.
+
+| part | detail |
+| --- | --- |
+| checkbox | `.cb`, 16px, radius 4px; `.cb.on` accent-deep with a 11px check; `.cb.off` on `bg4` with a muted border for a row the caller disabled |
+| dot | 8px `.dot` at `margin-top: 5px`, status colour; `.dot.off` hollow for a pane with no presence |
+| who | the handle at `.sm` / 600, or `not signed in` in `.sm.muted` |
+| where | `.xs.muted.truncate`, the workspace, plus ` · <title>` when the title is not the handle |
+| state | `.state` on the right: `.working` (warn) `working · queues until its turn ends`, `.blocked` (bad) `at a prompt · answer it first`, `.idle` muted; a caller's reason replaces it |
+| eye | a 22px `.aicon` |
+| line 2 | `repo · branch` in `.xs.muted`, then `.tag`s for rooms |
+| path | `…/leaf`, `.xs.muted`, real text (never `direction: rtl`) |
+| peek | `.peek` inside the row: `bg1`, hairline, radius 4px, 11.2px, `white-space: pre`, own `overflow-x`; the prompt line in `--fg` |
+
+Footer: a `.hint` (`the eye peeks at a pane's last lines...`), `Cancel`
+(`.btn`), `Use N panes` (`.btn.primary`).
+
+**New pane** is a second view in the same modal: back arrow + `New pane` +
+`a herdr tab running Claude`; `.field`s (`.lbl2` label, `.input`, `.hint`)
+for Directory (with a `.card` of `.opt` suggestions), a 2-column grid of
+Account / Model then Effort / Workspace, and the Opening prompt `.area`;
+footer hint with the launch command, `Back`, `Start pane`.
+
+## New room — Task 7
+
+A `.pop` modal, 680px. Header: hash icon + `New room`. `.field`s: Room
+(`#` prefix, hint `lowercase, digits, dashes · the room exists once you
+post the seed`), Seed (`.input.area`, 96px min, hints `posted as matt · every
+invitee is told to read it first` and `markdown subset · blank line between
+points`), Wakes (a `.chip` select, hint `all = a war room, nobody has to
+@here`). The Agents section: `AGENTS · N to invite` with `pick panes`
+(`.btn.sm`, terminal icon) on the right; a `.card` of `.pane` rows without
+checkboxes, each with a remove `.aicon` and a 28px note `.input`. Footer:
+the hint (`N invites · <handle> picks it up when its turn ends`), `Create
+without inviting` (`.btn`), `Create #<room> · invite N` (`.btn.primary`).
+
+## Entry points — Task 8
+
+The rooms rail header gains a 24px `.aicon` `+` beside the count. The page
+bar gains `add agents` (`.btn.sm`, user-plus icon) before `mark read`. After
+an invite the transcript opens with a `.edge` row, left-aligned: `invited 2 ·
+<ok>assured pane accepted</ok> · <warn>fred queued (working)</warn> ·
+members appear as they sign in`. Both entry points hide when rt reports
+herdr unavailable and disable with the daemon down.
+```
+
+- [ ] **Step 3: Audit targets**
+
+In `design/audit.mjs`'s `TARGETS`, add:
+
+```js
+  { spec: '.pane', find: '[data-testid^="pane-row-"]', props: ['display', 'align-items', 'gap', 'border-radius', 'min-width', 'padding'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye' } },
+  { spec: '.cb', find: '[data-testid^="pane-check-"]', props: ['width', 'height', 'border-radius', 'display', 'align-items', 'justify-content'] },
+  { spec: '.peek', find: '[data-testid^="pane-peek-"]:not([data-testid^="pane-peek-button-"])', props: ['padding', 'background', 'border-radius', 'font-size', 'line-height', 'white-space', 'overflow-x', 'color'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye', 'white-space': WHITE_SPACE_NOT_ENUMERATED, 'line-height': LINE_HEIGHT_RESOLVES_TO_PX } },
+  { spec: '.btn.sm', find: '[data-testid="add-agents-button"]', props: ['height', 'font-size', 'font-weight', 'border-radius'] },
+  { spec: '.edge', find: '[data-testid="transcript-notice"]', props: ['padding', 'font-size'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye' } },
+```
+
+and, for the picker's modal shell, a `.pop` entry finding `[data-testid="pane-picker"] .mantine-Modal-content` (check the class Mantine 9.5 renders for the content box in its docs) with the same props and `why` as the existing `.pop` entry.
+
+- [ ] **Step 4: Run the audit against the fixtures server**
+
+The audit needs the picker open, so it takes two captures (CONFORMANCE.md's documented flow, driven with Fast Browser):
+
+```bash
+bun run build
+CHAT_FIXTURES=1 PORT=3111 bun src/server/index.ts &
+node design/audit.mjs --probe > /Users/matt/.fast-browser/chat-shots/probe.js
+```
+
+Then with Fast Browser: navigate to `http://localhost:3111/r/build`, run the probe with `browser_evaluate` writing to `/Users/matt/.fast-browser/chat-shots/computed-page.json`; click `[data-testid="add-agents-button"]`, wait for `[data-testid="pane-row-w7A:pY"]`, click `[data-testid="pane-peek-button-w7A:pY"]`, wait for `[data-testid="pane-peek-w7A:pY"]`, run the probe again to `computed-picker.json`. Then:
+
+```bash
+node design/audit.mjs /Users/matt/.fast-browser/chat-shots/computed-page.json
+node design/audit.mjs /Users/matt/.fast-browser/chat-shots/computed-picker.json
+```
+
+Expected: every target either passes or is absent from that capture (the page capture has no picker rows; the picker capture has both). Fix any value mismatch in the component, not in the artboard, and re-run. Repeat once in dark (`--scheme dark`). Kill the server.
+
+- [ ] **Step 5: README and commit**
+
+Add the four artboards to `design/README.md`'s file table. Then:
+
+```bash
+git add design
+git commit -m "design: pane picker, new room, new pane and entry-point artboards, anatomy and audit targets"
+```
+
+---
+
+### Task 10: final wiring, docs, PR
+
+**Files:**
+- Modify: `package.json` (if Task 1 used `file:`), `ARCHITECTURE.md` (routes and the picker in the client section), `design/CONFORMANCE.md` (the "not built" list)
+
+- [ ] **Step 1: The rt-client pin**
+
+If `package.json` carries `file:../repo-tools-chat-invite/...`, check `npm view @mattstack/rt-client version`. When `0.6.2` is published: `bun add @mattstack/rt-client@^0.6.2`, `bunx vitest run`, commit. If it is not published yet, stop here and report: the PR waits on the publish; do not open a PR with a `file:` dependency.
+
+- [ ] **Step 2: Docs**
+
+In `ARCHITECTURE.md`: add the five `/api/panes*` rows and the two `POST /api/chat/*` rows to the API table; in "Live updates" note that the room page refetches `who` on `chat/<room>/msg`; add a short "Panes" paragraph: `PanePicker` (provider + `usePanePicker()`), `NewRoomModal`, the two entry points, and that both hide when `GET /api/panes` reports `available: false`. In `design/CONFORMANCE.md`, under "Two things drawn that are deliberately not built", note that "no route addresses a pane by id" is no longer true for the picker (`/api/panes/:id/peek`) and stays true for the roster row.
+
+- [ ] **Step 3: Full check and PR**
+
+```bash
+bun run typecheck && bun run lint && bunx vitest run && bun run build && bun run format:check
+git add ARCHITECTURE.md design/CONFORMANCE.md package.json bun.lock
+git commit -m "docs: pane routes, the picker, and the members refetch in ARCHITECTURE"
+git push -u origin feat/pane-invite
+gh pr create --title "Create rooms and invite herdr panes from the viewer" --body-file - <<'EOF'
+## Rooms from the viewer, agents from herdr panes
+
+Create a room, seed it, and invite or spawn herdr panes into it without leaving the chat. Spec: repo-tools `docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md`; canvas: https://claude.ai/code/artifact/93d55ea7-54c1-4866-9685-bdc3b605661b.
+
+### What changed
+
+**Server** (`src/server/panes.ts`, `chat.ts`)
+
+- `GET /api/panes`, `/accounts`, `/directories`, `/:id/peek`, `POST /api/panes` over rt-client's pane wrappers
+- `POST /api/chat/rooms` joins as the human and posts the seed; `POST /api/chat/invite` types `/chat:join` into each pane in order
+- herdr absent is `available: false`, not an error; fixtures for every route
+
+**Client**
+
+- `PanePicker`: provider-hosted, `usePanePicker()` resolves with the picked rows; filter, sort, peek, caller `disable`, `allowCreate` with the New pane form
+- `NewRoomModal`: name, seed, wake mode, picked panes with notes; create, seed, invite in order
+- `+` in the rooms rail, `add agents` in the page bar, the result line at the transcript edge
+- members refetch on `chat/<room>/msg`
+
+**Design**
+
+- Four artboards in `build.py`, anatomy sections, audit targets; audit green against fixtures in both schemes
+
+### Follow-up
+
+- Focusing a pane from the roster is a future picker caller (CONFORMANCE.md).
+EOF
+```
+
+---
+
+## Self-review
+
+**Spec coverage.** Routes table incl. `available: false` and 400 rules: Tasks 3, 4. Fixtures: Task 2. PanePicker contract (`context`, `multiple`, `disable`, `preselected`, `allowCreate`), owns fetch/filter/sort/peek/selection, resolves rows or `null`, New pane form fields and the `starting`/`ready:false` behaviour, herdr-unavailable notice: Task 6. New room form fields, picked list with notes, submit order, draft kept on failure: Task 7. Entry points (`+`, `add agents`), hide when unavailable, disable when the daemon is down, the notice line until the next room change, `who` refetch on `chat/<room>/msg`: Tasks 5 and 8. Phone drawers with 44px controls: Tasks 6 and 7 (`fullScreen` on `useIsMobile`). Path rendering via `headTruncatePath`: Task 6. Artboards into `build.py`, ANATOMY, audit TARGETS incl. the open-modal capture: Task 9. Delivery order and the rt-client pin: Tasks 1 and 10.
+
+**Placeholders.** None. Task 6 Step 6 (`NewPaneForm`) and Task 7 Step 3 describe the components in prose with every field, label, test id and behaviour named rather than pasting a second 200-line file; both have tests that pin the behaviour.
+
+**Type consistency.** `ChatPane`, `InviteResult`, `PaneAccount`, `PaneDirectory`, `AgentStatus` are rt-client's (re-exported from `src/ui/PanePicker/types.ts`). `PickPanesOptions`/`PickPanes` (Task 6) are what Task 7 and Task 8 call. Test ids are consistent across tasks: `pane-row-<id>`, `pane-check-<id>`, `pane-peek-button-<id>`, `pane-peek-<id>`, `pane-filter`, `pane-new`, `pane-start`, `pane-back`, `pane-use`, `pane-cancel`, `pane-picker`, `picked-<id>`, `new-room-pick`, `new-room-create`, `new-room-create-only`, `new-room-button`, `add-agents-button`, `transcript-notice`, `transcript-edge`. `onCreated(room, results, picked)` is the Task 8 amendment to Task 7's interface; both tasks say so.
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
new file mode 100644
index 00000000..a564ea47
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
@@ -0,0 +1,210 @@
+# rt chat invite, part 3: the `/chat:join` skill (mattstack-marketplace)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship the `/chat:join <room> [note from <handle>: <text>]` skill in the `chat` Claude Code plugin, the text that `rt chat invite` types into a pane, so an invited agent signs in, joins, arms its tail, reads the seed and announces itself.
+
+**Architecture:** One new skill directory in the plugin (`plugins/chat/skills/join/SKILL.md`) registered in `plugin.json`, version bumped, validated with `claude plugin validate --strict`, then the installed copy refreshed and the skill exercised once for real in a herdr pane. No hooks change. The skill leans on rt verbs that part 1 of this feature ships (`rt chat join`, `rt chat read --last`); it must be executed after part 1 is installed as the machine's `rt`.
+
+**Tech Stack:** Claude Code plugin manifest (`.claude-plugin/plugin.json`), SKILL.md frontmatter, the `claude plugin` CLI, herdr CLI for the real run.
+
+**Spec:** `docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md` (this worktree), sections "Skills", "Testing", "Delivery order" step 3.
+
+## Global Constraints
+
+- Work in a worktree of `~/Documents/GitHub/mattstack-marketplace`, never its main checkout: `git -C ~/Documents/GitHub/mattstack-marketplace worktree add ~/Documents/GitHub/mattstack-marketplace-chat-join -b feat/chat-join` then `cd` there.
+- Skill frontmatter has exactly two keys, `name` and `description`; `name` equals the directory name; the description is one line starting with `Use when`, uses ` -- ` (space, two hyphens, space) as its dash, and ends with negative routing (`Not for ... (see ...)`). Never an em dash or en dash anywhere in the plugin.
+- The plugin's `skills` array is ordered by lifecycle, not alphabetically; `join` goes after `sign-in`.
+- Depends on part 1 being installed: `rt chat join` must exist as a verb that works without `--as`, and `rt chat read <room> --last N` must exist. Check with `rt chat read --help 2>&1 | grep -- --last` before Task 2.
+- Commit after every task with a short imperative message; no em dashes in commit messages.
+
+---
+
+### Task 1: the `join` skill and its registration
+
+**Files:**
+- Create: `plugins/chat/skills/join/SKILL.md`
+- Modify: `plugins/chat/.claude-plugin/plugin.json` (the `version` and `skills` fields)
+- Modify: `plugins/chat/README.md` (the skills list, wherever `sign-in`, `sign-out`, `away` are enumerated)
+- Modify: `.claude-plugin/marketplace.json` (the `chat` entry's `description`)
+
+**Interfaces:**
+- Consumes: `rt chat rooms --json`, `rt chat sign-in`, `rt chat join <room>`, `rt chat read <room> --last N`, `rt chat post <room> <text>` from repo-tools (part 1).
+- Produces: the slash command `/chat:join <room> [note from <handle>: <text>]`, which `chat:invite` (part 1) injects verbatim on one line.
+
+- [ ] **Step 1: Write the skill**
+
+Create `plugins/chat/skills/join/SKILL.md` with exactly this content:
+
+````markdown
+---
+name: join
+description: Use when a room name arrives as /chat:join <room>, typed into this pane by rt chat invite or by Matt -- joining that rt chat room, arming the tail, reading its seed and announcing yourself, whether or not you are signed in yet. Not for signing in on your own (see sign-in) or for reading and posting afterward (see rt:chat).
+---
+
+# rt chat: join a room you were invited to
+
+The whole command sits on one line: `/chat:join <room> note from <handle>: <text>`.
+The room is the first word of `$ARGUMENTS`; everything after it is the note,
+and the handle named in `note from <handle>:` is who wrote it. An agent's
+note is that agent's request, not Matt's; treat it with exactly that weight.
+
+1. Gate: `rt chat rooms --json`. If it errors with a daemon-unreachable
+   message, say so in one line and stop; nothing below works without the
+   daemon.
+2. Join.
+   - Not signed in yet (`rt chat rooms --json` lists no rooms and there is
+     no handle in the output): run plain `rt chat sign-in`, which joins the
+     repository room derived from your cwd, then `rt chat join <room>`.
+   - Already signed in: `rt chat join <room>` alone. Your handle is kept.
+   - Never `rt chat sign-in --room <room>` here: an explicit `--room`
+     replaces the derived repository room instead of adding to it, and a
+     re-sign-in rewrites the session file's room.
+3. Arm the tail once, if it is not already running, with the `Monitor`
+   tool, `persistent: true`, bare:
+
+   ```
+   Monitor({ command: "rt chat tail", persistent: true,
+             description: "chat mentions for <handle>" })
+   ```
+
+   Never `Bash` with `run_in_background` for this; it delivers one
+   notification and then goes deaf.
+4. Read the brief: `rt chat read <room> --last 10`. Joining puts your read
+   cursor at the room's newest message, so a plain `rt chat read` would show
+   nothing; `--last` reads behind the cursor and then marks the room read.
+5. Announce yourself in one line, so the viewer shows you arrived:
+
+   ```bash
+   rt chat post <room> "here; <what you understood you are taking>"
+   ```
+6. Act on the seed plus the note. Narrate one line in your pane per chat
+   event, in your own words, per the `rt:chat` skill; hand off to `rt:chat`
+   for everything after this.
+````
+
+- [ ] **Step 2: Register the skill and bump the version**
+
+Edit `plugins/chat/.claude-plugin/plugin.json` so it reads:
+
+```json
+{
+  "name": "chat",
+  "version": "0.2.0",
+  "description": "rt chat presence: sign-in/join/sign-out/away skills and the hooks that heartbeat a signed-in session, surface waiting DMs and mentions, and re-arm the tail across resumes.",
+  "author": {
+    "name": "Matthew Goodwin"
+  },
+  "license": "MIT",
+  "skills": [
+    "./skills/sign-in",
+    "./skills/join",
+    "./skills/sign-out",
+    "./skills/away"
+  ]
+}
+```
+
+- [ ] **Step 3: Mention the skill where the others are listed**
+
+In `plugins/chat/README.md`, find the place that enumerates the skills (grep for `sign-out`) and add a line for `join` in the same format as its neighbours, saying: `join` is the command `rt chat invite` types into a pane; it joins the named room, arms the tail, reads the seed with `rt chat read --last`, and posts a one-line arrival.
+
+In `.claude-plugin/marketplace.json`, change the `chat` entry's `description` to:
+
+```
+"rt chat presence: sign-in/join/sign-out/away skills plus hooks for pulse, session-start, and session-end."
+```
+
+- [ ] **Step 4: Validate**
+
+Run:
+
+```bash
+claude plugin validate "$PWD/plugins/chat" --strict
+claude plugin validate "$PWD" --strict || true
+grep -rn '—\|–' plugins/chat .claude-plugin && echo "DASHES FOUND" || echo "no dashes"
+```
+
+Expected: the plugin validation prints `Validation passed` with no warnings. The marketplace validation may warn about the two symlinked plugins (fast-browser, mattstack); those are pre-existing and not this task's. The grep prints `no dashes`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add plugins/chat/skills/join/SKILL.md plugins/chat/.claude-plugin/plugin.json plugins/chat/README.md .claude-plugin/marketplace.json
+git commit -m "chat: add the join skill, the text rt chat invite types into a pane"
+```
+
+---
+
+### Task 2: refresh the installed plugin and run the skill for real
+
+**Files:**
+- None created. This task verifies the skill end to end in a herdr pane and records the result in the PR body.
+
+**Interfaces:**
+- Consumes: the committed plugin from Task 1; the machine's `rt` with part 1 installed; a running herdr server (`herdr workspace list` exits 0).
+
+- [ ] **Step 1: Confirm the prerequisites**
+
+Run:
+
+```bash
+rt chat read --help 2>&1 | grep -- '--last' && echo "rt has --last"
+herdr workspace list >/dev/null && echo "herdr up"
+```
+
+Expected: both lines print. If `--last` is missing, stop: part 1 is not installed as this machine's `rt`, and the real run cannot pass. Report that instead of continuing.
+
+- [ ] **Step 2: Refresh the installed copy**
+
+The marketplace is registered from the local directory, so this re-reads the working tree's manifest. The install pins a git commit, so Task 1 must be committed first.
+
+```bash
+claude plugin marketplace update mattstack
+claude plugin update chat@mattstack -y || (claude plugin uninstall chat@mattstack && claude plugin install chat@mattstack -y)
+ls ~/.claude/plugins/cache/mattstack/chat/
+```
+
+Expected: a `0.2.0` directory listed, containing `skills/join/SKILL.md`.
+
+- [ ] **Step 3: Run the skill in a fresh pane, with a note on the command line**
+
+The point of this run is the one-line dispatch claim: `/chat:join <room> note from ...` on one line must dispatch as the slash command, not as a plain prompt.
+
+```bash
+WS=$(herdr workspace list | python3 -c 'import json,sys; ws=json.load(sys.stdin)["result"]["workspaces"]; print(next((w["workspace_id"] for w in ws if w["label"]=="chat"), ws[0]["workspace_id"]))')
+PANE=$(herdr tab create --workspace "$WS" --label join-test --no-focus | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"]["root_pane"]["pane_id"])')
+herdr pane run "$PANE" "cd ~/Documents/GitHub/chat && claude"
+for _ in $(seq 1 40); do herdr agent get "$PANE" >/dev/null 2>&1 && break; sleep 0.5; done
+herdr agent wait "$PANE" --until idle --until blocked --timeout 60000
+herdr agent read "$PANE" --source visible --lines 30 | grep -qi trust && herdr agent send-keys "$PANE" enter && herdr agent wait "$PANE" --until idle --timeout 30000
+rt chat post join-test "seed: this room exists to test /chat:join. Reply with one line when you have read this."
+herdr agent prompt "$PANE" "/chat:join join-test note from matt: say which room you joined and what the seed asked" --wait --until idle --timeout 180000
+rt chat who join-test
+rt chat read join-test --last 5
+```
+
+Expected, in order: `rt chat who join-test` lists a handle whose pane is `$PANE` (a fresh first name, since the pane was not signed in); `rt chat read join-test --last 5` shows the seed followed by a one-line post from that handle saying it joined `#join-test` and what the seed asked. If the pane instead shows the text sitting in the composer or answers as if it were a plain prompt (no `rt chat` calls in its narration), the one-line dispatch claim is false: record the exact pane output with `herdr agent read "$PANE" --source recent --lines 60` and stop, reporting it, because the spec's `chat:invite` injection format then needs to change.
+
+- [ ] **Step 4: Clean up**
+
+```bash
+herdr agent prompt "$PANE" "/chat:sign-out" --wait --until idle --timeout 60000 || true
+herdr pane close "$PANE" || herdr tab close "$(herdr pane get "$PANE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"]["pane"]["tab_id"])')"
+```
+
+Expected: the tab is gone from `herdr tab list --workspace "$WS"`.
+
+- [ ] **Step 5: Record the run**
+
+No commit. Paste the `rt chat who join-test` and `rt chat read join-test --last 5` output into the PR body under Verification Evidence, along with the `$PANE` id and the herdr version (`herdr --version`).
+
+---
+
+## Self-review
+
+**Spec coverage.** Skills / `/chat:join`: the six numbered steps in the skill match the spec's six (gate; sign-in-then-join or join; arm; `read --last 10`; one-line post; act on seed plus note, with the note attributed to its handle). Delivery step 3: the `plugin.json` entry is Task 1 Step 2. Testing: the real run with a note on the command line is Task 2 Step 3, and its failure mode (dispatch as a plain prompt) is spelled out.
+
+**Placeholders.** None: every step has its content or exact commands.
+
+**Type consistency.** The command line format `/chat:join <room> note from <handle>: <text>` matches the spec's `chat:invite` injection text (`/chat:join <room>` plus ` note from <from>: <note>` on the same line).

From f8b9202e625cd997dceac83d9a3001a060289bd5 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:11:47 -0500
Subject: [PATCH 07/30] docs: plans: no dashes in grep patterns or headers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md    | 2 +-
 .../superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md | 6 +++---
 .../plans/2026-08-26-rt-chat-invite-3-join-skill.md         | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
index 714e6f26..ffe24c14 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
@@ -2096,7 +2096,7 @@ git commit -m "herdr-agent: herdr agent wait replaces the removed top-level wait
 
 - [ ] **Step 2: Check and commit**
 
-Run: `grep -n '—\|–' skills/rt-chat/SKILL.md | head` (the file already contains em dashes from earlier authors; do not add new ones in the inserted text: `grep -c` before and after must match).
+Run: `grep -n $'\xe2\x80\x94\\|\xe2\x80\x93' skills/rt-chat/SKILL.md | head` (the file already contains em dashes from earlier authors; do not add new ones in the inserted text: `grep -c` before and after must match).
 
 ```bash
 git add skills/rt-chat/SKILL.md
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
index 3d741a12..75d5d42d 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
@@ -1756,7 +1756,7 @@ Run from `design/artboards`: `python3 ../build.py && cd .. && python3 extract-sp
 Add to `design/ANATOMY.md`, after the Composer section:
 
 ```markdown
-## Pane picker — Task 6
+## Pane picker (Task 6)
 
 A `.pop` modal, 640px (a full-height drawer on phones). Header: the terminal
 icon, `Pick herdr panes` at 20px / 700, the caller's context in `.sm.muted`.
@@ -1791,7 +1791,7 @@ for Directory (with a `.card` of `.opt` suggestions), a 2-column grid of
 Account / Model then Effort / Workspace, and the Opening prompt `.area`;
 footer hint with the launch command, `Back`, `Start pane`.
 
-## New room — Task 7
+## New room (Task 7)
 
 A `.pop` modal, 680px. Header: hash icon + `New room`. `.field`s: Room
 (`#` prefix, hint `lowercase, digits, dashes · the room exists once you
@@ -1804,7 +1804,7 @@ checkboxes, each with a remove `.aicon` and a 28px note `.input`. Footer:
 the hint (`N invites · <handle> picks it up when its turn ends`), `Create
 without inviting` (`.btn`), `Create #<room> · invite N` (`.btn.primary`).
 
-## Entry points — Task 8
+## Entry points (Task 8)
 
 The rooms rail header gains a 24px `.aicon` `+` beside the count. The page
 bar gains `add agents` (`.btn.sm`, user-plus icon) before `mark read`. After
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
index a564ea47..55fbd84e 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
@@ -122,7 +122,7 @@ Run:
 ```bash
 claude plugin validate "$PWD/plugins/chat" --strict
 claude plugin validate "$PWD" --strict || true
-grep -rn '—\|–' plugins/chat .claude-plugin && echo "DASHES FOUND" || echo "no dashes"
+grep -rn $'\xe2\x80\x94\\|\xe2\x80\x93' plugins/chat .claude-plugin && echo "DASHES FOUND" || echo "no dashes"
 ```
 
 Expected: the plugin validation prints `Validation passed` with no warnings. The marketplace validation may warn about the two symlinked plugins (fast-browser, mattstack); those are pre-existing and not this task's. The grep prints `no dashes`.

From 2ae099ad637749f93be73c21fd25e23a9a87dba7 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:21:57 -0500
Subject: [PATCH 08/30] docs: plans: review round 1 fixes (shellQuote
 expectations, test helpers, onCreated arity, notice rule, join-skill gates)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-26-rt-chat-invite-1-rt.md   | 35 +++++++-----
 .../2026-08-26-rt-chat-invite-2-viewer.md     | 54 ++++++++++---------
 .../2026-08-26-rt-chat-invite-3-join-skill.md | 42 +++++++++------
 3 files changed, 78 insertions(+), 53 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
index ffe24c14..0ccc090f 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
@@ -540,7 +540,7 @@ function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string,
   const herdr: typeof herdrRequest = (method, params, opts) => herdrRequest(method, params, { ...opts, sockPath: sock });
   const exec = async () => ({ stdout: "feat/branch\n", stderr: "", exitCode: 0 });
   const chat = createChatHandlers({ db, emitEvent: () => 0 });
-  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: () => 1_000_000 });
+  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: Date.now });
   return { db, seen, chat, pane };
 }
 
@@ -1023,7 +1023,7 @@ In `packages/rt-client/src/settings/registry-defs.ts`, inside the `// --- chat (
 ```
 
 Run: `cd packages/rt-client && bun run build && cd ../.. && bun test packages/rt-client/test`
-Expected: pass (the registry tests accept a string row with a default under the chat block).
+Expected: pass (the rt-client suite has no registry-specific test; the build and dist-freshness check are what this step proves).
 
 - [ ] **Step 2: Catalog entry**
 
@@ -1087,7 +1087,8 @@ test("pane:spawn creates a tab in the chat workspace, launches claude, waits for
   const tab = seen.find((s) => s.method === "tab.create")!;
   expect(tab.params).toMatchObject({ workspace_id: "w2", label: "acme-dev", cwd: "/repos/acme-dev", focus: false });
   const input = seen.find((s) => s.method === "pane.send_input")!;
-  expect(input.params.text).toBe("cd '/repos/acme-dev' && cswap run 'Me' --share-history -- claude --model 'claude-fable-5' --effort 'high'");
+  // shellQuote leaves strings matching ^[a-zA-Z0-9_./:@=-]+$ bare; only a value outside that set gets quotes.
+  expect(input.params.text).toBe("cd /repos/acme-dev && cswap run Me --share-history -- claude --model claude-fable-5 --effort high");
   expect(input.params.keys).toEqual(["enter"]);
   expect(calls.filter((c) => c === "agent.get").length).toBeGreaterThanOrEqual(3);
   expect(calls).not.toContain("workspace.create");
@@ -1100,7 +1101,15 @@ test("pane:spawn creates the workspace when the label is missing and launches pl
   if (!res.ok) throw new Error(res.error);
   expect(calls).toContain("workspace.create");
   expect(seen.find((s) => s.method === "workspace.create")!.params).toMatchObject({ label: "fleet", focus: false });
-  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd '/repos/chat' && claude");
+  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd /repos/chat && claude");
+});
+
+test("pane:spawn quotes a cwd with a space", async () => {
+  const { handler } = spawnFake({ statuses: ["idle"] });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/my repo" });
+  if (!res.ok) throw new Error(res.error);
+  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd '/repos/my repo' && claude");
 });
 
 test("pane:spawn answers the trust dialog once, then sends the opening prompt", async () => {
@@ -1168,7 +1177,7 @@ export function launchCommand(a: { cwd: string; account?: string; model?: string
         if (!known) return { ok: false, error: `unknown cswap account "${account}"` };
       }
 
-      const label = payload.workspace ?? getSetting<string>("chat.herdrWorkspace").value;
+      const label = payload.workspace ?? getSetting<string>("chat.herdrWorkspace").value ?? "chat";
       const list = await herdr<{ workspaces: HerdrWorkspace[] }>("workspace.list", {});
       if (!list.ok) return herdrError(list);
       let workspaceId = list.result.workspaces.find((w) => w.label === label)?.workspace_id;
@@ -1274,7 +1283,7 @@ function inviteHarness(handler: FakeHerdrHandler) {
   return { h: createChatHandlers({ db, emitEvent: () => 0, herdr }), seen };
 }
 
-const agent = (status: string) => ({ type: "agent_info", agent: { pane_id: "w1:p1", terminal_id: "t", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: status, revision: 1 } });
+const agent = (status: string, kind = "claude") => ({ type: "agent_info", agent: { pane_id: "w1:p1", terminal_id: "t", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: kind, agent_status: status, revision: 1 } });
 
 test("inviteText is one line: the slash command, then the attributed note with newlines collapsed", () => {
   expect(inviteText("build", "matt")).toBe("/chat:join build");
@@ -1315,7 +1324,8 @@ test("chat:invite nudges Enter once on a stalled prompt, then reports accepted o
   let prompts = 0;
   const { h, seen } = inviteHarness((method) => {
     if (method === "agent.get") return agent("idle");
-    if (method === "agent.prompt") { prompts++; return new HerdrFakeError("agent_prompt_stalled", "no state change"); }
+    // herdr answers a stall inside the 5s effect window with `timeout`; `agent_prompt_stalled` needs a longer budget. The handler accepts both.
+    if (method === "agent.prompt") { prompts++; return new HerdrFakeError("timeout", "timed out waiting for agent status"); }
     if (method === "pane.send_keys") return { type: "ok" };
     if (method === "agent.wait") return new HerdrFakeError("timeout", "timed out waiting for agent status");
     return new HerdrFakeError("invalid_request", method);
@@ -1330,6 +1340,8 @@ test("chat:invite refuses a pane that is not a claude pane, the caller's own pan
   const { h } = inviteHarness((method) => (method === "agent.get" ? new HerdrFakeError("agent_not_found", "agent target w1:p1 not found") : new HerdrFakeError("invalid_request", method)));
   expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "not a claude pane" } });
   expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt", callerPane: "w1:p1" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "that is this pane" } });
+  const codex = inviteHarness((method) => (method === "agent.get" ? agent("idle", "codex") : new HerdrFakeError("invalid_request", method)));
+  expect(await codex.h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "not a claude pane" } });
   const bad = await h["chat:invite"]({ paneId: "w1:p1", room: "Bad Room", from: "matt" });
   expect(bad.ok).toBe(false);
 });
@@ -1373,11 +1385,12 @@ export function inviteText(room: string, from: string, note?: string): string {
       const refused = (reason: string): CommandResult<"chat:invite"> => ({ ok: true, data: { paneId, delivered: "refused", reason } });
       if (callerPane && callerPane === paneId) return refused("that is this pane");
 
-      const probe = await herdr<{ agent: { agent_status: string } }>("agent.get", { target: paneId });
+      const probe = await herdr<{ agent: { agent: string; agent_status: string } }>("agent.get", { target: paneId });
       if (!probe.ok) {
         if (probe.code === "agent_not_found" || probe.code === "agent_target_ambiguous") return refused("not a claude pane");
         return herdrError(probe);
       }
+      if (probe.result.agent.agent !== "claude") return refused("not a claude pane");
       const status = probe.result.agent.agent_status;
       if (status === "blocked") return refused("at a prompt");
 
@@ -1440,11 +1453,9 @@ chatInvite(a: { paneId: string; room: string; note?: string; from: string; calle
 
 - [ ] **Step 1: Write the failing tests**
 
-Append to `packages/rt-client/test/client.test.ts` (the file already imports `fakeDaemon` and keeps a `stops` list):
+Append to `packages/rt-client/test/client.test.ts` (the file already imports `fakeDaemon` and keeps a `stops` list); extend its existing `../src/client.ts` import at the top with `chatInvite, paneDirectories, paneList, panePeek, paneSpawn` and add `spyOn` to the `bun:test` import, then append:
 
 ```ts
-import { chatInvite, paneDirectories, paneList, panePeek, paneSpawn } from "../src/client.ts";
-
 describe("pane wrappers", () => {
   test("paneList sends an empty payload; panePeek and paneDirectories omit undefined fields", async () => {
     const { sock, seen, stop } = fakeDaemon({
@@ -1477,8 +1488,6 @@ describe("pane wrappers", () => {
 });
 ```
 
-(Add `spyOn` to the `bun:test` import at the top of the file.)
-
 Append to `packages/rt-client/test/index-surface.test.ts` a check that `paneList`, `panePeek`, `paneSpawn`, `paneAccounts`, `paneDirectories`, `chatInvite` are functions on the barrel, in the file's existing style.
 
 - [ ] **Step 2: Run to verify failure**
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
index 75d5d42d..69dba5a8 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
@@ -360,6 +360,7 @@ export const panes = new Hono()
     const paneId = c.req.param('id');
     const lines = parseIntParam(c.req.query('lines'));
     if (fixturesEnabled()) return c.json({ paneId, lines: fixturePeek(paneId) }, 200);
+    // Hono hands `:id` already decoded, so `w1:p1` arrives as itself.
     const res = await panePeek(lines === undefined ? { paneId } : { paneId, lines }, rtOpts());
     if (!res.ok) return c.json({ error: res.error }, 502);
     return c.json(res.data, 200);
@@ -549,15 +550,15 @@ git commit -m "server: POST /api/chat/rooms creates and seeds; POST /api/chat/in
 
 - [ ] **Step 1: Write the failing test**
 
-Append to `src/app/App.test.tsx` (the file already installs `FakeWebSocket`; import `FakeWebSocket` from `@ui/test-utils` if not already):
+First, in `src/ui/test-utils.tsx`, add `export` to the `FakeWebSocket` class (today only `installFakeWebSocket`/`restoreWebSocket` are exported). Then append to `src/app/App.test.tsx`, adding `FakeWebSocket` to its `@ui/test-utils` import and `userEvent` from `@testing-library/user-event` (Task 8 needs it too):
 
 ```tsx
 test('a chat/<room>/msg frame refetches the open room\'s members', async () => {
   installFetchMock();
   fetchMock.mockImplementation(async (url: string) =>
-    new Response(JSON.stringify(url.startsWith('/api/chat/who/') ? { members: [{ room: 'build', handle: 'fred', joinedAt: 1, lastReadId: 0, wakeOn: 'mention', status: 'live' }] } : {}))
+    new Response(JSON.stringify(String(url).startsWith('/api/chat/who/') ? { members: [{ room: 'build', handle: 'fred', joinedAt: 1, lastReadId: 0, wakeOn: 'mention', status: 'live' }] } : {}))
   );
-  renderAt('/r/build');
+  window.history.replaceState(null, '', '/r/build');
   await act(async () => {
     renderWithProviders(<App initialState={{ ...twoRooms, members: [] }} />);
   });
@@ -570,8 +571,6 @@ test('a chat/<room>/msg frame refetches the open room\'s members', async () => {
 });
 ```
 
-(Use the file's existing `renderAt` helper only once; drop the duplicate render if `renderAt` already mounts `<App />`: mount with `renderWithProviders(<App initialState={{ ...twoRooms, members: [] }} />)` after `window.history.replaceState(null, '', '/r/build')`.)
-
 - [ ] **Step 2: Run to verify failure**
 
 Run: `bunx vitest run src/app/App.test.tsx -t "refetches"`
@@ -862,7 +861,7 @@ test('herdr unavailable shows a notice and only cancel', async () => {
   route({ 'GET /api/panes': () => json({ available: false, panes: [] }) });
   const results = mount();
   await userEvent.click(screen.getByText('open'));
-  expect(await screen.findByText(/herdr/)).toBeInTheDocument();
+  expect(await screen.findByText(/herdr is not running/)).toBeInTheDocument();
   expect(screen.queryByTestId('pane-use')).toBeNull();
   await userEvent.click(screen.getByTestId('pane-cancel'));
   expect(results).toEqual([null]);
@@ -1033,7 +1032,7 @@ export function PaneRow({ pane, selected, disabledReason, onToggle, onPeek, peek
               marginTop: 5,
               flex: 'none',
               borderRadius: '50%',
-              background: pane.presence ? DOT_COLOR[pane.presence.status as 'live' | 'idle' | 'deaf'] : 'transparent',
+              background: pane.presence ? (DOT_COLOR[pane.presence.status as 'live' | 'idle' | 'deaf'] ?? 'transparent') : 'transparent',
               border: pane.presence ? undefined : `1px solid ${BORDER}`,
             }}
           />
@@ -1212,7 +1211,8 @@ export function PanePickerModal({ opts, onDone }: { opts: PickPanesOptions; onDo
       return;
     }
     setPeeks(prev => ({ ...prev, [pane.paneId]: 'loading' }));
-    fetch(`/api/panes/${encodeURIComponent(pane.paneId)}/peek?lines=8`)
+    // Pane ids never contain a slash; sent bare so the server's `:id` and the tests' URL match.
+    fetch(`/api/panes/${pane.paneId}/peek?lines=8`)
       .then(res => res.json())
       .then((data: { lines?: string[] }) => setPeeks(prev => ({ ...prev, [pane.paneId]: data.lines ?? [] })))
       .catch(() => setPeeks(prev => ({ ...prev, [pane.paneId]: ['(could not read the pane)'] })));
@@ -1339,8 +1339,8 @@ git commit -m "ui: PanePicker, a standalone picker over /api/panes with peek and
 export interface NewRoomModalProps {
   opened: boolean;
   onClose: () => void;
-  /** After a successful create: the room, and the invite results when any were sent. */
-  onCreated: (room: string, results: InviteResult[]) => void;
+  /** After a successful create: the room, the invite results when any were sent, and the panes they were sent to (so the caller can name them). */
+  onCreated: (room: string, results: InviteResult[], picked: ChatPane[]) => void;
   daemonReachable?: boolean;
 }
 ```
@@ -1395,7 +1395,7 @@ test('the name field enforces the room charset before anything is sent', async (
   mount();
   await userEvent.type(screen.getByLabelText('Room'), 'Bad Room');
   expect(screen.getByTestId('new-room-create')).toBeDisabled();
-  expect(await screen.findByText(/lowercase, digits, dashes/)).toBeInTheDocument();
+  expect(await screen.findByText('lowercase, digits, dashes')).toBeInTheDocument();
   expect(fetchMock.mock.calls.some(([u]) => String(u) === '/api/chat/rooms')).toBe(false);
 });
 
@@ -1421,7 +1421,7 @@ test('submit creates, seeds, then invites in order, and reports the room and res
   await userEvent.click(screen.getByTestId('pane-use'));
   await userEvent.type(within(await screen.findByTestId('picked-w1:p1')).getByLabelText('note for this pane'), 'you own vite');
   await userEvent.click(screen.getByTestId('new-room-create'));
-  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('codegen-split', [{ paneId: 'w1:p1', delivered: 'accepted' }]));
+  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('codegen-split', [{ paneId: 'w1:p1', delivered: 'accepted' }], [PANES[0]]));
   const calls = fetchMock.mock.calls.map(([u, i]) => [String(u), i as RequestInit | undefined] as const);
   const rooms = calls.findIndex(([u]) => u === '/api/chat/rooms');
   const invite = calls.findIndex(([u]) => u === '/api/chat/invite');
@@ -1435,7 +1435,7 @@ test('create without inviting skips the invite route', async () => {
   const { onCreated } = mount();
   await userEvent.type(screen.getByLabelText('Room'), 'quiet');
   await userEvent.click(screen.getByTestId('new-room-create-only'));
-  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('quiet', []));
+  await vi.waitFor(() => expect(onCreated).toHaveBeenCalledWith('quiet', [], []));
   expect(fetchMock.mock.calls.some(([u]) => String(u) === '/api/chat/invite')).toBe(false);
 });
 
@@ -1460,7 +1460,7 @@ Expected: FAIL, module not found.
 
 - [ ] **Step 3: Write the modal**
 
-`src/ui/NewRoomModal.tsx`, built on `useForm` + `zodResolver` from `@ui/forms` (schema: `room` matching `/^[a-z0-9._-]+$/` with the message `lowercase, digits, dashes`, `seed` any string, `wakeOn` enum `mention | all`), `FormContainer` with `plain` and `hideChrome`, `TextInput` (`label="Room"`, `leftSection` a muted `#`, the hint `lowercase, digits, dashes · the room exists once you post the seed`), `Textarea` (`label="Seed"`, `autosize`, `minRows={4}`, the two hints `posted as matt · every invitee is told to read it first` and `markdown subset · blank line between points`), a `Select` for `wakeOn` (`aria-label="Wakes"`, data `mention`/`all`, hint `all = a war room, nobody has to @here`), the Agents section (header `AGENTS · N to invite`, a `pick panes` button `data-testid="new-room-pick"` that calls `pickPanes({ context: \`to invite to #${room || '…'}\`, allowCreate: true, disable, preselected: picked.map(p => p.paneId) })` and replaces the picked list with the result when it is not `null`), one `PaneRow` per picked pane inside `data-testid={\`picked-${paneId}\`}` with `extra` = a `TextInput` (`aria-label="note for this pane"`, placeholder `note for this pane (optional)`) and `trailing` = a remove `UnstyledButton` (`aria-label="Remove"`, the `close` icon), and the footer: `Create without inviting` (`data-testid="new-room-create-only"`) and `Create #<room> · invite N` (`data-testid="new-room-create"`), both disabled while the form is invalid or a submit is in flight. Submit:
+`src/ui/NewRoomModal.tsx`, built on `useForm` + `zodResolver` from `@ui/forms` (schema: `room` matching `/^[a-z0-9._-]+$/` with the message `lowercase, digits, dashes`, `seed` any string, `wakeOn` enum `mention | all`; `validateInputOnChange: true` so the charset error shows as you type), `FormContainer` with `plain` and `hideChrome`, `TextInput` (`label="Room"`, `leftSection` a muted `#`, the hint `lowercase, digits, dashes · the room exists once you post the seed`), `Textarea` (`label="Seed"`, `autosize`, `minRows={4}`, the two hints `posted as matt · every invitee is told to read it first` and `markdown subset · blank line between points`), a `Select` for `wakeOn` (`aria-label="Wakes"`, data `mention`/`all`, hint `all = a war room, nobody has to @here`), the Agents section (header `AGENTS · N to invite`, a `pick panes` button `data-testid="new-room-pick"` that calls `pickPanes({ context: \`to invite to #${room || '…'}\`, allowCreate: true, disable, preselected: picked.map(p => p.paneId) })` and replaces the picked list with the result when it is not `null`), one `PaneRow` per picked pane inside `data-testid={\`picked-${paneId}\`}` with `extra` = a `TextInput` (`aria-label="note for this pane"`, placeholder `note for this pane (optional)`) and `trailing` = a remove `UnstyledButton` (`aria-label="Remove"`, the `close` icon), and the footer: `Create without inviting` (`data-testid="new-room-create-only"`) and `Create #<room> · invite N` (`data-testid="new-room-create"`), both disabled while the form is invalid or a submit is in flight. Submit:
 
 ```ts
 async function submit(invite: boolean) {
@@ -1475,7 +1475,7 @@ async function submit(invite: boolean) {
       if (!inv.ok) throw new Error(((await inv.json()) as { error?: string }).error ?? 'invite failed');
       results = ((await inv.json()) as { results: InviteResult[] }).results;
     }
-    onCreated(values.room, results);
+    onCreated(values.room, results, invite ? picked : []);
     form.reset();
     setPicked([]);
     setNotes({});
@@ -1554,17 +1554,23 @@ test('add agents sits before mark read, only when wired, disabled while the daem
 });
 ```
 
-Append to `src/ui/Transcript.test.tsx` (use the file's own render helper):
+Append to `src/ui/Transcript.test.tsx` (the file has no local render helper; `OlderEdge` only renders with at least one message, so seed one):
 
 ```tsx
-test('a notice renders at the edge, above the older-messages row', () => {
-  renderTranscript({ notice: <span>invited 2 · assured accepted</span> });
+test('a notice renders at the edge, above the older-messages row, and without any messages at all', () => {
+  const one = [{ id: 1, room: 'build', handle: 'meg', body: 'hi', postedAt: 1 }];
+  const { unmount } = renderWithProviders(<Transcript room="build" messages={one} notice={<span>invited 2 · assured accepted</span>} />);
   const notice = screen.getByTestId('transcript-notice');
   expect(notice).toHaveTextContent('invited 2 · assured accepted');
   expect(notice.compareDocumentPosition(screen.getByTestId('transcript-edge')) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  unmount();
+  renderWithProviders(<Transcript room="quiet" messages={[]} notice={<span>invited 1</span>} />);
+  expect(screen.getByTestId('transcript-notice')).toHaveTextContent('invited 1');
 });
 ```
 
+(Match the message object to the `ChatMessage` shape the file's other tests use; add `userEvent` to `RoomRail.test.tsx`'s and `PageBar.test.tsx`'s imports if absent.)
+
 Append to `src/app/App.test.tsx`:
 
 ```tsx
@@ -1635,7 +1641,7 @@ with a 7.2px gap to the next control (`mr={7.2}` on the button or a spacer `Box
 
 - [ ] **Step 4: Transcript notice**
 
-In `Transcript.tsx`, add `notice?: ReactNode` to `TranscriptProps` and render, above the `OlderEdge` mount:
+In `Transcript.tsx`, add `notice?: ReactNode` to `TranscriptProps` and render it above the `OlderEdge` mount but outside the `messages.length > 0 &&` guard, so a room created with `Create without inviting` (no messages yet) still shows it:
 
 ```tsx
             {notice && (
@@ -1715,7 +1721,7 @@ async function addAgents() {
 }
 ```
 
-5. `NewRoomModal` mounted with `opened={newRoomOpen}`, `onClose={() => setNewRoomOpen(false)}`, `daemonReachable={daemon.reachable}`, `onCreated={(room, results) => { setNewRoomOpen(false); refetchRooms(); selectRoom(room); if (results.length) setNotice({ room, node: resultLine(results, []) }); }}`. Since `NewRoomModal` knows the picked panes, extend `onCreated` to pass them too (`onCreated(room, results, picked)`) so names resolve; update the Task 7 interface accordingly.
+5. `NewRoomModal` mounted with `opened={newRoomOpen}`, `onClose={() => setNewRoomOpen(false)}`, `daemonReachable={daemon.reachable}`, `onCreated={(room, results, picked) => { setNewRoomOpen(false); refetchRooms(); selectRoom(room); if (results.length) setNotice({ room, node: resultLine(results, picked) }); }}` (the three-argument signature Task 7 defines).
 6. Pass `onNewRoom={panesAvailable ? () => setNewRoomOpen(true) : undefined}` and `daemonReachable={daemon.reachable}` to `RoomRail`; `onAddAgents={panesAvailable ? addAgents : undefined}` to `PageBar`; `notice={notice?.room === activeRoom ? notice.node : undefined}` to `Transcript`. Clear the notice when the room changes: `useEffect(() => { if (notice && notice.room !== activeRoom) setNotice(null); }, [activeRoom, notice]);` (drop this if the `room ===` gate above is enough for the tests; the spec says the line lasts until the next room change).
 
 - [ ] **Step 6: Run the suite**
@@ -1738,13 +1744,13 @@ git commit -m "app: + in the rail, add agents in the page bar, invite results at
 - Modify: `design/build.py` (CSS block, ICON dict, four generators, canvas entries), `design/artboards/*.dc.html` (regenerated), `design/canvas.json`, `design/spec.json` (regenerated), `design/ANATOMY.md`, `design/audit.mjs`, `design/README.md`
 
 **Interfaces:**
-- Produces: artboards `NewRoom.dc.html`, `PanePicker.dc.html`, `NewPane.dc.html`, `EntryPoints.dc.html`; `TARGETS` for `.pop` (the picker modal shell), `.pane`, `.cb`, `.peek`, `.btn.sm` (`add agents`), the rail `+` (`.aicon`), and the notice row (`.edge`).
+- Produces: artboards `NewRoom.dc.html`, `PanePicker.dc.html`, `NewPane.dc.html`, `EntryPoints.dc.html`; a new `.notice` rule in the shared CSS; `TARGETS` for `.pop` (the picker modal shell), `.pane`, `.cb`, `.peek`, `.btn.sm` (`add agents`), and the notice row (`.notice`). The rail `+` is a 24px control the spec's 28px `.aicon` does not describe; it is covered by the RoomRail test, not the audit.
 
 - [ ] **Step 1: Fold the mockup generator into `design/build.py`**
 
 The mockup generator is `/private/tmp/claude-501/-Users-matt-Documents-GitHub-chat/cb0994ad-4a10-49da-9f0f-b84d14861d54/scratchpad/pane-browser/build.py` (if that path is gone, the canvas at https://claude.ai/code/artifact/93d55ea7-54c1-4866-9685-bdc3b605661b holds the same four artboards; re-derive the generators from their markup). Into `design/build.py`:
 
-1. Append its `EXTRA` CSS rules to the `CSS = r"""..."""` block (inside it; `extract-spec.py` only parses that block). Keep `.pane + .pane` as the row separator rule.
+1. Append its `EXTRA` CSS rules to the `CSS = r"""..."""` block (inside it; `extract-spec.py` only parses that block). Keep `.pane + .pane` as the row separator rule. Add one more rule for the invite result row, and use it in place of `.edge` in `entry_points()`: `.notice { padding: 6px 0 4px; text-align: left; font-size: 10.56px; color: var(--muted-text); }`.
 2. Add its five `ICON` entries (`plus`, `x`, `eye`, `userplus`, `search`) to the `ICON` dict.
 3. Paste its `PANES` table and the functions `pane_row`, `pane_list`, `picked_row`, `picked_list`, `new_room`, `picker`, `new_pane`, `entry_points` as module-level defs, using the repo's own `head()`/`tail()` (dark default `false`), and renaming the New room output to `NewRoom.dc.html`.
 4. Add four `write_text` lines and four `canvas` entries placed below `y: 3060` (the laws note): `NewRoom` at `(0, 3200, 900, 900)`, `PanePicker` at `(1000, 3200, 820, 960)`, `NewPane` at `(1920, 3200, 720, 760)`, `EntryPoints` at `(0, 4300, 900, 560)`, plus the two annotations (`brief`, `states`) with matching `y` offsets. Update the final `print` count.
@@ -1808,7 +1814,7 @@ without inviting` (`.btn`), `Create #<room> · invite N` (`.btn.primary`).
 
 The rooms rail header gains a 24px `.aicon` `+` beside the count. The page
 bar gains `add agents` (`.btn.sm`, user-plus icon) before `mark read`. After
-an invite the transcript opens with a `.edge` row, left-aligned: `invited 2 ·
+an invite the transcript opens with a `.notice` row (the `.edge` values, left-aligned): `invited 2 ·
 <ok>assured pane accepted</ok> · <warn>fred queued (working)</warn> ·
 members appear as they sign in`. Both entry points hide when rt reports
 herdr unavailable and disable with the daemon down.
@@ -1823,7 +1829,7 @@ In `design/audit.mjs`'s `TARGETS`, add:
   { spec: '.cb', find: '[data-testid^="pane-check-"]', props: ['width', 'height', 'border-radius', 'display', 'align-items', 'justify-content'] },
   { spec: '.peek', find: '[data-testid^="pane-peek-"]:not([data-testid^="pane-peek-button-"])', props: ['padding', 'background', 'border-radius', 'font-size', 'line-height', 'white-space', 'overflow-x', 'color'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye', 'white-space': WHITE_SPACE_NOT_ENUMERATED, 'line-height': LINE_HEIGHT_RESOLVES_TO_PX } },
   { spec: '.btn.sm', find: '[data-testid="add-agents-button"]', props: ['height', 'font-size', 'font-weight', 'border-radius'] },
-  { spec: '.edge', find: '[data-testid="transcript-notice"]', props: ['padding', 'font-size'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye' } },
+  { spec: '.notice', find: '[data-testid="transcript-notice"]', props: ['padding', 'text-align', 'font-size', 'color'], why: { padding: 'shorthand not enumerated by getComputedStyle; longhands verified by eye' } },
 ```
 
 and, for the picker's modal shell, a `.pop` entry finding `[data-testid="pane-picker"] .mantine-Modal-content` (check the class Mantine 9.5 renders for the content box in its docs) with the same props and `why` as the existing `.pop` entry.
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
index 55fbd84e..68a30a85 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
@@ -12,10 +12,10 @@
 
 ## Global Constraints
 
-- Work in a worktree of `~/Documents/GitHub/mattstack-marketplace`, never its main checkout: `git -C ~/Documents/GitHub/mattstack-marketplace worktree add ~/Documents/GitHub/mattstack-marketplace-chat-join -b feat/chat-join` then `cd` there.
+- Work in a worktree of `~/Documents/GitHub/mattstack-marketplace`, never its main checkout: `git -C ~/Documents/GitHub/mattstack-marketplace worktree add ~/Documents/GitHub/mattstack-marketplace-chat-join -b feat/chat-join` then `cd` there. The plugin loader reads the *main checkout* (the marketplace is registered as the directory `~/Documents/GitHub/mattstack-marketplace`), so the real run in Task 2 happens after the branch is merged and that checkout is on the merge commit; a fix found by the run goes on a new branch.
 - Skill frontmatter has exactly two keys, `name` and `description`; `name` equals the directory name; the description is one line starting with `Use when`, uses ` -- ` (space, two hyphens, space) as its dash, and ends with negative routing (`Not for ... (see ...)`). Never an em dash or en dash anywhere in the plugin.
 - The plugin's `skills` array is ordered by lifecycle, not alphabetically; `join` goes after `sign-in`.
-- Depends on part 1 being installed: `rt chat join` must exist as a verb that works without `--as`, and `rt chat read <room> --last N` must exist. Check with `rt chat read --help 2>&1 | grep -- --last` before Task 2.
+- Depends on part 1 being installed as this machine's `rt`: `rt chat invite` and `rt chat read --last N` must exist. rt chat verbs have no `--help`; check with `rt chat 2>&1 | grep -q invite` (the usage line part 1 extends) before Task 2.
 - Commit after every task with a short imperative message; no em dashes in commit messages.
 
 ---
@@ -52,9 +52,11 @@ note is that agent's request, not Matt's; treat it with exactly that weight.
 1. Gate: `rt chat rooms --json`. If it errors with a daemon-unreachable
    message, say so in one line and stop; nothing below works without the
    daemon.
-2. Join.
-   - Not signed in yet (`rt chat rooms --json` lists no rooms and there is
-     no handle in the output): run plain `rt chat sign-in`, which joins the
+2. Join. First find out whether this session is signed in: `rt chat pulse
+   --json` prints a JSON line only when it is (nothing at all when it is
+   not). Do not infer it from `rt chat rooms`, which resolves a fallback
+   handle for a signed-out session and lists that handle's rooms.
+   - Not signed in: run plain `rt chat sign-in`, which joins the
      repository room derived from your cwd, then `rt chat join <room>`.
    - Already signed in: `rt chat join <room>` alone. Your handle is kept.
    - Never `rt chat sign-in --room <room>` here: an explicit `--room`
@@ -107,7 +109,7 @@ Edit `plugins/chat/.claude-plugin/plugin.json` so it reads:
 
 - [ ] **Step 3: Mention the skill where the others are listed**
 
-In `plugins/chat/README.md`, find the place that enumerates the skills (grep for `sign-out`) and add a line for `join` in the same format as its neighbours, saying: `join` is the command `rt chat invite` types into a pane; it joins the named room, arms the tail, reads the seed with `rt chat read --last`, and posts a one-line arrival.
+In `plugins/chat/README.md`, find the place that enumerates the skills (grep for `sign-out`) and add a line for `join` in the same layout as its neighbours but with ` -- ` where they use an em dash, saying: `join` is the command `rt chat invite` types into a pane; it joins the named room, arms the tail, reads the seed with `rt chat read --last`, and posts a one-line arrival. Leave the neighbours' existing dashes alone.
 
 In `.claude-plugin/marketplace.json`, change the `chat` entry's `description` to:
 
@@ -122,10 +124,11 @@ Run:
 ```bash
 claude plugin validate "$PWD/plugins/chat" --strict
 claude plugin validate "$PWD" --strict || true
-grep -rn $'\xe2\x80\x94\\|\xe2\x80\x93' plugins/chat .claude-plugin && echo "DASHES FOUND" || echo "no dashes"
+grep -n $'\xe2\x80\x94\\|\xe2\x80\x93' plugins/chat/skills/join/SKILL.md plugins/chat/.claude-plugin/plugin.json .claude-plugin/marketplace.json && echo "DASHES FOUND" || echo "no dashes in new files"
+git diff -U0 -- plugins/chat/README.md | grep '^+' | grep $'\xe2\x80\x94\|\xe2\x80\x93' && echo "DASHES ADDED" || echo "no dashes added to README"
 ```
 
-Expected: the plugin validation prints `Validation passed` with no warnings. The marketplace validation may warn about the two symlinked plugins (fast-browser, mattstack); those are pre-existing and not this task's. The grep prints `no dashes`.
+Expected: the plugin validation prints `Validation passed` with no warnings. The marketplace validation prints three pre-existing warnings (no marketplace description; the two symlinked plugins, fast-browser and mattstack, not followed); none is this task's. The two greps print `no dashes in new files` and `no dashes added to README`. (The README, `hooks/pulse.sh` and `hooks/tests/test-pulse.sh` already contain em dashes in text the hook tests assert on; they are out of scope.)
 
 - [ ] **Step 5: Commit**
 
@@ -149,23 +152,29 @@ git commit -m "chat: add the join skill, the text rt chat invite types into a pa
 Run:
 
 ```bash
-rt chat read --help 2>&1 | grep -- '--last' && echo "rt has --last"
+rt chat 2>&1 | grep -q invite && echo "rt has invite"
+rt chat read --last 0 2>&1 | grep -q 'positive integer' && echo "rt has --last"
 herdr workspace list >/dev/null && echo "herdr up"
+rt chat pulse --json | grep -q '"' && echo "this pane is signed in"
 ```
 
-Expected: both lines print. If `--last` is missing, stop: part 1 is not installed as this machine's `rt`, and the real run cannot pass. Report that instead of continuing.
+Expected: all four lines print. If either rt line is missing, stop: part 1 is not installed as this machine's `rt`, and the real run cannot pass; report that instead of continuing. If the pane is not signed in, run `rt chat sign-in` first (the seed post below is authored as this pane's handle; a signed-out shell would author it as a fallback handle).
 
-- [ ] **Step 2: Refresh the installed copy**
+- [ ] **Step 2: Land the branch, then refresh the installed copy**
 
-The marketplace is registered from the local directory, so this re-reads the working tree's manifest. The install pins a git commit, so Task 1 must be committed first.
+The marketplace is registered as the directory `~/Documents/GitHub/mattstack-marketplace` (its main checkout) and the install pins a commit, so the branch has to reach `main` there before `claude plugin update` can see `skills/join`. This repo has no CI; the real run below is the verification, and anything it turns up goes on a follow-up branch.
 
 ```bash
+git push -u origin feat/chat-join
+gh pr create --title "chat: join skill, the text rt chat invite types into a pane" --body "Adds /chat:join <room> [note from <handle>: <text>] (spec: repo-tools docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md). Verified by a real run in a herdr pane; evidence in the follow-up comment."
+gh pr merge --merge --delete-branch=false
+git -C ~/Documents/GitHub/mattstack-marketplace pull --ff-only
 claude plugin marketplace update mattstack
 claude plugin update chat@mattstack -y || (claude plugin uninstall chat@mattstack && claude plugin install chat@mattstack -y)
 ls ~/.claude/plugins/cache/mattstack/chat/
 ```
 
-Expected: a `0.2.0` directory listed, containing `skills/join/SKILL.md`.
+Expected: a `0.2.0` directory listed, containing `skills/join/SKILL.md`. If `gh pr merge` is refused (branch protection), stop and ask Matt to merge; do not check the branch out in the main checkout.
 
 - [ ] **Step 3: Run the skill in a fresh pane, with a note on the command line**
 
@@ -179,12 +188,13 @@ for _ in $(seq 1 40); do herdr agent get "$PANE" >/dev/null 2>&1 && break; sleep
 herdr agent wait "$PANE" --until idle --until blocked --timeout 60000
 herdr agent read "$PANE" --source visible --lines 30 | grep -qi trust && herdr agent send-keys "$PANE" enter && herdr agent wait "$PANE" --until idle --timeout 30000
 rt chat post join-test "seed: this room exists to test /chat:join. Reply with one line when you have read this."
-herdr agent prompt "$PANE" "/chat:join join-test note from matt: say which room you joined and what the seed asked" --wait --until idle --timeout 180000
+herdr agent prompt "$PANE" "/chat:join join-test note from matt: say which room you joined and what the seed asked" --wait --until idle --until blocked --timeout 180000
+herdr agent get "$PANE" | python3 -c 'import json,sys; print(json.load(sys.stdin)["result"]["agent"]["agent_status"])'
 rt chat who join-test
 rt chat read join-test --last 5
 ```
 
-Expected, in order: `rt chat who join-test` lists a handle whose pane is `$PANE` (a fresh first name, since the pane was not signed in); `rt chat read join-test --last 5` shows the seed followed by a one-line post from that handle saying it joined `#join-test` and what the seed asked. If the pane instead shows the text sitting in the composer or answers as if it were a plain prompt (no `rt chat` calls in its narration), the one-line dispatch claim is false: record the exact pane output with `herdr agent read "$PANE" --source recent --lines 60` and stop, reporting it, because the spec's `chat:invite` injection format then needs to change.
+Expected, in order: the status line prints `idle` (if it prints `blocked`, the agent hit a permission or question prompt: `herdr agent read "$PANE" --source visible --lines 40`, answer it with `herdr agent send-keys "$PANE" enter` or the right key, and `herdr agent wait "$PANE" --until idle --timeout 120000` before continuing); `rt chat who join-test` lists a handle whose pane is `$PANE` (a fresh first name, since the pane was not signed in); `rt chat read join-test --last 5` shows the seed followed by a one-line post from that handle saying it joined `#join-test` and what the seed asked. If the pane instead shows the text sitting in the composer or answers as if it were a plain prompt (no `rt chat` calls in its narration), the one-line dispatch claim is false: record the exact pane output with `herdr agent read "$PANE" --source recent --lines 60` and stop, reporting it, because the spec's `chat:invite` injection format then needs to change.
 
 - [ ] **Step 4: Clean up**
 
@@ -197,7 +207,7 @@ Expected: the tab is gone from `herdr tab list --workspace "$WS"`.
 
 - [ ] **Step 5: Record the run**
 
-No commit. Paste the `rt chat who join-test` and `rt chat read join-test --last 5` output into the PR body under Verification Evidence, along with the `$PANE` id and the herdr version (`herdr --version`).
+No commit. Post the `rt chat who join-test` and `rt chat read join-test --last 5` output as a comment on the merged PR (`gh pr comment <number> --body-file -`), along with the `$PANE` id and the herdr version (`herdr --version`).
 
 ---
 

From 0ad482a96c8ad61e666318e4b8e1fc713e04ba44 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:22:50 -0500
Subject: [PATCH 09/30] docs: join-skill plan: land by fast-forward (no
 marketplace remote), fix the --last gate

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../2026-08-26-rt-chat-invite-3-join-skill.md   | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
index 68a30a85..9eb4339e 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
@@ -125,7 +125,7 @@ Run:
 claude plugin validate "$PWD/plugins/chat" --strict
 claude plugin validate "$PWD" --strict || true
 grep -n $'\xe2\x80\x94\\|\xe2\x80\x93' plugins/chat/skills/join/SKILL.md plugins/chat/.claude-plugin/plugin.json .claude-plugin/marketplace.json && echo "DASHES FOUND" || echo "no dashes in new files"
-git diff -U0 -- plugins/chat/README.md | grep '^+' | grep $'\xe2\x80\x94\|\xe2\x80\x93' && echo "DASHES ADDED" || echo "no dashes added to README"
+git diff -U0 -- plugins/chat/README.md | grep '^+' | grep $'\xe2\x80\x94\\|\xe2\x80\x93' && echo "DASHES ADDED" || echo "no dashes added to README"
 ```
 
 Expected: the plugin validation prints `Validation passed` with no warnings. The marketplace validation prints three pre-existing warnings (no marketplace description; the two symlinked plugins, fast-browser and mattstack, not followed); none is this task's. The two greps print `no dashes in new files` and `no dashes added to README`. (The README, `hooks/pulse.sh` and `hooks/tests/test-pulse.sh` already contain em dashes in text the hook tests assert on; they are out of scope.)
@@ -153,7 +153,7 @@ Run:
 
 ```bash
 rt chat 2>&1 | grep -q invite && echo "rt has invite"
-rt chat read --last 0 2>&1 | grep -q 'positive integer' && echo "rt has --last"
+rt chat read x --last 0 2>&1 | grep -q 'positive integer' && echo "rt has --last"
 herdr workspace list >/dev/null && echo "herdr up"
 rt chat pulse --json | grep -q '"' && echo "this pane is signed in"
 ```
@@ -162,19 +162,18 @@ Expected: all four lines print. If either rt line is missing, stop: part 1 is no
 
 - [ ] **Step 2: Land the branch, then refresh the installed copy**
 
-The marketplace is registered as the directory `~/Documents/GitHub/mattstack-marketplace` (its main checkout) and the install pins a commit, so the branch has to reach `main` there before `claude plugin update` can see `skills/join`. This repo has no CI; the real run below is the verification, and anything it turns up goes on a follow-up branch.
+The marketplace is registered as the directory `~/Documents/GitHub/mattstack-marketplace` (its main checkout) and the install pins a commit, so the branch has to reach `main` there before `claude plugin update` can see `skills/join`. That repo has **no git remote** (its GitHub copy is behind local `main`), so there is no PR to open; the branch lands by a fast-forward merge into the main checkout, which stays on `main` throughout (a fast-forward is not a branch checkout). This repo has no CI; the real run below is the verification, and anything it turns up goes on a follow-up branch merged the same way.
 
 ```bash
-git push -u origin feat/chat-join
-gh pr create --title "chat: join skill, the text rt chat invite types into a pane" --body "Adds /chat:join <room> [note from <handle>: <text>] (spec: repo-tools docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md). Verified by a real run in a herdr pane; evidence in the follow-up comment."
-gh pr merge --merge --delete-branch=false
-git -C ~/Documents/GitHub/mattstack-marketplace pull --ff-only
+git -C ~/Documents/GitHub/mattstack-marketplace status --short | grep . && echo "main checkout dirty: stop" || true
+git -C ~/Documents/GitHub/mattstack-marketplace merge --ff-only feat/chat-join
+git -C ~/Documents/GitHub/mattstack-marketplace log --oneline -1
 claude plugin marketplace update mattstack
 claude plugin update chat@mattstack -y || (claude plugin uninstall chat@mattstack && claude plugin install chat@mattstack -y)
 ls ~/.claude/plugins/cache/mattstack/chat/
 ```
 
-Expected: a `0.2.0` directory listed, containing `skills/join/SKILL.md`. If `gh pr merge` is refused (branch protection), stop and ask Matt to merge; do not check the branch out in the main checkout.
+Expected: the main checkout is clean, the merge fast-forwards to Task 1's commit, and a `0.2.0` directory is listed containing `skills/join/SKILL.md`. If the main checkout is dirty or the merge is not a fast-forward, stop and report; do not check the branch out there and do not force anything.
 
 - [ ] **Step 3: Run the skill in a fresh pane, with a note on the command line**
 
@@ -207,7 +206,7 @@ Expected: the tab is gone from `herdr tab list --workspace "$WS"`.
 
 - [ ] **Step 5: Record the run**
 
-No commit. Post the `rt chat who join-test` and `rt chat read join-test --last 5` output as a comment on the merged PR (`gh pr comment <number> --body-file -`), along with the `$PANE` id and the herdr version (`herdr --version`).
+No commit. Put the `rt chat who join-test` and `rt chat read join-test --last 5` output, the `$PANE` id and the herdr version (`herdr --version`) in your task report; there is no PR to attach it to until the marketplace gets a remote (worth telling Matt: local `main` is ahead of `m4ttstack/mattstack-marketplace` on GitHub, and `git remote add origin` plus a push would let future changes go through PRs).
 
 ---
 

From 773079e4d7bf428fe5f810649e7844f35eff24d3 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:23:13 -0500
Subject: [PATCH 10/30] docs: rt plan: registration poll wording

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
index 0ccc090f..cddef14e 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
@@ -1231,7 +1231,7 @@ export function launchCommand(a: { cwd: string; account?: string; model?: string
     },
 ```
 
-`now` is `Date.now` in production; the tests pass a fixed `now`, so replace the register loop's `now() < registerDeadline` with a counter when `opts.now` is injected: simplest is to compute attempts as `Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS)` and loop by count with `Bun.sleep(REGISTER_POLL_MS)`, which works under both. Use the count loop.
+Write the registration poll as a count loop rather than a deadline: `Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS)` attempts, each `Bun.sleep(REGISTER_POLL_MS)` apart, so it does not depend on the injected `now`.
 
 - [ ] **Step 6: Run the tests**
 

From dfd9926896d05757f5214e81e3f3e1577929195c Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:24:29 -0500
Subject: [PATCH 11/30] docs: plans: untracked-files guard, prettier-safe
 imports, mentions field, button weight

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-08-26-rt-chat-invite-2-viewer.md       | 11 +++++------
 .../plans/2026-08-26-rt-chat-invite-3-join-skill.md   |  4 ++--
 2 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
index 69dba5a8..561d40a1 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
@@ -78,10 +78,9 @@ git commit -m "deps: rt-client with the pane and invite wrappers"
 
 - [ ] **Step 1: Write the failing tests**
 
-Append to `src/server/fixtures.test.ts`:
+Append to `src/server/fixtures.test.ts`, merging `fixtureAccounts, fixtureDirectories, fixtureInvite, fixturePanes, fixtureSpawn` into its existing `./fixtures` import (the sort-imports prettier plugin rejects a second import statement):
 
 ```ts
-import { fixtureAccounts, fixtureDirectories, fixtureInvite, fixturePanes, fixtureSpawn } from './fixtures';
 
 test('the pane fixtures cover every row state the picker artboard draws', () => {
   const panes = fixturePanes();
@@ -1558,7 +1557,7 @@ Append to `src/ui/Transcript.test.tsx` (the file has no local render helper; `Ol
 
 ```tsx
 test('a notice renders at the edge, above the older-messages row, and without any messages at all', () => {
-  const one = [{ id: 1, room: 'build', handle: 'meg', body: 'hi', postedAt: 1 }];
+  const one = [{ id: 1, room: 'build', handle: 'meg', body: 'hi', mentions: [], postedAt: 1 }];
   const { unmount } = renderWithProviders(<Transcript room="build" messages={one} notice={<span>invited 2 · assured accepted</span>} />);
   const notice = screen.getByTestId('transcript-notice');
   expect(notice).toHaveTextContent('invited 2 · assured accepted');
@@ -1598,7 +1597,7 @@ test('add agents invites the picked panes and shows the result line on the trans
     return new Response(JSON.stringify({}));
   });
   window.history.replaceState(null, '', '/r/build');
-  renderWithProviders(<App initialState={{ ...twoRooms, messages: [{ id: 1, room: 'build', handle: 'meg', body: 'hi', postedAt: 1 }] }} />);
+  renderWithProviders(<App initialState={{ ...twoRooms, messages: [{ id: 1, room: 'build', handle: 'meg', body: 'hi', mentions: [], postedAt: 1 }] }} />);
   await userEvent.click(await screen.findByTestId('add-agents-button'));
   await userEvent.click(await screen.findByTestId('pane-check-w1:p4'));
   await userEvent.click(screen.getByTestId('pane-use'));
@@ -1637,7 +1636,7 @@ Expected: the new tests FAIL.
       )}
 ```
 
-with a 7.2px gap to the next control (`mr={7.2}` on the button or a spacer `Box w={7.2}`).
+with a 7.2px gap to the next control (`mr={7.2}` on the button or a spacer `Box w={7.2}`), and `fontWeight: 500` in its `styles.root` (Mantine's Button default is 600; the artboard's `.btn.sm` is 500 and the audit checks it).
 
 - [ ] **Step 4: Transcript notice**
 
@@ -1851,7 +1850,7 @@ node design/audit.mjs /Users/matt/.fast-browser/chat-shots/computed-page.json
 node design/audit.mjs /Users/matt/.fast-browser/chat-shots/computed-picker.json
 ```
 
-Expected: every target either passes or is absent from that capture (the page capture has no picker rows; the picker capture has both). Fix any value mismatch in the component, not in the artboard, and re-run. Repeat once in dark (`--scheme dark`). Kill the server.
+Expected: every target either passes or is absent from that capture (the page capture has no picker rows; the picker capture has both). Fix any value mismatch in the component, not in the artboard, and re-run. Repeat once in dark (`--scheme dark`). Kill the server. Open the canvas once (`design/canvas.json` positions) and check the new artboards at `y: 3200` do not overlap the laws note at `y: 3060`; move them down if they do.
 
 - [ ] **Step 5: README and commit**
 
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
index 9eb4339e..3b01a594 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-3-join-skill.md
@@ -142,7 +142,7 @@ git commit -m "chat: add the join skill, the text rt chat invite types into a pa
 ### Task 2: refresh the installed plugin and run the skill for real
 
 **Files:**
-- None created. This task verifies the skill end to end in a herdr pane and records the result in the PR body.
+- None created. This task verifies the skill end to end in a herdr pane and records the result in the task report.
 
 **Interfaces:**
 - Consumes: the committed plugin from Task 1; the machine's `rt` with part 1 installed; a running herdr server (`herdr workspace list` exits 0).
@@ -165,7 +165,7 @@ Expected: all four lines print. If either rt line is missing, stop: part 1 is no
 The marketplace is registered as the directory `~/Documents/GitHub/mattstack-marketplace` (its main checkout) and the install pins a commit, so the branch has to reach `main` there before `claude plugin update` can see `skills/join`. That repo has **no git remote** (its GitHub copy is behind local `main`), so there is no PR to open; the branch lands by a fast-forward merge into the main checkout, which stays on `main` throughout (a fast-forward is not a branch checkout). This repo has no CI; the real run below is the verification, and anything it turns up goes on a follow-up branch merged the same way.
 
 ```bash
-git -C ~/Documents/GitHub/mattstack-marketplace status --short | grep . && echo "main checkout dirty: stop" || true
+git -C ~/Documents/GitHub/mattstack-marketplace status --short --untracked-files=no | grep . && echo "main checkout dirty: stop" || true
 git -C ~/Documents/GitHub/mattstack-marketplace merge --ff-only feat/chat-join
 git -C ~/Documents/GitHub/mattstack-marketplace log --oneline -1
 claude plugin marketplace update mattstack

From dc0a79526d225e73e85856b706eaaf9d688c323c Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:28:35 -0500
Subject: [PATCH 12/30] herdr: NDJSON socket client with a fake server for
 tests

---
 lib/herdr/__tests__/client.test.ts |  67 +++++++++++++++++++
 lib/herdr/__tests__/fake-herdr.ts  |  61 +++++++++++++++++
 lib/herdr/client.ts                | 101 +++++++++++++++++++++++++++++
 3 files changed, 229 insertions(+)
 create mode 100644 lib/herdr/__tests__/client.test.ts
 create mode 100644 lib/herdr/__tests__/fake-herdr.ts
 create mode 100644 lib/herdr/client.ts

diff --git a/lib/herdr/__tests__/client.test.ts b/lib/herdr/__tests__/client.test.ts
new file mode 100644
index 00000000..0f176726
--- /dev/null
+++ b/lib/herdr/__tests__/client.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, expect, test } from "bun:test";
+import { tmpdir } from "os";
+import { join } from "path";
+import { HERDR_UNAVAILABLE, herdrAvailable, herdrRequest, waitTimeout } from "../client.ts";
+import { fakeHerdr, HerdrFakeError } from "./fake-herdr.ts";
+
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops) stop();
+  stops.length = 0;
+});
+
+test("a success reply comes back as ok with the result object", async () => {
+  const { sock, seen, stop } = fakeHerdr((method) => {
+    if (method === "pane.list") return { type: "pane_list", panes: [{ pane_id: "w1:p1" }] };
+    return new HerdrFakeError("invalid_request", "nope");
+  });
+  stops.push(stop);
+  const res = await herdrRequest<{ type: string; panes: unknown[] }>("pane.list", {}, { sockPath: sock });
+  expect(res.ok).toBe(true);
+  if (!res.ok) throw new Error("unreachable");
+  expect(res.result.panes).toHaveLength(1);
+  expect(seen[0]).toEqual({ method: "pane.list", params: {} });
+});
+
+test("an error reply comes back as ok:false with herdr's code and message", async () => {
+  const { sock, stop } = fakeHerdr(() => new HerdrFakeError("agent_blocked", "agent w1:p1 is blocked"));
+  stops.push(stop);
+  const res = await herdrRequest("agent.prompt", { target: "w1:p1", text: "hi" }, { sockPath: sock });
+  expect(res).toEqual({ ok: false, code: "agent_blocked", message: "agent w1:p1 is blocked" });
+});
+
+test("params travel verbatim, with the request id as a string", async () => {
+  const { sock, seen, stop } = fakeHerdr(() => ({ type: "ok" }));
+  stops.push(stop);
+  await herdrRequest("pane.send_input", { pane_id: "w1:p1", text: "ls", keys: ["enter"] }, { sockPath: sock });
+  expect(seen[0]!.params).toEqual({ pane_id: "w1:p1", text: "ls", keys: ["enter"] });
+});
+
+test("a missing socket is herdr unavailable, never a throw", async () => {
+  const res = await herdrRequest("pane.list", {}, { sockPath: join(tmpdir(), "no-such-herdr.sock") });
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.message.startsWith(HERDR_UNAVAILABLE)).toBe(true);
+});
+
+test("a reply slower than timeoutMs is a timeout", async () => {
+  const { sock, stop } = fakeHerdr(async () => {
+    await Bun.sleep(400);
+    return { type: "ok" };
+  });
+  stops.push(stop);
+  const res = await herdrRequest("agent.wait", { target: "w1:p1" }, { sockPath: sock, timeoutMs: 100 });
+  expect(res).toMatchObject({ ok: false, code: "timeout" });
+});
+
+test("herdrAvailable probes session.snapshot", async () => {
+  const { sock, seen, stop } = fakeHerdr(() => ({ type: "session_snapshot", snapshot: { panes: [], workspaces: [], agents: [], tabs: [], layouts: [], version: "0.8.0", protocol: 19 } }));
+  stops.push(stop);
+  expect(await herdrAvailable(sock)).toBe(true);
+  expect(seen[0]!.method).toBe("session.snapshot");
+  expect(await herdrAvailable(join(tmpdir(), "no-such-herdr.sock"))).toBe(false);
+});
+
+test("waitTimeout adds the 5s margin herdr needs to answer at its own budget", () => {
+  expect(waitTimeout(60_000)).toBe(65_000);
+});
diff --git a/lib/herdr/__tests__/fake-herdr.ts b/lib/herdr/__tests__/fake-herdr.ts
new file mode 100644
index 00000000..73c3a5d5
--- /dev/null
+++ b/lib/herdr/__tests__/fake-herdr.ts
@@ -0,0 +1,61 @@
+import { tmpdir } from "os";
+import { join } from "path";
+
+/** A reply the fake returns as herdr's `{ error: { code, message } }` envelope. */
+export class HerdrFakeError {
+  constructor(public code: string, public message: string) {}
+}
+
+export type FakeHerdrHandler = (method: string, params: Record<string, unknown>) => unknown | Promise<unknown>;
+
+let counter = 0;
+
+/**
+ * herdr's wire contract, for tests: newline-delimited JSON over a unix
+ * socket, one request per connection, the server closes after replying.
+ * The handler returns the `result` object (with its `type` field) or a
+ * HerdrFakeError; a thrown error becomes `internal_error`.
+ */
+export function fakeHerdr(handler: FakeHerdrHandler) {
+  const sock = join(tmpdir(), `fake-herdr-${process.pid}-${counter++}.sock`);
+  const seen: Array<{ method: string; params: Record<string, unknown> }> = [];
+  const buffers = new Map<object, string>();
+  const server = Bun.listen({
+    unix: sock,
+    socket: {
+      data(socket, chunk) {
+        const buf = (buffers.get(socket) ?? "") + chunk.toString();
+        const nl = buf.indexOf("\n");
+        if (nl < 0) {
+          buffers.set(socket, buf);
+          return;
+        }
+        buffers.delete(socket);
+        const line = buf.slice(0, nl);
+        void (async () => {
+          let reply: string;
+          let id = "";
+          try {
+            const req = JSON.parse(line) as { id: string; method: string; params?: Record<string, unknown> };
+            id = req.id;
+            const params = req.params ?? {};
+            seen.push({ method: req.method, params });
+            const out = await handler(req.method, params);
+            reply = out instanceof HerdrFakeError
+              ? JSON.stringify({ id, error: { code: out.code, message: out.message } })
+              : JSON.stringify({ id, result: out });
+          } catch (err) {
+            reply = JSON.stringify({ id, error: { code: "internal_error", message: err instanceof Error ? err.message : String(err) } });
+          }
+          socket.write(reply + "\n");
+          socket.end();
+        })();
+      },
+      close(socket) {
+        buffers.delete(socket);
+      },
+      error() {},
+    },
+  });
+  return { sock, seen, stop: () => server.stop(true) };
+}
diff --git a/lib/herdr/client.ts b/lib/herdr/client.ts
new file mode 100644
index 00000000..14d73fe3
--- /dev/null
+++ b/lib/herdr/client.ts
@@ -0,0 +1,101 @@
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+export const HERDR_UNAVAILABLE = "herdr unavailable";
+
+export type HerdrResult<T> = { ok: true; result: T } | { ok: false; code: string; message: string };
+
+const PLAIN_TIMEOUT_MS = 5_000;
+const WAIT_MARGIN_MS = 5_000;
+
+/** The daemon runs outside any pane, so the path is configured, never inherited from herdr. */
+export function herdrSocketPath(): string {
+  return process.env.HERDR_SOCKET_PATH ?? join(homedir(), ".config", "herdr", "herdr.sock");
+}
+
+/** herdr answers a waiting call at its budget, not before; the socket must outlive it. */
+export function waitTimeout(timeoutMs: number): number {
+  return timeoutMs + WAIT_MARGIN_MS;
+}
+
+let seq = 0;
+
+/**
+ * One request, one connection: herdr reads a single line and closes after
+ * replying, so there is nothing to pool. Never throws.
+ */
+export function herdrRequest<T = unknown>(
+  method: string,
+  params: Record<string, unknown> = {},
+  opts: { timeoutMs?: number; sockPath?: string } = {},
+): Promise<HerdrResult<T>> {
+  const sockPath = opts.sockPath ?? herdrSocketPath();
+  const timeoutMs = opts.timeoutMs ?? PLAIN_TIMEOUT_MS;
+  const id = `rt:${process.pid}:${++seq}`;
+  const line = JSON.stringify({ id, method, params }) + "\n";
+
+  return new Promise((resolve) => {
+    let settled = false;
+    let buf = "";
+    let conn: { end(): void } | undefined;
+    const finish = (r: HerdrResult<T>) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { conn?.end(); } catch { /* already closed */ }
+      resolve(r);
+    };
+    const unavailable = (detail: string): HerdrResult<T> => ({ ok: false, code: "unreachable", message: `${HERDR_UNAVAILABLE}: ${detail}` });
+    const timer = setTimeout(() => finish({ ok: false, code: "timeout", message: `herdr ${method} timed out after ${timeoutMs}ms` }), timeoutMs);
+
+    if (!existsSync(sockPath)) {
+      finish(unavailable(`no socket at ${sockPath}`));
+      return;
+    }
+
+    Bun.connect({
+      unix: sockPath,
+      socket: {
+        open(socket) {
+          conn = socket;
+          socket.write(line);
+        },
+        data(_socket, chunk) {
+          buf += chunk.toString();
+          const nl = buf.indexOf("\n");
+          if (nl < 0) return;
+          const text = buf.slice(0, nl);
+          let parsed: { result?: T; error?: { code?: string; message?: string } };
+          try {
+            parsed = JSON.parse(text);
+          } catch {
+            finish({ ok: false, code: "invalid_response", message: `herdr ${method}: unparseable reply` });
+            return;
+          }
+          if (parsed.error) {
+            finish({ ok: false, code: String(parsed.error.code ?? "error"), message: String(parsed.error.message ?? "") });
+          } else {
+            finish({ ok: true, result: parsed.result as T });
+          }
+        },
+        error(_socket, err) {
+          finish(unavailable(err.message));
+        },
+        connectError(_socket, err) {
+          finish(unavailable(err.message));
+        },
+        close() {
+          finish(unavailable("connection closed before a reply"));
+        },
+      },
+    }).catch((err: unknown) => finish(unavailable(err instanceof Error ? err.message : String(err))));
+  });
+}
+
+/** The gate every pane verb sits behind: a socket that exists and answers. */
+export async function herdrAvailable(sockPath: string = herdrSocketPath()): Promise<boolean> {
+  if (!existsSync(sockPath)) return false;
+  const res = await herdrRequest("session.snapshot", {}, { sockPath });
+  return res.ok;
+}

From c1f75dbd62254ca9af515362550bd01804b679b3 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:42:36 -0500
Subject: [PATCH 13/30] herdr: fix close-before-data race, guard settled open,
 track id in fake seen

---
 lib/herdr/__tests__/client.test.ts |  3 +-
 lib/herdr/__tests__/fake-herdr.ts  |  4 +--
 lib/herdr/client.ts                | 46 +++++++++++++++++++-----------
 3 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/lib/herdr/__tests__/client.test.ts b/lib/herdr/__tests__/client.test.ts
index 0f176726..431b7132 100644
--- a/lib/herdr/__tests__/client.test.ts
+++ b/lib/herdr/__tests__/client.test.ts
@@ -20,7 +20,7 @@ test("a success reply comes back as ok with the result object", async () => {
   expect(res.ok).toBe(true);
   if (!res.ok) throw new Error("unreachable");
   expect(res.result.panes).toHaveLength(1);
-  expect(seen[0]).toEqual({ method: "pane.list", params: {} });
+  expect(seen[0]).toEqual({ id: expect.any(String), method: "pane.list", params: {} });
 });
 
 test("an error reply comes back as ok:false with herdr's code and message", async () => {
@@ -35,6 +35,7 @@ test("params travel verbatim, with the request id as a string", async () => {
   stops.push(stop);
   await herdrRequest("pane.send_input", { pane_id: "w1:p1", text: "ls", keys: ["enter"] }, { sockPath: sock });
   expect(seen[0]!.params).toEqual({ pane_id: "w1:p1", text: "ls", keys: ["enter"] });
+  expect(typeof seen[0]!.id).toBe("string");
 });
 
 test("a missing socket is herdr unavailable, never a throw", async () => {
diff --git a/lib/herdr/__tests__/fake-herdr.ts b/lib/herdr/__tests__/fake-herdr.ts
index 73c3a5d5..64538743 100644
--- a/lib/herdr/__tests__/fake-herdr.ts
+++ b/lib/herdr/__tests__/fake-herdr.ts
@@ -18,7 +18,7 @@ let counter = 0;
  */
 export function fakeHerdr(handler: FakeHerdrHandler) {
   const sock = join(tmpdir(), `fake-herdr-${process.pid}-${counter++}.sock`);
-  const seen: Array<{ method: string; params: Record<string, unknown> }> = [];
+  const seen: Array<{ id: string; method: string; params: Record<string, unknown> }> = [];
   const buffers = new Map<object, string>();
   const server = Bun.listen({
     unix: sock,
@@ -39,7 +39,7 @@ export function fakeHerdr(handler: FakeHerdrHandler) {
             const req = JSON.parse(line) as { id: string; method: string; params?: Record<string, unknown> };
             id = req.id;
             const params = req.params ?? {};
-            seen.push({ method: req.method, params });
+            seen.push({ id, method: req.method, params });
             const out = await handler(req.method, params);
             reply = out instanceof HerdrFakeError
               ? JSON.stringify({ id, error: { code: out.code, message: out.message } })
diff --git a/lib/herdr/client.ts b/lib/herdr/client.ts
index 14d73fe3..eb1dc373 100644
--- a/lib/herdr/client.ts
+++ b/lib/herdr/client.ts
@@ -54,30 +54,36 @@ export function herdrRequest<T = unknown>(
       return;
     }
 
+    const tryParseBuffered = (): HerdrResult<T> | undefined => {
+      const nl = buf.indexOf("\n");
+      if (nl < 0) return undefined;
+      const text = buf.slice(0, nl);
+      let parsed: { result?: T; error?: { code?: string; message?: string } };
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        return { ok: false, code: "invalid_response", message: `herdr ${method}: unparseable reply` };
+      }
+      return parsed.error
+        ? { ok: false, code: String(parsed.error.code ?? "error"), message: String(parsed.error.message ?? "") }
+        : { ok: true, result: parsed.result as T };
+    };
+
     Bun.connect({
       unix: sockPath,
       socket: {
         open(socket) {
+          if (settled) {
+            try { socket.end(); } catch { /* already closed */ }
+            return;
+          }
           conn = socket;
           socket.write(line);
         },
         data(_socket, chunk) {
           buf += chunk.toString();
-          const nl = buf.indexOf("\n");
-          if (nl < 0) return;
-          const text = buf.slice(0, nl);
-          let parsed: { result?: T; error?: { code?: string; message?: string } };
-          try {
-            parsed = JSON.parse(text);
-          } catch {
-            finish({ ok: false, code: "invalid_response", message: `herdr ${method}: unparseable reply` });
-            return;
-          }
-          if (parsed.error) {
-            finish({ ok: false, code: String(parsed.error.code ?? "error"), message: String(parsed.error.message ?? "") });
-          } else {
-            finish({ ok: true, result: parsed.result as T });
-          }
+          const parsed = tryParseBuffered();
+          if (parsed) finish(parsed);
         },
         error(_socket, err) {
           finish(unavailable(err.message));
@@ -86,7 +92,15 @@ export function herdrRequest<T = unknown>(
           finish(unavailable(err.message));
         },
         close() {
-          finish(unavailable("connection closed before a reply"));
+          // `close` can fire before the `data` callback carrying a buffered
+          // reply has run; check the buffer first, then yield a turn so a
+          // pending `data` callback settles before this gives up.
+          const parsed = tryParseBuffered();
+          if (parsed) {
+            finish(parsed);
+            return;
+          }
+          queueMicrotask(() => finish(unavailable("connection closed before a reply")));
         },
       },
     }).catch((err: unknown) => finish(unavailable(err instanceof Error ? err.message : String(err))));

From 577d838fdd2df2164a34ce98abbc1e5722bedca2 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 20:52:56 -0500
Subject: [PATCH 14/30] lib: repo-for-cwd, the git-free cwd to repo resolution
 shared by chat and the pane verbs

---
 commands/chat.ts                   |  78 +---------------------
 lib/__tests__/repo-for-cwd.test.ts |  46 +++++++++++++
 lib/repo-for-cwd.ts                | 103 +++++++++++++++++++++++++++++
 3 files changed, 152 insertions(+), 75 deletions(-)
 create mode 100644 lib/__tests__/repo-for-cwd.test.ts
 create mode 100644 lib/repo-for-cwd.ts

diff --git a/commands/chat.ts b/commands/chat.ts
index 7996f581..65fb68f0 100644
--- a/commands/chat.ts
+++ b/commands/chat.ts
@@ -25,13 +25,14 @@
  * Spec: docs/superpowers/specs/2026-08-23-rt-chat-design.md
  */
 
-import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { execSync } from "child_process";
 import { homedir, hostname } from "os";
-import { basename, dirname, join, resolve as resolvePath } from "path";
+import { basename, dirname, join } from "path";
 
 import { loadRepoIndex } from "../lib/repo-index.ts";
 import { repoLabel } from "../lib/repo-arg.ts";
+import { findGitRoot, repoAliasForPath, resolveMainWorktreePath } from "../lib/repo-for-cwd.ts";
 import { getCurrentBranch, getRepoRoot } from "../lib/git.ts";
 import { getRepoIdentityForRoot } from "../lib/repo.ts";
 import { parseIdentity, type RepoIdentity } from "../lib/settings/identity.ts";
@@ -185,79 +186,6 @@ function slugify(raw: string): string {
   return slug || "x";
 }
 
-function safeRealpath(p: string): string {
-  try {
-    return realpathSync(p);
-  } catch {
-    return p;
-  }
-}
-
-/** Nearest ancestor directory holding a `.git` entry — a plain walk, never a git spawn. */
-function findGitRoot(start: string): string | null {
-  let dir = start;
-  while (true) {
-    if (existsSync(join(dir, ".git"))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-/**
- * The MAIN worktree path for `worktreeRoot`: itself when `.git` is a real
- * directory, or — for a linked worktree — the repo its `.git` FILE's
- * `gitdir: <main>/.git/worktrees/<slot>` pointer names, parsed by hand
- * (never `git worktree list`). Null when the pointer is stale or foreign
- * (a worktree whose gitdir survived a home-directory move errors with
- * "fatal: not a git repository" under real git) — this is why the
- * resolution order has a position AFTER the repo-name rung: dropping
- * straight to `<user>-<host>` here would give one shared handle to every
- * broken directory on the machine.
- */
-function resolveMainWorktreePath(worktreeRoot: string): string | null {
-  const gitPath = join(worktreeRoot, ".git");
-  let stat;
-  try {
-    stat = statSync(gitPath);
-  } catch {
-    return null;
-  }
-  if (stat.isDirectory()) return worktreeRoot;
-  if (!stat.isFile()) return null;
-
-  let content: string;
-  try {
-    content = readFileSync(gitPath, "utf8");
-  } catch {
-    return null;
-  }
-  const match = /^gitdir:\s*(.+?)\s*$/m.exec(content);
-  if (!match) return null;
-  const gitdir = match[1]!.startsWith("/") ? match[1]! : resolvePath(worktreeRoot, match[1]!);
-
-  // "<main>/.git/worktrees/<slot>" → <main>, three levels up.
-  const mainPath = dirname(dirname(dirname(gitdir)));
-  if (!existsSync(mainPath) || !existsSync(join(mainPath, ".git"))) return null;
-  return mainPath;
-}
-
-/**
- * Reverse lookup: which repos.json alias names `mainWorktreePath`. Index is an
- * explicit param so the derivation stays testable without a real HOME
- * (carry-forward fixture test). Index keys are serialized identities after the
- * RT-62 re-key (`remote:host%2Fpath`) — a wire form whose `%` and `:` the
- * handle charset forbids — so the alias is the key's display label, never the
- * key itself (repoLabel passes a legacy name-keyed row through unchanged).
- */
-function repoAliasForPath(mainWorktreePath: string, index: Record<string, string>): string | null {
-  const target = safeRealpath(mainWorktreePath);
-  for (const [name, path] of Object.entries(index)) {
-    if (safeRealpath(path) === target) return repoLabel(name);
-  }
-  return null;
-}
-
 /** `<alias>-<cwd-basename>`, or null when `cwd` isn't inside any indexed repo (or the git pointer is broken). */
 function deriveRepoDirHandle(cwd: string, index: Record<string, string>): string | null {
   const worktreeRoot = findGitRoot(cwd) ?? cwd;
diff --git a/lib/__tests__/repo-for-cwd.test.ts b/lib/__tests__/repo-for-cwd.test.ts
new file mode 100644
index 00000000..47c7dce5
--- /dev/null
+++ b/lib/__tests__/repo-for-cwd.test.ts
@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { branchForCwd, repoForCwd, resolveMainWorktreePath } from "../repo-for-cwd.ts";
+
+let root: string;
+beforeEach(() => {
+  root = realpathSync(mkdtempSync(join(tmpdir(), "rt-repo-for-cwd-")));
+});
+afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+function mainRepo(name: string): string {
+  const path = join(root, name);
+  mkdirSync(join(path, ".git", "worktrees"), { recursive: true });
+  return path;
+}
+
+test("a main worktree resolves to its own alias", () => {
+  const main = mainRepo("acme");
+  mkdirSync(join(main, "src"));
+  expect(repoForCwd(join(main, "src"), { "remote:gitlab.com%2Facme%2Facme": main })).toBe("acme");
+});
+
+test("a linked worktree resolves through its .git file to the main repo's alias", () => {
+  const main = mainRepo("acme");
+  mkdirSync(join(main, ".git", "worktrees", "wt-1"));
+  const linked = join(root, "acme-wt-1");
+  mkdirSync(linked);
+  writeFileSync(join(linked, ".git"), `gitdir: ${join(main, ".git", "worktrees", "wt-1")}\n`);
+  expect(resolveMainWorktreePath(linked)).toBe(main);
+  expect(repoForCwd(linked, { "remote:gitlab.com%2Facme%2Facme": main })).toBe("acme");
+});
+
+test("a directory outside any repo resolves to null", () => {
+  const stray = join(root, "stray");
+  mkdirSync(stray);
+  expect(repoForCwd(stray, {})).toBeNull();
+});
+
+test("branchForCwd reads the branch through an injected async exec and never throws", async () => {
+  const exec = async () => ({ stdout: "feat/x\n", stderr: "", exitCode: 0 });
+  expect(await branchForCwd("/anywhere", exec)).toBe("feat/x");
+  const failing = async () => ({ stdout: "", stderr: "", exitCode: 128 });
+  expect(await branchForCwd("/anywhere", failing)).toBeUndefined();
+});
diff --git a/lib/repo-for-cwd.ts b/lib/repo-for-cwd.ts
new file mode 100644
index 00000000..a6ea8930
--- /dev/null
+++ b/lib/repo-for-cwd.ts
@@ -0,0 +1,103 @@
+/**
+ * cwd to repo and branch, without a sync git spawn.
+ *
+ * The daemon thread never sync-execs (MAT-222): finding a cwd's repo is a
+ * `.git` walk plus a repo-index reverse lookup, both plain file reads;
+ * finding its branch is the one git call an unsigned pane needs, run async
+ * so the daemon loop never blocks.
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from "fs";
+import { dirname, join, resolve as resolvePath } from "path";
+import { repoLabel } from "./repo-label.ts";
+import { runCapture } from "./subprocess.ts";
+
+export function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** Nearest ancestor directory holding a `.git` entry — a plain walk, never a git spawn. */
+export function findGitRoot(start: string): string | null {
+  let dir = start;
+  while (true) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The MAIN worktree path for `worktreeRoot`: itself when `.git` is a real
+ * directory, or — for a linked worktree — the repo its `.git` FILE's
+ * `gitdir: <main>/.git/worktrees/<slot>` pointer names, parsed by hand
+ * (never `git worktree list`). Null when the pointer is stale or foreign
+ * (a worktree whose gitdir survived a home-directory move errors with
+ * "fatal: not a git repository" under real git) — this is why the
+ * resolution order has a position AFTER the repo-name rung: dropping
+ * straight to `<user>-<host>` here would give one shared handle to every
+ * broken directory on the machine.
+ */
+export function resolveMainWorktreePath(worktreeRoot: string): string | null {
+  const gitPath = join(worktreeRoot, ".git");
+  let stat;
+  try {
+    stat = statSync(gitPath);
+  } catch {
+    return null;
+  }
+  if (stat.isDirectory()) return worktreeRoot;
+  if (!stat.isFile()) return null;
+
+  let content: string;
+  try {
+    content = readFileSync(gitPath, "utf8");
+  } catch {
+    return null;
+  }
+  const match = /^gitdir:\s*(.+?)\s*$/m.exec(content);
+  if (!match) return null;
+  const gitdir = match[1]!.startsWith("/") ? match[1]! : resolvePath(worktreeRoot, match[1]!);
+
+  // "<main>/.git/worktrees/<slot>" → <main>, three levels up.
+  const mainPath = dirname(dirname(dirname(gitdir)));
+  if (!existsSync(mainPath) || !existsSync(join(mainPath, ".git"))) return null;
+  return mainPath;
+}
+
+/**
+ * Reverse lookup: which repos.json alias names `mainWorktreePath`. Index is an
+ * explicit param so the derivation stays testable without a real HOME
+ * (carry-forward fixture test). Index keys are serialized identities after the
+ * RT-62 re-key (`remote:host%2Fpath`) — a wire form whose `%` and `:` the
+ * handle charset forbids — so the alias is the key's display label, never the
+ * key itself (repoLabel passes a legacy name-keyed row through unchanged).
+ */
+export function repoAliasForPath(mainWorktreePath: string, index: Record<string, string>): string | null {
+  const target = safeRealpath(mainWorktreePath);
+  for (const [name, path] of Object.entries(index)) {
+    if (safeRealpath(path) === target) return repoLabel(name);
+  }
+  return null;
+}
+
+/** cwd to the repo's display label using the repo index alone: no git spawn, so it is safe on the daemon thread. */
+export function repoForCwd(cwd: string, index: Record<string, string>): string | null {
+  const gitRoot = findGitRoot(cwd);
+  if (!gitRoot) return null;
+  const main = resolveMainWorktreePath(gitRoot);
+  if (!main) return null;
+  return repoAliasForPath(main, index);
+}
+
+/** The one git call an unsigned pane needs, async so the daemon loop never blocks. */
+export async function branchForCwd(cwd: string, exec: typeof runCapture = runCapture): Promise<string | undefined> {
+  const res = await exec(["git", "-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"], { timeoutMs: 2_000 });
+  if (res.exitCode !== 0) return undefined;
+  const branch = res.stdout.trim();
+  return branch && branch !== "HEAD" ? branch : undefined;
+}

From f3a0a62c4e0c024e55685b878bd23d083586a3a1 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 21:11:39 -0500
Subject: [PATCH 15/30] daemon: pane:list and pane:peek, herdr panes joined to
 presence

---
 lib/daemon/__tests__/pane-handlers.test.ts | 120 +++++++++++++++++
 lib/daemon/command-router.ts               |   3 +
 lib/daemon/handlers/pane.ts                | 143 +++++++++++++++++++++
 packages/rt-client/src/commands.ts         |  19 +++
 4 files changed, 285 insertions(+)
 create mode 100644 lib/daemon/__tests__/pane-handlers.test.ts
 create mode 100644 lib/daemon/handlers/pane.ts

diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
new file mode 100644
index 00000000..29784731
--- /dev/null
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -0,0 +1,120 @@
+import { afterEach, expect, test } from "bun:test";
+import { tmpdir } from "os";
+import { join } from "path";
+import { HERDR_UNAVAILABLE, herdrRequest } from "../../herdr/client.ts";
+import { fakeHerdr, HerdrFakeError, type FakeHerdrHandler } from "../../herdr/__tests__/fake-herdr.ts";
+import { openStateDb } from "../../state/index.ts";
+import { createChatHandlers } from "../handlers/chat.ts";
+import { createPaneHandlers } from "../handlers/pane.ts";
+
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops) stop();
+  stops.length = 0;
+});
+
+let n = 0;
+function freshDb() {
+  return openStateDb(join(tmpdir(), `pane-h-${process.pid}-${n++}.db`));
+}
+
+const SNAPSHOT = {
+  type: "session_snapshot",
+  snapshot: {
+    version: "0.8.0",
+    protocol: 19,
+    workspaces: [{ workspace_id: "w1", label: "assured", focused: false }],
+    tabs: [],
+    layouts: [],
+    agents: [],
+    panes: [
+      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/assured", foreground_cwd: "/tmp/assured", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
+      { pane_id: "w1:p2", terminal_id: "t2", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "working", cwd: "/tmp/other", terminal_title_stripped: "fred", revision: 1 },
+      { pane_id: "w1:p3", terminal_id: "t3", workspace_id: "w1", tab_id: "w1:t2", focused: false, agent_status: "unknown", cwd: "/tmp", revision: 1 },
+    ],
+  },
+};
+
+function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string, string> } = {}) {
+  const { sock, seen, stop } = fakeHerdr(handler);
+  stops.push(stop);
+  const db = freshDb();
+  const herdr: typeof herdrRequest = (method, params, opts) => herdrRequest(method, params, { ...opts, sockPath: sock });
+  const exec = async () => ({ stdout: "feat/branch\n", stderr: "", exitCode: 0 });
+  const chat = createChatHandlers({ db, emitEvent: () => 0 });
+  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: Date.now });
+  return { db, seen, chat, pane };
+}
+
+test("pane:list lists only claude panes, joined to presence by session id, with rooms", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/assured", repo: "assured", branch: "main", pane: "w1:p1" });
+  if (!signed.ok) throw new Error(signed.error);
+  await chat["chat:join"]({ room: "build", handle: signed.data.handle });
+
+  const res = await pane["pane:list"]({});
+  expect(res.ok).toBe(true);
+  if (!res.ok) throw new Error("unreachable");
+  expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p1", "w1:p2"]);
+  const first = res.data.panes[0]!;
+  expect(first).toMatchObject({ workspace: "assured", title: "Evaluate codegen", cwd: "/tmp/assured", repo: "assured", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
+  expect(first.presence).toMatchObject({ handle: "meg", rooms: ["build"] });
+  expect(first.presence!.status).not.toBe("offline");
+});
+
+test("pane:list falls back to the presence row's pane id when herdr has no session id", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-by-pane", baseHandle: "fred", cwd: "/tmp/other", pane: "w1:p2" });
+  if (!signed.ok) throw new Error(signed.error);
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.panes.find((p) => p.paneId === "w1:p2")!.presence?.handle).toBe("fred");
+});
+
+test("pane:list derives repo and branch for an unsigned pane without touching the presence table", async () => {
+  const { pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  const unsigned = res.data.panes.find((p) => p.paneId === "w1:p2")!;
+  expect(unsigned.presence).toBeUndefined();
+  expect(unsigned.branch).toBe("feat/branch");
+  expect(unsigned.repo).toBeUndefined();
+});
+
+test("pane:list sorts listening, idle, deaf, then not signed in", async () => {
+  const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-p2", baseHandle: "fred", pane: "w1:p2" });
+  if (!signed.ok) throw new Error(signed.error);
+  const res = await pane["pane:list"]({});
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p2", "w1:p1"]);
+});
+
+test("pane:list is herdr unavailable when the socket is missing", async () => {
+  const db = freshDb();
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: join(tmpdir(), "absent-herdr.sock") });
+  const pane = createPaneHandlers({ db, repoIndex: () => ({}), herdr });
+  const res = await pane["pane:list"]({});
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.error.startsWith(HERDR_UNAVAILABLE)).toBe(true);
+});
+
+test("pane:peek reads the visible screen and drops trailing blank lines", async () => {
+  const { pane, seen } = harness((method) =>
+    method === "pane.read"
+      ? { type: "pane_read", read: { pane_id: "w1:p1", workspace_id: "w1", tab_id: "w1:t1", source: "visible", format: "text", text: "⏺ Read(x)\n  ⎿ 12 lines\n❯ \n\n\n", revision: 0, truncated: false } }
+      : new HerdrFakeError("invalid_request", method),
+  );
+  const res = await pane["pane:peek"]({ paneId: "w1:p1", lines: 8 });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data).toEqual({ paneId: "w1:p1", lines: ["⏺ Read(x)", "  ⎿ 12 lines", "❯ "] });
+  // fakeHerdr's seen entries also carry a per-request `id`; match the rest structurally.
+  expect(seen[0]).toMatchObject({ method: "pane.read", params: { pane_id: "w1:p1", source: "visible", lines: 8 } });
+});
+
+test("pane:peek passes herdr's pane_not_found through as an error", async () => {
+  const { pane } = harness(() => new HerdrFakeError("pane_not_found", "pane not found"));
+  const res = await pane["pane:peek"]({ paneId: "w9:p9" });
+  expect(res).toEqual({ ok: false, error: "pane_not_found: pane not found" });
+});
diff --git a/lib/daemon/command-router.ts b/lib/daemon/command-router.ts
index c483f380..568c7ec4 100644
--- a/lib/daemon/command-router.ts
+++ b/lib/daemon/command-router.ts
@@ -22,6 +22,7 @@ import { createProjectMRsHandlers } from "./handlers/project-mrs.ts";
 import { createEventsHandlers } from "./handlers/events.ts";
 import { createChatHandlers } from "./handlers/chat.ts";
 import { createAgentHandlers } from "./handlers/agent.ts";
+import { createPaneHandlers } from "./handlers/pane.ts";
 import { createEndpointHandlers } from "./handlers/endpoint.ts";
 import { createSettingsHandlers } from "./handlers/settings.ts";
 import { createHomeHandlers } from "./handlers/home.ts";
@@ -69,6 +70,7 @@ export function buildRoutedHandlers(opts: {
   // createChatHandlers also exposes `db` (its test-isolation seam); dropped
   // here so it never lands as a bogus "db" entry in the command map below.
   const { db: _chatDb, ...chatHandlers } = createChatHandlers({ db: opts.stateDb, emitEvent });
+  const { db: _paneDb, ...paneHandlers } = createPaneHandlers({ db: opts.stateDb, repoIndex: ctx.repoIndex });
   // Same seam as chatHandlers above: createAgentHandlers exposes `db` for
   // test isolation only.
   const { db: _agentDb, ...agentHandlers } = createAgentHandlers({ db: opts.stateDb, emitEvent, log: ctx.log });
@@ -87,6 +89,7 @@ export function buildRoutedHandlers(opts: {
     ...createEventsHandlers(opts.eventsBus, broadcast),
     ...chatHandlers,
     ...agentHandlers,
+    ...paneHandlers,
     ...createEndpointHandlers(ctx),
     ...createSettingsHandlers(),
     ...createHomeHandlers(opts.homeSnapshot),
diff --git a/lib/daemon/handlers/pane.ts b/lib/daemon/handlers/pane.ts
new file mode 100644
index 00000000..d49af95b
--- /dev/null
+++ b/lib/daemon/handlers/pane.ts
@@ -0,0 +1,143 @@
+/**
+ * pane:* daemon handlers: herdr's panes joined to rt's presence.
+ * lib/herdr/client.ts owns the socket; this module owns the join.
+ */
+import type { Database } from "bun:sqlite";
+import type { AgentStatus, BuddyStatus, ChatPane, Commands } from "../../../packages/rt-client/src/commands.ts";
+import { HERDR_UNAVAILABLE, herdrRequest, type HerdrResult } from "../../herdr/client.ts";
+import { branchForCwd, repoForCwd } from "../../repo-for-cwd.ts";
+import { listBuddies, listRooms, type PresenceRow } from "../../state/index.ts";
+import { runCapture } from "../../subprocess.ts";
+import type { CommandResult, TypedHandlers } from "./types.ts";
+
+export interface HerdrPane {
+  pane_id: string;
+  workspace_id: string;
+  tab_id: string;
+  agent?: string;
+  agent_status: AgentStatus;
+  cwd?: string;
+  foreground_cwd?: string;
+  terminal_title?: string;
+  terminal_title_stripped?: string;
+  agent_session?: { source: string; agent: string; kind: "id" | "path"; value: string };
+}
+
+export interface HerdrWorkspace {
+  workspace_id: string;
+  label: string;
+}
+
+export interface HerdrSnapshot {
+  workspaces: HerdrWorkspace[];
+  panes: HerdrPane[];
+}
+
+export interface HerdrAgent extends HerdrPane {
+  state_change_seq?: number;
+}
+
+export interface PaneRowContext {
+  db: Database;
+  repoIndex: () => Record<string, string>;
+  exec: typeof runCapture;
+  now: () => number;
+  workspaces: Map<string, string>;
+  bySession: Map<string, PresenceRow & { status: BuddyStatus }>;
+  byPane: Map<string, PresenceRow & { status: BuddyStatus }>;
+}
+
+const STATUS_ORDER: Record<BuddyStatus | "none", number> = { live: 0, idle: 1, deaf: 2, offline: 3, none: 3 };
+
+export function herdrError(res: { ok: false; code: string; message: string }): { ok: false; error: string } {
+  if (res.code === "unreachable" || res.code === "timeout") return { ok: false, error: res.message.startsWith(HERDR_UNAVAILABLE) ? res.message : `${HERDR_UNAVAILABLE}: ${res.message}` };
+  return { ok: false, error: `${res.code}: ${res.message}` };
+}
+
+/** Presence maps built once per verb call; offline rows are not presence. */
+export function presenceMaps(db: Database, now: number): Pick<PaneRowContext, "bySession" | "byPane"> {
+  const bySession = new Map<string, PresenceRow & { status: BuddyStatus }>();
+  const byPane = new Map<string, PresenceRow & { status: BuddyStatus }>();
+  for (const row of listBuddies(now, db)) {
+    if (row.status === "offline") continue;
+    bySession.set(row.sessionId, row);
+    if (row.pane) byPane.set(row.pane, row);
+  }
+  return { bySession, byPane };
+}
+
+export async function paneRow(pane: HerdrPane, ctx: PaneRowContext): Promise<ChatPane> {
+  const sessionId = pane.agent_session?.kind === "id" ? pane.agent_session.value : undefined;
+  const presence = (sessionId ? ctx.bySession.get(sessionId) : undefined) ?? ctx.byPane.get(pane.pane_id);
+  const cwd = pane.foreground_cwd ?? pane.cwd;
+  let repo = presence?.repo;
+  let branch = presence?.branch;
+  if (!presence && cwd) {
+    repo = repoForCwd(cwd, ctx.repoIndex()) ?? undefined;
+    branch = await branchForCwd(cwd, ctx.exec);
+  }
+  return {
+    paneId: pane.pane_id,
+    workspace: ctx.workspaces.get(pane.workspace_id) ?? pane.workspace_id,
+    title: pane.terminal_title_stripped ?? pane.terminal_title,
+    cwd,
+    repo,
+    branch,
+    agentStatus: pane.agent_status,
+    sessionId,
+    presence: presence
+      ? { handle: presence.handle, status: presence.status, rooms: listRooms(presence.handle, ctx.db).map((r) => r.room) }
+      : undefined,
+  };
+}
+
+export function sortPanes(panes: ChatPane[]): ChatPane[] {
+  return panes
+    .map((p, i) => ({ p, i }))
+    .sort((a, b) => STATUS_ORDER[a.p.presence?.status ?? "none"] - STATUS_ORDER[b.p.presence?.status ?? "none"] || a.i - b.i)
+    .map(({ p }) => p);
+}
+
+export function createPaneHandlers(opts: {
+  db: Database;
+  repoIndex: () => Record<string, string>;
+  herdr?: typeof herdrRequest;
+  exec?: typeof runCapture;
+  now?: () => number;
+}): Pick<TypedHandlers, "pane:list" | "pane:peek"> & { db: Database } {
+  const { db, repoIndex } = opts;
+  const herdr = opts.herdr ?? herdrRequest;
+  const exec = opts.exec ?? runCapture;
+  const now = opts.now ?? Date.now;
+
+  async function snapshot(): Promise<HerdrResult<{ snapshot: HerdrSnapshot }>> {
+    return herdr<{ snapshot: HerdrSnapshot }>("session.snapshot", {});
+  }
+
+  return {
+    db,
+
+    "pane:list": async (): Promise<CommandResult<"pane:list">> => {
+      const snap = await snapshot();
+      if (!snap.ok) return herdrError(snap);
+      const ctx: PaneRowContext = {
+        db, repoIndex, exec, now,
+        workspaces: new Map(snap.result.snapshot.workspaces.map((w) => [w.workspace_id, w.label])),
+        ...presenceMaps(db, now()),
+      };
+      const claude = snap.result.snapshot.panes.filter((p) => p.agent === "claude");
+      const rows = await Promise.all(claude.map((p) => paneRow(p, ctx)));
+      return { ok: true, data: { panes: sortPanes(rows) } };
+    },
+
+    "pane:peek": async (payload: Commands["pane:peek"]["payload"]): Promise<CommandResult<"pane:peek">> => {
+      const params: Record<string, unknown> = { pane_id: payload.paneId, source: "visible" };
+      if (payload.lines !== undefined) params.lines = payload.lines;
+      const res = await herdr<{ read: { text: string } }>("pane.read", params);
+      if (!res.ok) return herdrError(res);
+      const lines = res.result.read.text.split("\n");
+      while (lines.length && lines[lines.length - 1]!.trim() === "") lines.pop();
+      return { ok: true, data: { paneId: payload.paneId, lines } };
+    },
+  };
+}
diff --git a/packages/rt-client/src/commands.ts b/packages/rt-client/src/commands.ts
index b59af9a9..cb1cf1de 100644
--- a/packages/rt-client/src/commands.ts
+++ b/packages/rt-client/src/commands.ts
@@ -146,6 +146,21 @@ export interface PresenceRow {
   signedOutAt?: number;
 }
 
+export type AgentStatus = "idle" | "working" | "blocked" | "done" | "unknown";
+
+/** Duplicated shape on purpose (see EventsBusEvent above): mirrors the daemon's pane row, which rt-client cannot import. */
+export interface ChatPane {
+  paneId: string;
+  workspace: string;
+  title?: string;
+  cwd?: string;
+  repo?: string;
+  branch?: string;
+  agentStatus: AgentStatus;
+  sessionId?: string;
+  presence?: { handle: string; status: BuddyStatus; rooms: string[] };
+}
+
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
 export type Attention = {
@@ -295,6 +310,8 @@ export interface Commands {
   "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface }; data: AgentRecord };
   "agent:get": { payload: { id: string }; data: AgentRecord };
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
+  "pane:list": { payload: Record<string, never>; data: { panes: ChatPane[] } };
+  "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
 }
 
 export type CommandName = keyof Commands;
@@ -335,4 +352,6 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "agent:resume",
   "agent:get",
   "agent:list",
+  "pane:list",
+  "pane:peek",
 ];

From ab6382b478b8f57e412d18f7e0e36f4e74ea5509 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 21:26:18 -0500
Subject: [PATCH 16/30] daemon: pane:accounts (cswap list) and pane:directories
 (repo index plus worktrees)

---
 lib/__tests__/cswap.test.ts                | 31 +++++++++++++++++++
 lib/cswap.ts                               | 35 ++++++++++++++++++++++
 lib/daemon/__tests__/pane-handlers.test.ts | 30 +++++++++++++++++++
 lib/daemon/handlers/pane.ts                | 31 +++++++++++++++++--
 packages/rt-client/src/commands.ts         |  7 +++++
 5 files changed, 132 insertions(+), 2 deletions(-)
 create mode 100644 lib/__tests__/cswap.test.ts
 create mode 100644 lib/cswap.ts

diff --git a/lib/__tests__/cswap.test.ts b/lib/__tests__/cswap.test.ts
new file mode 100644
index 00000000..1c80a09e
--- /dev/null
+++ b/lib/__tests__/cswap.test.ts
@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { listCswapAccounts, parseCswapList } from "../cswap.ts";
+
+const CAPTURED = `
+A newer version of claude-swap is available (0.25.0). You are using 0.23.0. Run \`cswap upgrade\` to update.
+Accounts:
+  1: matthew.goodwin@assured.claims [Assured] (history: shared)
+     ├ $$:    100%   $400.07 / $400.00
+     ├ 5h:      0%
+     ├ 7d:     40%   resets Aug 30 20:00  in 4d 0h
+     └ Fable:  35%   resets Aug 30 20:00  in 4d 0h · 6m ago
+  2: someone@example.com
+     └ 5h:     12%
+`;
+
+test("parses slots, emails, aliases and a compact headroom summary", () => {
+  expect(parseCswapList(CAPTURED)).toEqual([
+    { slot: 1, email: "matthew.goodwin@assured.claims", alias: "Assured", headroom: "5h 0% · 7d 40% · Fable 35%" },
+    { slot: 2, email: "someone@example.com", headroom: "5h 12%" },
+  ]);
+});
+
+test("an empty or unrelated output parses to no accounts", () => {
+  expect(parseCswapList("")).toEqual([]);
+  expect(parseCswapList("cswap: not found")).toEqual([]);
+});
+
+test("listCswapAccounts is empty when the binary is missing or fails", async () => {
+  const missing = async () => ({ stdout: "", stderr: "", exitCode: -1 });
+  expect(await listCswapAccounts(missing)).toEqual([]);
+});
diff --git a/lib/cswap.ts b/lib/cswap.ts
new file mode 100644
index 00000000..8e81ef13
--- /dev/null
+++ b/lib/cswap.ts
@@ -0,0 +1,35 @@
+import { homedir } from "os";
+import { join } from "path";
+import type { PaneAccount } from "../packages/rt-client/src/commands.ts";
+import { runCapture } from "./subprocess.ts";
+
+const ACCOUNT_LINE = /^\s*(\d+):\s+(\S+)(?:\s+\[([^\]]+)\])?/;
+// The `$$` row is spend, not rate-limit headroom; it is skipped on purpose.
+const HEADROOM_LINE = /^\s*[├└]\s+([^:$]+):\s+(\d+)%/;
+
+export function parseCswapList(text: string): PaneAccount[] {
+  const accounts: PaneAccount[] = [];
+  const headroom: string[][] = [];
+  for (const line of text.split("\n")) {
+    const acct = ACCOUNT_LINE.exec(line);
+    if (acct) {
+      accounts.push({ slot: Number(acct[1]), email: acct[2]!, ...(acct[3] ? { alias: acct[3] } : {}) });
+      headroom.push([]);
+      continue;
+    }
+    const head = HEADROOM_LINE.exec(line);
+    if (head && headroom.length) headroom[headroom.length - 1]!.push(`${head[1]!.trim()} ${head[2]}%`);
+  }
+  return accounts.map((a, i) => (headroom[i]!.length ? { ...a, headroom: headroom[i]!.join(" · ") } : a));
+}
+
+/** launchd's PATH does not carry ~/.local/bin, so resolve the binary explicitly. */
+export function cswapBin(): string {
+  return Bun.which("cswap") ?? join(homedir(), ".local", "bin", "cswap");
+}
+
+export async function listCswapAccounts(exec: typeof runCapture = runCapture): Promise<PaneAccount[]> {
+  const res = await exec([cswapBin(), "list"], { timeoutMs: 5_000 });
+  if (res.exitCode !== 0) return [];
+  return parseCswapList(res.stdout);
+}
diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
index 29784731..79d58a8d 100644
--- a/lib/daemon/__tests__/pane-handlers.test.ts
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -118,3 +118,33 @@ test("pane:peek passes herdr's pane_not_found through as an error", async () =>
   const res = await pane["pane:peek"]({ paneId: "w9:p9" });
   expect(res).toEqual({ ok: false, error: "pane_not_found: pane not found" });
 });
+
+test("pane:accounts parses cswap list through the injected exec", async () => {
+  const db = freshDb();
+  const exec = async (argv: [string, ...string[]]) =>
+    argv[1] === "list"
+      ? { stdout: "Accounts:\n  1: a@b.c [A]\n     └ 5h: 3%\n", stderr: "", exitCode: 0 }
+      : { stdout: "", stderr: "", exitCode: 1 };
+  const pane = createPaneHandlers({ db, repoIndex: () => ({}), exec });
+  const res = await pane["pane:accounts"]({});
+  expect(res).toEqual({ ok: true, data: { accounts: [{ slot: 1, email: "a@b.c", alias: "A", headroom: "5h 3%" }] } });
+});
+
+test("pane:directories lists indexed repos and their registered worktrees, filtered by q", async () => {
+  const db = freshDb();
+  const pane = createPaneHandlers({
+    db,
+    repoIndex: () => ({ "remote:gitlab.com%2Facme%2Facme-dev": "/repos/acme-dev", "remote:github.com%2Fm%2Fchat": "/repos/chat" }),
+    registry: (name) => (name.endsWith("acme-dev") ? [{ path: "/repos/acme-dev-wt-1", branch: "feat/one" }] : []),
+  });
+  const all = await pane["pane:directories"]({});
+  if (!all.ok) throw new Error(all.error);
+  expect(all.data.directories).toEqual([
+    { path: "/repos/acme-dev", repo: "acme-dev" },
+    { path: "/repos/acme-dev-wt-1", repo: "acme-dev", branch: "feat/one" },
+    { path: "/repos/chat", repo: "chat" },
+  ]);
+  const filtered = await pane["pane:directories"]({ q: "wt-1" });
+  if (!filtered.ok) throw new Error(filtered.error);
+  expect(filtered.data.directories.map((d) => d.path)).toEqual(["/repos/acme-dev-wt-1"]);
+});
diff --git a/lib/daemon/handlers/pane.ts b/lib/daemon/handlers/pane.ts
index d49af95b..edb503ad 100644
--- a/lib/daemon/handlers/pane.ts
+++ b/lib/daemon/handlers/pane.ts
@@ -3,11 +3,14 @@
  * lib/herdr/client.ts owns the socket; this module owns the join.
  */
 import type { Database } from "bun:sqlite";
-import type { AgentStatus, BuddyStatus, ChatPane, Commands } from "../../../packages/rt-client/src/commands.ts";
+import type { AgentStatus, BuddyStatus, ChatPane, Commands, PaneDirectory } from "../../../packages/rt-client/src/commands.ts";
+import { listCswapAccounts } from "../../cswap.ts";
 import { HERDR_UNAVAILABLE, herdrRequest, type HerdrResult } from "../../herdr/client.ts";
+import { repoLabel } from "../../repo-label.ts";
 import { branchForCwd, repoForCwd } from "../../repo-for-cwd.ts";
 import { listBuddies, listRooms, type PresenceRow } from "../../state/index.ts";
 import { runCapture } from "../../subprocess.ts";
+import { loadRegistry } from "../../worktree/registry.ts";
 import type { CommandResult, TypedHandlers } from "./types.ts";
 
 export interface HerdrPane {
@@ -104,11 +107,13 @@ export function createPaneHandlers(opts: {
   herdr?: typeof herdrRequest;
   exec?: typeof runCapture;
   now?: () => number;
-}): Pick<TypedHandlers, "pane:list" | "pane:peek"> & { db: Database } {
+  registry?: (repoName: string) => Array<{ path: string; branch: string | null | undefined }>;
+}): Pick<TypedHandlers, "pane:list" | "pane:peek" | "pane:accounts" | "pane:directories"> & { db: Database } {
   const { db, repoIndex } = opts;
   const herdr = opts.herdr ?? herdrRequest;
   const exec = opts.exec ?? runCapture;
   const now = opts.now ?? Date.now;
+  const registry = opts.registry ?? ((name: string) => loadRegistry(name));
 
   async function snapshot(): Promise<HerdrResult<{ snapshot: HerdrSnapshot }>> {
     return herdr<{ snapshot: HerdrSnapshot }>("session.snapshot", {});
@@ -139,5 +144,27 @@ export function createPaneHandlers(opts: {
       while (lines.length && lines[lines.length - 1]!.trim() === "") lines.pop();
       return { ok: true, data: { paneId: payload.paneId, lines } };
     },
+
+    "pane:accounts": async (): Promise<CommandResult<"pane:accounts">> => {
+      return { ok: true, data: { accounts: await listCswapAccounts(exec) } };
+    },
+
+    "pane:directories": async (payload: Commands["pane:directories"]["payload"]): Promise<CommandResult<"pane:directories">> => {
+      const q = payload.q?.toLowerCase();
+      const seen = new Set<string>();
+      const out: PaneDirectory[] = [];
+      const push = (d: PaneDirectory) => {
+        if (seen.has(d.path)) return;
+        if (q && !d.path.toLowerCase().includes(q)) return;
+        seen.add(d.path);
+        out.push(d);
+      };
+      for (const [name, path] of Object.entries(repoIndex()).sort(([, a], [, b]) => a.localeCompare(b))) {
+        const repo = repoLabel(name);
+        push({ path, repo });
+        for (const tree of registry(name)) push({ path: tree.path, repo, ...(tree.branch ? { branch: tree.branch } : {}) });
+      }
+      return { ok: true, data: { directories: out } };
+    },
   };
 }
diff --git a/packages/rt-client/src/commands.ts b/packages/rt-client/src/commands.ts
index cb1cf1de..be4e66be 100644
--- a/packages/rt-client/src/commands.ts
+++ b/packages/rt-client/src/commands.ts
@@ -161,6 +161,9 @@ export interface ChatPane {
   presence?: { handle: string; status: BuddyStatus; rooms: string[] };
 }
 
+export interface PaneAccount { slot: number; email: string; alias?: string; headroom?: string }
+export interface PaneDirectory { path: string; repo: string; branch?: string }
+
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
 export type Attention = {
@@ -312,6 +315,8 @@ export interface Commands {
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
   "pane:list": { payload: Record<string, never>; data: { panes: ChatPane[] } };
   "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
+  "pane:accounts": { payload: Record<string, never>; data: { accounts: PaneAccount[] } };
+  "pane:directories": { payload: { q?: string }; data: { directories: PaneDirectory[] } };
 }
 
 export type CommandName = keyof Commands;
@@ -354,4 +359,6 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "agent:list",
   "pane:list",
   "pane:peek",
+  "pane:accounts",
+  "pane:directories",
 ];

From 68a7e9c029eb49bf4ded1dc41787c454a570d059 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 21:34:53 -0500
Subject: [PATCH 17/30] cswap: tolerate colon in headroom labels;
 pane:directories: isolate per-repo registry errors

---
 lib/__tests__/cswap.test.ts                |  9 +++++++++
 lib/cswap.ts                               |  3 ++-
 lib/daemon/__tests__/pane-handlers.test.ts | 18 ++++++++++++++++++
 lib/daemon/handlers/pane.ts                |  9 ++++++++-
 4 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/lib/__tests__/cswap.test.ts b/lib/__tests__/cswap.test.ts
index 1c80a09e..503a5274 100644
--- a/lib/__tests__/cswap.test.ts
+++ b/lib/__tests__/cswap.test.ts
@@ -20,6 +20,15 @@ test("parses slots, emails, aliases and a compact headroom summary", () => {
   ]);
 });
 
+test("a headroom label containing a colon still parses", () => {
+  const text = `
+Accounts:
+  1: a@b.c
+     ├ Sub:Label:  50%
+`;
+  expect(parseCswapList(text)).toEqual([{ slot: 1, email: "a@b.c", headroom: "Sub:Label 50%" }]);
+});
+
 test("an empty or unrelated output parses to no accounts", () => {
   expect(parseCswapList("")).toEqual([]);
   expect(parseCswapList("cswap: not found")).toEqual([]);
diff --git a/lib/cswap.ts b/lib/cswap.ts
index 8e81ef13..27758deb 100644
--- a/lib/cswap.ts
+++ b/lib/cswap.ts
@@ -5,7 +5,8 @@ import { runCapture } from "./subprocess.ts";
 
 const ACCOUNT_LINE = /^\s*(\d+):\s+(\S+)(?:\s+\[([^\]]+)\])?/;
 // The `$$` row is spend, not rate-limit headroom; it is skipped on purpose.
-const HEADROOM_LINE = /^\s*[├└]\s+([^:$]+):\s+(\d+)%/;
+// Lazy label capture tolerates a colon inside the label itself (e.g. "Sub:Label:").
+const HEADROOM_LINE = /^\s*[├└]\s+([^$\n]+?):\s+(\d+)%/;
 
 export function parseCswapList(text: string): PaneAccount[] {
   const accounts: PaneAccount[] = [];
diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
index 79d58a8d..6caaa1c3 100644
--- a/lib/daemon/__tests__/pane-handlers.test.ts
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -148,3 +148,21 @@ test("pane:directories lists indexed repos and their registered worktrees, filte
   if (!filtered.ok) throw new Error(filtered.error);
   expect(filtered.data.directories.map((d) => d.path)).toEqual(["/repos/acme-dev-wt-1"]);
 });
+
+test("pane:directories keeps other repos when one repo's registry throws", async () => {
+  const db = freshDb();
+  const pane = createPaneHandlers({
+    db,
+    repoIndex: () => ({ "remote:gitlab.com%2Facme%2Facme-dev": "/repos/acme-dev", "remote:github.com%2Fm%2Fchat": "/repos/chat" }),
+    registry: (name) => {
+      if (name.endsWith("acme-dev")) throw new Error("boom");
+      return [];
+    },
+  });
+  const res = await pane["pane:directories"]({});
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.directories).toEqual([
+    { path: "/repos/acme-dev", repo: "acme-dev" },
+    { path: "/repos/chat", repo: "chat" },
+  ]);
+});
diff --git a/lib/daemon/handlers/pane.ts b/lib/daemon/handlers/pane.ts
index edb503ad..9357f38b 100644
--- a/lib/daemon/handlers/pane.ts
+++ b/lib/daemon/handlers/pane.ts
@@ -162,7 +162,14 @@ export function createPaneHandlers(opts: {
       for (const [name, path] of Object.entries(repoIndex()).sort(([, a], [, b]) => a.localeCompare(b))) {
         const repo = repoLabel(name);
         push({ path, repo });
-        for (const tree of registry(name)) push({ path: tree.path, repo, ...(tree.branch ? { branch: tree.branch } : {}) });
+        // One repo's registry throwing (corrupt kv row, etc.) must not blank every other repo's listing.
+        let trees: Array<{ path: string; branch: string | null | undefined }> = [];
+        try {
+          trees = registry(name);
+        } catch {
+          trees = [];
+        }
+        for (const tree of trees) push({ path: tree.path, repo, ...(tree.branch ? { branch: tree.branch } : {}) });
       }
       return { ok: true, data: { directories: out } };
     },

From caf873362c105217139677e4f8b1e46dba197d6c Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 21:50:14 -0500
Subject: [PATCH 18/30] daemon: pane:spawn starts claude in a herdr tab;
 chat.herdrWorkspace setting

---
 lib/daemon/__tests__/pane-handlers.test.ts    | 110 +++++++++++++++++-
 lib/daemon/handlers/pane.ts                   |  84 ++++++++++++-
 packages/rt-client/src/commands.ts            |   5 +
 .../src/settings/__tests__/registry.test.ts   |   5 +-
 .../rt-client/src/settings/registry-defs.ts   |   8 ++
 5 files changed, 206 insertions(+), 6 deletions(-)

diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
index 6caaa1c3..30928da0 100644
--- a/lib/daemon/__tests__/pane-handlers.test.ts
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -35,12 +35,15 @@ const SNAPSHOT = {
   },
 };
 
+const CSWAP_EXEC = async (argv: [string, ...string[]]) =>
+  argv[1] === "list" ? { stdout: "Accounts:\n  1: me@x.y [Me]\n", stderr: "", exitCode: 0 } : { stdout: "main\n", stderr: "", exitCode: 0 };
+
 function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string, string> } = {}) {
   const { sock, seen, stop } = fakeHerdr(handler);
   stops.push(stop);
   const db = freshDb();
   const herdr: typeof herdrRequest = (method, params, opts) => herdrRequest(method, params, { ...opts, sockPath: sock });
-  const exec = async () => ({ stdout: "feat/branch\n", stderr: "", exitCode: 0 });
+  const exec = CSWAP_EXEC;
   const chat = createChatHandlers({ db, emitEvent: () => 0 });
   const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: Date.now });
   return { db, seen, chat, pane };
@@ -77,7 +80,7 @@ test("pane:list derives repo and branch for an unsigned pane without touching th
   if (!res.ok) throw new Error(res.error);
   const unsigned = res.data.panes.find((p) => p.paneId === "w1:p2")!;
   expect(unsigned.presence).toBeUndefined();
-  expect(unsigned.branch).toBe("feat/branch");
+  expect(unsigned.branch).toBe("main");
   expect(unsigned.repo).toBeUndefined();
 });
 
@@ -166,3 +169,106 @@ test("pane:directories keeps other repos when one repo's registry throws", async
     { path: "/repos/chat", repo: "chat" },
   ]);
 });
+
+function spawnFake(script: { statuses: string[]; screen?: string; agentGetFailures?: number }) {
+  let getCalls = 0;
+  let waitCalls = 0;
+  const calls: string[] = [];
+  const paneInfo = (status: string) => ({ pane_id: "w2:p7", terminal_id: "t7", workspace_id: "w2", tab_id: "w2:t3", focused: false, agent: "claude", agent_status: status, cwd: "/repos/acme-dev", terminal_title_stripped: "claude", revision: 3 });
+  const handler: FakeHerdrHandler = (method, params) => {
+    calls.push(method);
+    switch (method) {
+      case "workspace.list":
+        return { type: "workspace_list", workspaces: [{ workspace_id: "w2", label: "chat", focused: false }] };
+      case "workspace.create":
+        return { type: "workspace_created", workspace: { workspace_id: "w3", label: params.label }, tab: { tab_id: "w3:t1" }, root_pane: paneInfo("unknown") };
+      case "tab.create":
+        return { type: "tab_created", tab: { tab_id: "w2:t3", workspace_id: "w2", label: params.label }, root_pane: paneInfo("unknown") };
+      case "pane.send_input":
+      case "pane.send_keys":
+        return { type: "ok" };
+      case "agent.get":
+        if (getCalls++ < (script.agentGetFailures ?? 0)) return new HerdrFakeError("agent_not_found", "agent target w2:p7 not found");
+        return { type: "agent_info", agent: paneInfo(script.statuses[Math.min(waitCalls, script.statuses.length - 1)]!) };
+      case "agent.wait": {
+        const status = script.statuses[Math.min(waitCalls++, script.statuses.length - 1)]!;
+        if (status === "timeout") return new HerdrFakeError("timeout", "timed out waiting for agent status");
+        return { type: "agent_info", agent: paneInfo(status) };
+      }
+      case "pane.read":
+        return { type: "pane_read", read: { pane_id: "w2:p7", workspace_id: "w2", tab_id: "w2:t3", source: "visible", format: "text", text: script.screen ?? "", revision: 0, truncated: false } };
+      case "agent.prompt":
+        return { type: "agent_prompted", agent: paneInfo("working") };
+      case "pane.get":
+        return { type: "pane_info", pane: paneInfo(script.statuses[script.statuses.length - 1] === "timeout" ? "unknown" : script.statuses[script.statuses.length - 1]!) };
+      case "session.snapshot":
+        return { type: "session_snapshot", snapshot: { workspaces: [{ workspace_id: "w2", label: "chat" }], panes: [], tabs: [], layouts: [], agents: [], version: "0.8.0", protocol: 19 } };
+      default:
+        return new HerdrFakeError("invalid_request", method);
+    }
+  };
+  return { handler, calls };
+}
+
+test("pane:spawn creates a tab in the chat workspace, launches claude, waits for idle and returns the pane ready", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"], agentGetFailures: 2 });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/acme-dev", account: "Me", model: "claude-fable-5", effort: "high" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(true);
+  expect(res.data.pane).toMatchObject({ paneId: "w2:p7", workspace: "chat", cwd: "/repos/acme-dev", agentStatus: "idle" });
+  const tab = seen.find((s) => s.method === "tab.create")!;
+  expect(tab.params).toMatchObject({ workspace_id: "w2", label: "acme-dev", cwd: "/repos/acme-dev", focus: false });
+  const input = seen.find((s) => s.method === "pane.send_input")!;
+  // shellQuote leaves strings matching ^[a-zA-Z0-9_./:@=-]+$ bare; only a value outside that set gets quotes.
+  expect(input.params.text).toBe("cd /repos/acme-dev && cswap run Me --share-history -- claude --model claude-fable-5 --effort high");
+  expect(input.params.keys).toEqual(["enter"]);
+  expect(calls.filter((c) => c === "agent.get").length).toBeGreaterThanOrEqual(3);
+  expect(calls).not.toContain("workspace.create");
+});
+
+test("pane:spawn creates the workspace when the label is missing and launches plain claude without an account", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"] });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", workspace: "fleet" });
+  if (!res.ok) throw new Error(res.error);
+  expect(calls).toContain("workspace.create");
+  expect(seen.find((s) => s.method === "workspace.create")!.params).toMatchObject({ label: "fleet", focus: false });
+  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd /repos/chat && claude");
+});
+
+test("pane:spawn quotes a cwd with a space", async () => {
+  const { handler } = spawnFake({ statuses: ["idle"] });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/my repo" });
+  if (!res.ok) throw new Error(res.error);
+  expect(seen.find((s) => s.method === "pane.send_input")!.params.text).toBe("cd '/repos/my repo' && claude");
+});
+
+test("pane:spawn answers the trust dialog once, then sends the opening prompt", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["blocked", "idle"], screen: "Do you trust the files in this folder?" });
+  const { pane, seen } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", prompt: "read AGENTS.md" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(true);
+  expect(calls.filter((c) => c === "pane.send_keys")).toHaveLength(1);
+  expect(seen.find((s) => s.method === "agent.prompt")!.params).toMatchObject({ target: "w2:p7", text: "read AGENTS.md", wait: { until: ["working"], timeout_ms: 5000 } });
+});
+
+test("pane:spawn returns ready:false with the pane when idle never arrives, and does not send the prompt", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["timeout"] });
+  const { pane } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", prompt: "hi" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(false);
+  expect(res.data.pane.paneId).toBe("w2:p7");
+  expect(calls).not.toContain("agent.prompt");
+});
+
+test("pane:spawn refuses an unknown cswap account before touching herdr", async () => {
+  const { handler, calls } = spawnFake({ statuses: ["idle"] });
+  const { pane } = harness(handler);
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat", account: "nobody" });
+  expect(res).toEqual({ ok: false, error: 'unknown cswap account "nobody"' });
+  expect(calls).toHaveLength(0);
+});
diff --git a/lib/daemon/handlers/pane.ts b/lib/daemon/handlers/pane.ts
index 9357f38b..1a7d1c9f 100644
--- a/lib/daemon/handlers/pane.ts
+++ b/lib/daemon/handlers/pane.ts
@@ -3,10 +3,13 @@
  * lib/herdr/client.ts owns the socket; this module owns the join.
  */
 import type { Database } from "bun:sqlite";
+import { basename } from "path";
 import type { AgentStatus, BuddyStatus, ChatPane, Commands, PaneDirectory } from "../../../packages/rt-client/src/commands.ts";
 import { listCswapAccounts } from "../../cswap.ts";
-import { HERDR_UNAVAILABLE, herdrRequest, type HerdrResult } from "../../herdr/client.ts";
+import { HERDR_UNAVAILABLE, herdrRequest, waitTimeout, type HerdrResult } from "../../herdr/client.ts";
+import { shellQuote } from "../../herdr-launch.ts";
 import { repoLabel } from "../../repo-label.ts";
+import { getSetting } from "../../settings/resolve.ts";
 import { branchForCwd, repoForCwd } from "../../repo-for-cwd.ts";
 import { listBuddies, listRooms, type PresenceRow } from "../../state/index.ts";
 import { runCapture } from "../../subprocess.ts";
@@ -52,6 +55,19 @@ export interface PaneRowContext {
 
 const STATUS_ORDER: Record<BuddyStatus | "none", number> = { live: 0, idle: 1, deaf: 2, offline: 3, none: 3 };
 
+const REGISTER_BUDGET_MS = 10_000;
+const REGISTER_POLL_MS = 250;
+const IDLE_BUDGET_MS = 50_000;
+const TRUST_BUDGET_MS = 15_000;
+const PROMPT_BUDGET_MS = 5_000;
+const SETTLED = ["idle", "done", "blocked"];
+
+export function launchCommand(a: { cwd: string; account?: string; model?: string; effort?: string }): string {
+  const claude = ["claude", ...(a.model ? ["--model", shellQuote(a.model)] : []), ...(a.effort ? ["--effort", shellQuote(a.effort)] : [])].join(" ");
+  const launch = a.account ? `cswap run ${shellQuote(a.account)} --share-history -- ${claude}` : claude;
+  return `cd ${shellQuote(a.cwd)} && ${launch}`;
+}
+
 export function herdrError(res: { ok: false; code: string; message: string }): { ok: false; error: string } {
   if (res.code === "unreachable" || res.code === "timeout") return { ok: false, error: res.message.startsWith(HERDR_UNAVAILABLE) ? res.message : `${HERDR_UNAVAILABLE}: ${res.message}` };
   return { ok: false, error: `${res.code}: ${res.message}` };
@@ -108,7 +124,7 @@ export function createPaneHandlers(opts: {
   exec?: typeof runCapture;
   now?: () => number;
   registry?: (repoName: string) => Array<{ path: string; branch: string | null | undefined }>;
-}): Pick<TypedHandlers, "pane:list" | "pane:peek" | "pane:accounts" | "pane:directories"> & { db: Database } {
+}): Pick<TypedHandlers, "pane:list" | "pane:peek" | "pane:accounts" | "pane:directories" | "pane:spawn"> & { db: Database } {
   const { db, repoIndex } = opts;
   const herdr = opts.herdr ?? herdrRequest;
   const exec = opts.exec ?? runCapture;
@@ -173,5 +189,69 @@ export function createPaneHandlers(opts: {
       }
       return { ok: true, data: { directories: out } };
     },
+
+    "pane:spawn": async (payload: Commands["pane:spawn"]["payload"]): Promise<CommandResult<"pane:spawn">> => {
+      const { cwd, account, model, effort, prompt } = payload;
+      if (!cwd || !cwd.startsWith("/")) return { ok: false, error: "cwd must be an absolute path" };
+      if (account) {
+        const accounts = await listCswapAccounts(exec);
+        const known = accounts.some((a) => a.alias === account || a.email === account || String(a.slot) === account);
+        if (!known) return { ok: false, error: `unknown cswap account "${account}"` };
+      }
+
+      const label = payload.workspace ?? getSetting<string>("chat.herdrWorkspace").value ?? "chat";
+      const list = await herdr<{ workspaces: HerdrWorkspace[] }>("workspace.list", {});
+      if (!list.ok) return herdrError(list);
+      let workspaceId = list.result.workspaces.find((w) => w.label === label)?.workspace_id;
+      if (!workspaceId) {
+        const created = await herdr<{ workspace: HerdrWorkspace }>("workspace.create", { label, focus: false });
+        if (!created.ok) return herdrError(created);
+        workspaceId = created.result.workspace.workspace_id;
+      }
+
+      const tab = await herdr<{ root_pane: HerdrPane }>("tab.create", { workspace_id: workspaceId, label: basename(cwd), cwd, focus: false });
+      if (!tab.ok) return herdrError(tab);
+      const paneId = tab.result.root_pane.pane_id;
+
+      const sent = await herdr("pane.send_input", { pane_id: paneId, text: launchCommand({ cwd, account, model, effort }), keys: ["enter"] });
+      if (!sent.ok) return herdrError(sent);
+
+      // herdr registers the agent a few hundred ms after the shell starts claude.
+      let registered = false;
+      for (let attempt = 0; attempt < Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS); attempt++) {
+        const got = await herdr("agent.get", { target: paneId });
+        if (got.ok) {
+          registered = true;
+          break;
+        }
+        await Bun.sleep(REGISTER_POLL_MS);
+      }
+
+      let status: AgentStatus = "unknown";
+      let ready = false;
+      if (registered) {
+        const settled = await herdr<{ agent: HerdrAgent }>("agent.wait", { target: paneId, until: SETTLED, timeout_ms: IDLE_BUDGET_MS }, { timeoutMs: waitTimeout(IDLE_BUDGET_MS) });
+        if (settled.ok) status = settled.result.agent.agent_status;
+        if (status === "blocked") {
+          const screen = await herdr<{ read: { text: string } }>("pane.read", { pane_id: paneId, source: "visible" });
+          if (screen.ok && /trust/i.test(screen.result.read.text)) {
+            await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+            const again = await herdr<{ agent: HerdrAgent }>("agent.wait", { target: paneId, until: SETTLED, timeout_ms: TRUST_BUDGET_MS }, { timeoutMs: waitTimeout(TRUST_BUDGET_MS) });
+            if (again.ok) status = again.result.agent.agent_status;
+          }
+        }
+        ready = status === "idle" || status === "done";
+      }
+
+      if (ready && prompt) {
+        await herdr("agent.prompt", { target: paneId, text: prompt, wait: { until: ["working"], timeout_ms: PROMPT_BUDGET_MS } }, { timeoutMs: waitTimeout(PROMPT_BUDGET_MS) });
+      }
+
+      const info = await herdr<{ pane: HerdrPane }>("pane.get", { pane_id: paneId });
+      const raw: HerdrPane = info.ok ? info.result.pane : { ...tab.result.root_pane, agent: "claude", agent_status: status };
+      const ctx: PaneRowContext = { db, repoIndex, exec, now, workspaces: new Map([[workspaceId, label]]), ...presenceMaps(db, now()) };
+      const pane = await paneRow(raw, ctx);
+      return { ok: true, data: { pane, ready } };
+    },
   };
 }
diff --git a/packages/rt-client/src/commands.ts b/packages/rt-client/src/commands.ts
index be4e66be..5d4ab5df 100644
--- a/packages/rt-client/src/commands.ts
+++ b/packages/rt-client/src/commands.ts
@@ -317,6 +317,10 @@ export interface Commands {
   "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
   "pane:accounts": { payload: Record<string, never>; data: { accounts: PaneAccount[] } };
   "pane:directories": { payload: { q?: string }; data: { directories: PaneDirectory[] } };
+  "pane:spawn": {
+    payload: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string };
+    data: { pane: ChatPane; ready: boolean };
+  };
 }
 
 export type CommandName = keyof Commands;
@@ -361,4 +365,5 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "pane:peek",
   "pane:accounts",
   "pane:directories",
+  "pane:spawn",
 ];
diff --git a/packages/rt-client/src/settings/__tests__/registry.test.ts b/packages/rt-client/src/settings/__tests__/registry.test.ts
index 47c0e9bd..1b534ea0 100644
--- a/packages/rt-client/src/settings/__tests__/registry.test.ts
+++ b/packages/rt-client/src/settings/__tests__/registry.test.ts
@@ -197,7 +197,7 @@ describe("settings/registry", () => {
       expect(def?.merge).toBe("replace");
     });
 
-    test("has exactly the 22 migrated:true keys and the 41 suite keys", () => {
+    test("has exactly the 22 migrated:true keys and the 42 suite keys", () => {
       const migratedFalseKeys: string[] = [];
       const migratedTrueKeys = [
         "rt.roles", "rt.intercepts", "rt.worktrees", "rt.repoIdentityOverrides", "rt.repoRoots",
@@ -241,6 +241,7 @@ describe("settings/registry", () => {
         "chat.handle",
         "chat.humanHandle",
         "chat.viewerUrl",
+        "chat.herdrWorkspace",
         "chat.push.provider",
         "chat.push.target",
         "agent.model",
@@ -248,7 +249,7 @@ describe("settings/registry", () => {
         "agent.account",
         "agent.extraArgs",
       ];
-      expect(suiteKeys).toHaveLength(41);
+      expect(suiteKeys).toHaveLength(42);
 
       expect(allDefs().map((d) => d.key).sort()).toEqual(
         [...migratedFalseKeys, ...migratedTrueKeys, ...suiteKeys].sort(),
diff --git a/packages/rt-client/src/settings/registry-defs.ts b/packages/rt-client/src/settings/registry-defs.ts
index ecf9703a..f0109ddd 100644
--- a/packages/rt-client/src/settings/registry-defs.ts
+++ b/packages/rt-client/src/settings/registry-defs.ts
@@ -480,6 +480,14 @@ export const REGISTRY: readonly SettingDef[] = [
     merge: "replace",
     description: "Base URL of the chat viewer, no trailing slash. When set, rt chat post and the tail's wake lines end with a link to the room or message.",
   },
+  {
+    key: "chat.herdrWorkspace",
+    type: "string",
+    scopes: ["user"],
+    default: "chat",
+    merge: "replace",
+    description: "herdr workspace label that rt pane spawn opens new agent tabs in; created when missing.",
+  },
   {
     key: "chat.push.provider",
     type: "string",

From 250d4cb812fbce93d68f91dd3314b7c540e6e07d Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 22:08:27 -0500
Subject: [PATCH 19/30] daemon: chat:invite types /chat:join into a herdr pane

---
 lib/daemon/__tests__/chat-handlers.test.ts | 95 +++++++++++++++++++++-
 lib/daemon/handlers/chat.ts                | 48 +++++++++++
 packages/rt-client/src/commands.ts         |  3 +
 3 files changed, 144 insertions(+), 2 deletions(-)

diff --git a/lib/daemon/__tests__/chat-handlers.test.ts b/lib/daemon/__tests__/chat-handlers.test.ts
index 3c072766..ba358d7e 100644
--- a/lib/daemon/__tests__/chat-handlers.test.ts
+++ b/lib/daemon/__tests__/chat-handlers.test.ts
@@ -1,12 +1,20 @@
-import { beforeEach, expect, test } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import type { Database } from "bun:sqlite";
 import { tmpdir } from "os";
 import { join } from "path";
 import { openStateDb } from "../../state/index.ts";
-import { createChatHandlers } from "../handlers/chat.ts";
+import { createChatHandlers, inviteText } from "../handlers/chat.ts";
+import { herdrRequest } from "../../herdr/client.ts";
+import { fakeHerdr, HerdrFakeError, type FakeHerdrHandler } from "../../herdr/__tests__/fake-herdr.ts";
 import { drainNotifications, loadNotificationPrefs, peekNotifications, saveNotificationPrefs } from "../../notifier.ts";
 import { setSetting } from "../../settings/write.ts";
 
+const stops: Array<() => void> = [];
+afterEach(() => {
+  for (const stop of stops) stop();
+  stops.length = 0;
+});
+
 let n = 0;
 function freshHandlers(emitEvent: (topic: string, payload?: unknown) => number = () => 0) {
   const db = openStateDb(join(tmpdir(), `chat-h-${process.pid}-${n++}.db`));
@@ -429,3 +437,86 @@ test("chat:who reads an unsigned member as live right after arming, even joined
   const memberA = who.data.members.find((m) => m.handle === "a");
   expect(memberA?.status).toBe("live");
 });
+
+// ─── chat:invite ──────────────────────────────────────────────────────────
+
+function inviteHarness(handler: FakeHerdrHandler) {
+  const { sock, seen, stop } = fakeHerdr(handler);
+  stops.push(stop);
+  const db = openStateDb(join(tmpdir(), `chat-inv-${process.pid}-${n++}.db`));
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: sock });
+  return { h: createChatHandlers({ db, emitEvent: () => 0, herdr }), seen };
+}
+
+const agent = (status: string, kind = "claude") => ({ type: "agent_info", agent: { pane_id: "w1:p1", terminal_id: "t", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: kind, agent_status: status, revision: 1 } });
+
+test("inviteText is one line: the slash command, then the attributed note with newlines collapsed", () => {
+  expect(inviteText("build", "matt")).toBe("/chat:join build");
+  expect(inviteText("build", "fred", "take the\nserver half\n")).toBe("/chat:join build note from fred: take the server half");
+});
+
+test("chat:invite prompts an idle pane and reports accepted when it reaches working", async () => {
+  const { h, seen } = inviteHarness((method, params) => {
+    if (method === "agent.get") return agent("idle");
+    if (method === "agent.prompt") return { type: "agent_prompted", agent: { ...agent("working").agent, text: params.text } };
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt", note: "you own vite" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "accepted" } });
+  const prompt = seen.find((s) => s.method === "agent.prompt")!;
+  expect(prompt.params).toEqual({ target: "w1:p1", text: "/chat:join build note from matt: you own vite", wait: { until: ["working"], timeout_ms: 5000 } });
+});
+
+test("chat:invite queues into a working pane without waiting", async () => {
+  const { h, seen } = inviteHarness((method) => {
+    if (method === "agent.get") return agent("working");
+    if (method === "agent.prompt") return { type: "agent_prompted", agent: agent("working").agent };
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "queued" } });
+  expect(seen.find((s) => s.method === "agent.prompt")!.params).toEqual({ target: "w1:p1", text: "/chat:join build" });
+});
+
+test("chat:invite refuses a blocked pane without sending anything", async () => {
+  const { h, seen } = inviteHarness((method) => (method === "agent.get" ? agent("blocked") : new HerdrFakeError("invalid_request", method)));
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "at a prompt" } });
+  expect(seen.map((s) => s.method)).toEqual(["agent.get"]);
+});
+
+test("chat:invite nudges Enter once on a stalled prompt, then reports accepted or queued honestly", async () => {
+  let prompts = 0;
+  const { h, seen } = inviteHarness((method) => {
+    if (method === "agent.get") return agent("idle");
+    // herdr answers a stall inside the 5s effect window with `timeout`; `agent_prompt_stalled` needs a longer budget. The handler accepts both.
+    if (method === "agent.prompt") { prompts++; return new HerdrFakeError("timeout", "timed out waiting for agent status"); }
+    if (method === "pane.send_keys") return { type: "ok" };
+    if (method === "agent.wait") return new HerdrFakeError("timeout", "timed out waiting for agent status");
+    return new HerdrFakeError("invalid_request", method);
+  });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "queued" } });
+  expect(prompts).toBe(1);
+  expect(seen.filter((s) => s.method === "pane.send_keys")).toHaveLength(1);
+});
+
+test("chat:invite refuses a pane that is not a claude pane, the caller's own pane, and a bad room", async () => {
+  const { h } = inviteHarness((method) => (method === "agent.get" ? new HerdrFakeError("agent_not_found", "agent target w1:p1 not found") : new HerdrFakeError("invalid_request", method)));
+  expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "not a claude pane" } });
+  expect(await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt", callerPane: "w1:p1" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "that is this pane" } });
+  const codex = inviteHarness((method) => (method === "agent.get" ? agent("idle", "codex") : new HerdrFakeError("invalid_request", method)));
+  expect(await codex.h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" })).toEqual({ ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "not a claude pane" } });
+  const bad = await h["chat:invite"]({ paneId: "w1:p1", room: "Bad Room", from: "matt" });
+  expect(bad.ok).toBe(false);
+});
+
+test("chat:invite is herdr unavailable when the socket is missing", async () => {
+  const db = openStateDb(join(tmpdir(), `chat-inv-${process.pid}-${n++}.db`));
+  const herdr: typeof herdrRequest = (m, p, o) => herdrRequest(m, p, { ...o, sockPath: join(tmpdir(), "absent-herdr.sock") });
+  const h = createChatHandlers({ db, emitEvent: () => 0, herdr });
+  const res = await h["chat:invite"]({ paneId: "w1:p1", room: "build", from: "matt" });
+  expect(res.ok).toBe(false);
+  if (res.ok) throw new Error("unreachable");
+  expect(res.error.startsWith("herdr unavailable")).toBe(true);
+});
diff --git a/lib/daemon/handlers/chat.ts b/lib/daemon/handlers/chat.ts
index 18cde0a5..ab0726e7 100644
--- a/lib/daemon/handlers/chat.ts
+++ b/lib/daemon/handlers/chat.ts
@@ -39,6 +39,8 @@ import {
 import { CHAT_NOTIFICATION_CATEGORY, notifyEnabled } from "../../notifier.ts";
 import { chatViewerUrl, readChatViewerUrlSetting } from "../../chat-viewer-url.ts";
 import { getSetting } from "../../settings/resolve.ts";
+import { herdrRequest, waitTimeout } from "../../herdr/client.ts";
+import { herdrError } from "./pane.ts";
 import type { Commands } from "../../../packages/rt-client/src/commands.ts";
 import type { CommandResult, TypedHandlers } from "./types.ts";
 
@@ -62,6 +64,7 @@ const CHAT_COMMANDS = [
   "chat:buddies",
   "chat:pulse",
   "chat:dm",
+  "chat:invite",
 ] as const;
 
 /** Collapses the repeated try/catch every presence-assertion call site needs into one line: null on success, the refusal's message on throw. */
@@ -137,11 +140,22 @@ function unreadSummaryFor(handle: string, db: Database): { dms: number; mentions
   return { dms, mentions, rooms: Math.max(0, nonDmWaking - mentions) };
 }
 
+const INVITE_WAIT_MS = 5_000;
+
+/** One line, because Claude Code dispatches a slash command from the first line only. */
+export function inviteText(room: string, from: string, note?: string): string {
+  const head = `/chat:join ${room}`;
+  const body = note?.replace(/\s*\n+\s*/g, " ").trim();
+  return body ? `${head} note from ${from}: ${body}` : head;
+}
+
 export function createChatHandlers(opts: {
   db: Database;
   emitEvent: (topic: string, payload?: unknown) => unknown;
+  herdr?: typeof herdrRequest;
 }): Pick<TypedHandlers, (typeof CHAT_COMMANDS)[number]> & { db: Database } {
   const { db, emitEvent } = opts;
+  const herdr = opts.herdr ?? herdrRequest;
 
   return {
     db,
@@ -328,5 +342,39 @@ export function createChatHandlers(opts: {
       if (!posted) return { ok: false, error: "chat: dm failed (retry budget exhausted)" };
       return { ok: true, data: { room, id: posted.id, recipients: posted.recipients } };
     },
+
+    "chat:invite": async (payload: Commands["chat:invite"]["payload"]): Promise<CommandResult<"chat:invite">> => {
+      const { paneId, room, note, from, callerPane } = payload;
+      if (!isValidChatName(room)) return { ok: false, error: `invalid room "${room}"` };
+      if (!isValidChatName(from)) return { ok: false, error: `invalid handle "${from}"` };
+      const refused = (reason: string): CommandResult<"chat:invite"> => ({ ok: true, data: { paneId, delivered: "refused", reason } });
+      if (callerPane && callerPane === paneId) return refused("that is this pane");
+
+      const probe = await herdr<{ agent: { agent: string; agent_status: string } }>("agent.get", { target: paneId });
+      if (!probe.ok) {
+        if (probe.code === "agent_not_found" || probe.code === "agent_target_ambiguous") return refused("not a claude pane");
+        return herdrError(probe);
+      }
+      if (probe.result.agent.agent !== "claude") return refused("not a claude pane");
+      const status = probe.result.agent.agent_status;
+      if (status === "blocked") return refused("at a prompt");
+
+      const text = inviteText(room, from, note);
+      if (status === "working") {
+        const queued = await herdr("agent.prompt", { target: paneId, text });
+        if (!queued.ok) return queued.code === "agent_blocked" ? refused("at a prompt") : herdrError(queued);
+        return { ok: true, data: { paneId, delivered: "queued" } };
+      }
+
+      const prompted = await herdr("agent.prompt", { target: paneId, text, wait: { until: ["working"], timeout_ms: INVITE_WAIT_MS } }, { timeoutMs: waitTimeout(INVITE_WAIT_MS) });
+      if (prompted.ok) return { ok: true, data: { paneId, delivered: "accepted" } };
+      if (prompted.code === "agent_blocked") return refused("at a prompt");
+      if (prompted.code !== "timeout" && prompted.code !== "agent_prompt_stalled") return herdrError(prompted);
+
+      // The Claude TUI can absorb the bundled Enter into the composer; one nudge, one more wait.
+      await herdr("pane.send_keys", { pane_id: paneId, keys: ["enter"] });
+      const nudged = await herdr("agent.wait", { target: paneId, until: ["working"], timeout_ms: INVITE_WAIT_MS }, { timeoutMs: waitTimeout(INVITE_WAIT_MS) });
+      return { ok: true, data: { paneId, delivered: nudged.ok ? "accepted" : "queued" } };
+    },
   };
 }
diff --git a/packages/rt-client/src/commands.ts b/packages/rt-client/src/commands.ts
index 5d4ab5df..da6b7c81 100644
--- a/packages/rt-client/src/commands.ts
+++ b/packages/rt-client/src/commands.ts
@@ -163,6 +163,7 @@ export interface ChatPane {
 
 export interface PaneAccount { slot: number; email: string; alias?: string; headroom?: string }
 export interface PaneDirectory { path: string; repo: string; branch?: string }
+export interface InviteResult { paneId: string; delivered: "accepted" | "queued" | "refused"; reason?: string }
 
 // SKILLS-53: one judgment, computed once in rt, so the console and the tray
 // never derive two verdicts that can disagree.
@@ -313,6 +314,7 @@ export interface Commands {
   "agent:resume": { payload: { id: string; prompt?: string; surface?: AgentSurface }; data: AgentRecord };
   "agent:get": { payload: { id: string }; data: AgentRecord };
   "agent:list": { payload: { repo?: string }; data: { agents: AgentRecord[] } };
+  "chat:invite": { payload: { paneId: string; room: string; note?: string; from: string; callerPane?: string }; data: InviteResult };
   "pane:list": { payload: Record<string, never>; data: { panes: ChatPane[] } };
   "pane:peek": { payload: { paneId: string; lines?: number }; data: { paneId: string; lines: string[] } };
   "pane:accounts": { payload: Record<string, never>; data: { accounts: PaneAccount[] } };
@@ -361,6 +363,7 @@ export const COMMAND_NAMES: readonly CommandName[] = [
   "agent:resume",
   "agent:get",
   "agent:list",
+  "chat:invite",
   "pane:list",
   "pane:peek",
   "pane:accounts",

From e33708e8e7721bafca73205a85ef76622f4e7e38 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 22:20:53 -0500
Subject: [PATCH 20/30] rt-client: pane and invite wrappers with their own
 timeouts

---
 packages/rt-client/README.md                  |  2 +
 packages/rt-client/src/client.ts              | 47 +++++++++++++++++++
 packages/rt-client/src/index.ts               | 11 +++++
 packages/rt-client/test/client.test.ts        | 35 +++++++++++++-
 packages/rt-client/test/index-surface.test.ts | 11 +++++
 5 files changed, 104 insertions(+), 2 deletions(-)

diff --git a/packages/rt-client/README.md b/packages/rt-client/README.md
index cc728cc6..1f5e8983 100644
--- a/packages/rt-client/README.md
+++ b/packages/rt-client/README.md
@@ -103,6 +103,8 @@ const stop = createRelay({                                     // one daemon sub
 | `chatJoin` / `chatLeave` | membership (`wakeOn: mention \| all \| none`) |
 | `chatPost` / `chatDm` / `chatRead` / `chatMessages` / `chatMark` | messages: post, DM, read-and-advance, page, advance the cursor |
 | `chatArm` / `chatTouch` / `chatDisarm` / `chatUnreadWaking` | the tail's wake protocol; the CLI's `rt chat tail` uses these |
+| `paneList` / `panePeek` / `paneSpawn` / `paneAccounts` / `paneDirectories` | herdr panes: list with presence joined, peek a screen, start claude in a tab, cswap accounts, directory suggestions |
+| `chatInvite` | type `/chat:join <room>` into a pane; `accepted`, `queued` or `refused` |
 | `createRelay` / `subscribe` | the event stream; `daemonHealth` the reachability probe |
 
 Pass `{ sockPath }` as the trailing options to reach a non-default daemon
diff --git a/packages/rt-client/src/client.ts b/packages/rt-client/src/client.ts
index 19d2fa7b..1ee52df3 100644
--- a/packages/rt-client/src/client.ts
+++ b/packages/rt-client/src/client.ts
@@ -23,6 +23,10 @@ import type {
   PresenceRow,
   AgentRecord,
   Commands,
+  ChatPane,
+  PaneAccount,
+  PaneDirectory,
+  InviteResult,
 } from "./commands.ts";
 
 /**
@@ -357,3 +361,46 @@ export function agentList(a: { repo?: string }, o: RtClientOptions = {}): Promis
   if (a.repo !== undefined) payload.repo = a.repo;
   return rtCommand<{ agents: AgentRecord[] }>("agent:list", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
+
+// ─── Panes (rt chat invite) ────────────────────────────────────────────────
+// herdr-facing verbs; the daemon answers `herdr unavailable` without herdr.
+
+export function paneList(o: RtClientOptions = {}): Promise<RtResponse<{ panes: ChatPane[] }>> {
+  return rtCommand<{ panes: ChatPane[] }>("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function panePeek(a: { paneId: string; lines?: number }, o: RtClientOptions = {}): Promise<RtResponse<{ paneId: string; lines: string[] }>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId };
+  if (a.lines !== undefined) payload.lines = a.lines;
+  return rtCommand<{ paneId: string; lines: string[] }>("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+/** The spawn waits on claude starting, so its budget is minutes, not seconds. */
+export function paneSpawn(
+  a: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<{ pane: ChatPane; ready: boolean }>> {
+  const payload: Record<string, unknown> = { cwd: a.cwd };
+  for (const k of ["account", "model", "effort", "prompt", "workspace"] as const) if (a[k] !== undefined) payload[k] = a[k];
+  return rtCommand<{ pane: ChatPane; ready: boolean }>("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90_000 });
+}
+
+export function paneAccounts(o: RtClientOptions = {}): Promise<RtResponse<{ accounts: PaneAccount[] }>> {
+  return rtCommand<{ accounts: PaneAccount[] }>("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function paneDirectories(a: { q?: string }, o: RtClientOptions = {}): Promise<RtResponse<{ directories: PaneDirectory[] }>> {
+  const payload: Record<string, unknown> = {};
+  if (a.q !== undefined) payload.q = a.q;
+  return rtCommand<{ directories: PaneDirectory[] }>("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+}
+
+export function chatInvite(
+  a: { paneId: string; room: string; note?: string; from: string; callerPane?: string },
+  o: RtClientOptions = {},
+): Promise<RtResponse<InviteResult>> {
+  const payload: Record<string, unknown> = { paneId: a.paneId, room: a.room, from: a.from };
+  if (a.note !== undefined) payload.note = a.note;
+  if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
+  return rtCommand<InviteResult>("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+}
diff --git a/packages/rt-client/src/index.ts b/packages/rt-client/src/index.ts
index 236214e7..29abcd72 100644
--- a/packages/rt-client/src/index.ts
+++ b/packages/rt-client/src/index.ts
@@ -34,6 +34,12 @@ export {
   agentResume,
   agentGet,
   agentList,
+  paneList,
+  panePeek,
+  paneSpawn,
+  paneAccounts,
+  paneDirectories,
+  chatInvite,
 } from "./client.ts";
 
 export { COMMAND_NAMES } from "./commands.ts";
@@ -64,6 +70,11 @@ export type {
   PresenceRow,
   AgentRecord,
   AgentSurface,
+  AgentStatus,
+  ChatPane,
+  PaneAccount,
+  PaneDirectory,
+  InviteResult,
 } from "./commands.ts";
 
 export { subscribe, createRelay, DEFAULT_WS_URL } from "./relay.ts";
diff --git a/packages/rt-client/test/client.test.ts b/packages/rt-client/test/client.test.ts
index 5984b40e..a023a332 100644
--- a/packages/rt-client/test/client.test.ts
+++ b/packages/rt-client/test/client.test.ts
@@ -1,5 +1,5 @@
-import { describe, expect, test, afterEach } from "bun:test";
-import { readProjectMRs, readDiscussions, readMrsByBranch, listRuns, abandonRun, readBranchCache } from "../src/client.ts";
+import { describe, expect, test, afterEach, spyOn } from "bun:test";
+import { readProjectMRs, readDiscussions, readMrsByBranch, listRuns, abandonRun, readBranchCache, chatInvite, paneDirectories, paneList, panePeek, paneSpawn } from "../src/client.ts";
 import { fakeDaemon } from "./fake-daemon.ts";
 
 const stops: Array<() => void> = [];
@@ -129,3 +129,34 @@ describe("run verbs", () => {
     expect(seen[1]!.payload).toEqual({ runId: "run-2" });
   });
 });
+
+describe("pane wrappers", () => {
+  test("paneList sends an empty payload; panePeek and paneDirectories omit undefined fields", async () => {
+    const { sock, seen, stop } = fakeDaemon({
+      "pane:list": { ok: true, data: { panes: [] } },
+      "pane:peek": { ok: true, data: { paneId: "w1:p1", lines: [] } },
+      "pane:directories": { ok: true, data: { directories: [] } },
+    });
+    stops.push(stop);
+    await paneList({ sockPath: sock });
+    await panePeek({ paneId: "w1:p1" }, { sockPath: sock });
+    await paneDirectories({}, { sockPath: sock });
+    expect(seen.map((s) => [s.cmd, s.payload])).toEqual([
+      ["pane:list", {}],
+      ["pane:peek", { paneId: "w1:p1" }],
+      ["pane:directories", {}],
+    ]);
+  });
+
+  test("paneSpawn and chatInvite outlive rt-client's 15s default", async () => {
+    const { sock, stop } = fakeDaemon({});
+    stops.push(stop);
+    // fakeDaemon answers instantly; the assertion is on the timeout the wrapper hands rtCommand,
+    // captured through the AbortSignal it builds. Spy on AbortSignal.timeout.
+    const spy = spyOn(AbortSignal, "timeout");
+    await paneSpawn({ cwd: "/x" }, { sockPath: sock });
+    await chatInvite({ paneId: "w1:p1", room: "build", from: "matt" }, { sockPath: sock });
+    expect(spy.mock.calls.map((c) => c[0])).toEqual([90_000, 30_000]);
+    spy.mockRestore();
+  });
+});
diff --git a/packages/rt-client/test/index-surface.test.ts b/packages/rt-client/test/index-surface.test.ts
index ea4c7000..3e44b562 100644
--- a/packages/rt-client/test/index-surface.test.ts
+++ b/packages/rt-client/test/index-surface.test.ts
@@ -41,3 +41,14 @@ describe("index.ts branch cache surface", () => {
     expect(typeof rtClient.readBranchCache).toBe("function");
   });
 });
+
+describe("index.ts pane and invite surface", () => {
+  test("exports the pane and invite wrappers", () => {
+    expect(typeof rtClient.paneList).toBe("function");
+    expect(typeof rtClient.panePeek).toBe("function");
+    expect(typeof rtClient.paneSpawn).toBe("function");
+    expect(typeof rtClient.paneAccounts).toBe("function");
+    expect(typeof rtClient.paneDirectories).toBe("function");
+    expect(typeof rtClient.chatInvite).toBe("function");
+  });
+});

From af86a71c04d7ffda34ea5e3b9b02eb942ae2addd Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 22:32:45 -0500
Subject: [PATCH 21/30] cli: rt pane list, peek, spawn, accounts, directories

---
 commands/__tests__/pane.test.ts             | 102 +++++++++++++++++++
 commands/pane.ts                            | 104 ++++++++++++++++++++
 lib/command-tree-def.ts                     |  51 ++++++++++
 lib/module-registry.ts                      |   1 +
 website/docs/reference/pane/accounts.mdx    |  26 +++++
 website/docs/reference/pane/directories.mdx |  27 +++++
 website/docs/reference/pane/index.mdx       |  28 ++++++
 website/docs/reference/pane/list.mdx        |  26 +++++
 website/docs/reference/pane/peek.mdx        |  28 ++++++
 website/docs/reference/pane/spawn.mdx       |  32 ++++++
 10 files changed, 425 insertions(+)
 create mode 100644 commands/__tests__/pane.test.ts
 create mode 100644 commands/pane.ts
 create mode 100644 website/docs/reference/pane/accounts.mdx
 create mode 100644 website/docs/reference/pane/directories.mdx
 create mode 100644 website/docs/reference/pane/index.mdx
 create mode 100644 website/docs/reference/pane/list.mdx
 create mode 100644 website/docs/reference/pane/peek.mdx
 create mode 100644 website/docs/reference/pane/spawn.mdx

diff --git a/commands/__tests__/pane.test.ts b/commands/__tests__/pane.test.ts
new file mode 100644
index 00000000..423095ec
--- /dev/null
+++ b/commands/__tests__/pane.test.ts
@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, expect, spyOn, test } from "bun:test";
+import { mkdirSync, mkdtempSync, realpathSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { paneAccounts, paneDirectories, paneList, panePeek, paneSpawn } from "../pane.ts";
+
+let home: string;
+let origHome: string | undefined;
+let server: ReturnType<typeof Bun.serve> | undefined;
+let seen: Array<{ cmd: string; payload: unknown }> = [];
+let replies: Record<string, unknown> = {};
+
+beforeEach(() => {
+  origHome = process.env.HOME;
+  home = realpathSync(mkdtempSync(join(tmpdir(), "rt-pane-cli-")));
+  process.env.HOME = home;
+  const sockDir = join(home, ".mattstack", "rt");
+  mkdirSync(sockDir, { recursive: true });
+  seen = [];
+  server = Bun.serve({
+    unix: join(sockDir, "rt.sock"),
+    async fetch(req) {
+      const cmd = new URL(req.url).pathname.slice(1);
+      const payload = req.method === "POST" ? await req.json() : {};
+      seen.push({ cmd, payload });
+      return Response.json(replies[cmd] ?? { ok: false, error: `unknown command: ${cmd}` });
+    },
+  });
+});
+
+afterEach(() => {
+  server?.stop(true);
+  process.env.HOME = origHome;
+});
+
+async function run(fn: (args: string[]) => Promise<void>, args: string[]) {
+  const out: string[] = [];
+  const err: string[] = [];
+  const logSpy = spyOn(console, "log").mockImplementation((...a: unknown[]) => { out.push(a.map(String).join(" ")); });
+  const errSpy = spyOn(console, "error").mockImplementation((...a: unknown[]) => { err.push(a.map(String).join(" ")); });
+  const exitSpy = spyOn(process, "exit").mockImplementation(() => { throw new Error("process.exit sentinel"); });
+  let code = 0;
+  try {
+    await fn(args);
+  } catch (e) {
+    if (e instanceof Error && e.message === "process.exit sentinel") code = (exitSpy.mock.calls.at(-1)?.[0] as number | undefined) ?? 1;
+    else throw e;
+  } finally {
+    logSpy.mockRestore(); errSpy.mockRestore(); exitSpy.mockRestore();
+  }
+  return { code, stdout: out.join("\n"), stderr: err.join("\n") };
+}
+
+const PANE = { paneId: "w1:p1", workspace: "assured", title: "Evaluate codegen", cwd: "/repos/assured", repo: "assured", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
+
+test("pane list --json prints the rows; plain prints one line per pane", async () => {
+  replies = { "pane:list": { ok: true, data: { panes: [PANE, { ...PANE, paneId: "w1:p2", presence: undefined, title: "fred" }] } } };
+  const json = await run(paneList, ["--json"]);
+  expect(JSON.parse(json.stdout)).toEqual({ ok: true, panes: replies["pane:list"]!["data"]["panes"] });
+  const plain = await run(paneList, []);
+  expect(plain.stdout).toContain("w1:p1");
+  expect(plain.stdout).toContain("meg");
+  expect(plain.stdout).toContain("not signed in");
+});
+
+test("pane list reports herdr unavailable and exits 1", async () => {
+  replies = { "pane:list": { ok: false, error: "herdr unavailable: no socket" } };
+  const r = await run(paneList, []);
+  expect(r.code).toBe(1);
+  expect(r.stderr).toContain("herdr unavailable");
+});
+
+test("pane peek passes the pane id and --lines", async () => {
+  replies = { "pane:peek": { ok: true, data: { paneId: "w1:p1", lines: ["a", "b"] } } };
+  const r = await run(panePeek, ["w1:p1", "--lines", "2"]);
+  expect(seen[0]).toEqual({ cmd: "pane:peek", payload: { paneId: "w1:p1", lines: 2 } });
+  expect(r.stdout).toBe("a\nb");
+});
+
+test("pane spawn passes every flag and prints the pane and readiness", async () => {
+  replies = { "pane:spawn": { ok: true, data: { pane: PANE, ready: true } } };
+  const r = await run(paneSpawn, ["--cwd", "/repos/assured", "--account", "Assured", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
+  expect(seen[0]!.payload).toEqual({ cwd: "/repos/assured", account: "Assured", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
+  expect(JSON.parse(r.stdout)).toMatchObject({ ok: true, ready: true, pane: { paneId: "w1:p1" } });
+});
+
+test("pane spawn requires --cwd", async () => {
+  const r = await run(paneSpawn, []);
+  expect(r.code).toBe(1);
+  expect(r.stderr).toContain("--cwd");
+});
+
+test("pane accounts and directories render", async () => {
+  replies = {
+    "pane:accounts": { ok: true, data: { accounts: [{ slot: 1, email: "a@b.c", alias: "A", headroom: "5h 3%" }] } },
+    "pane:directories": { ok: true, data: { directories: [{ path: "/repos/chat", repo: "chat" }] } },
+  };
+  expect((await run(paneAccounts, [])).stdout).toContain("A");
+  const d = await run(paneDirectories, ["--q", "chat"]);
+  expect(seen.at(-1)).toEqual({ cmd: "pane:directories", payload: { q: "chat" } });
+  expect(d.stdout).toContain("/repos/chat");
+});
diff --git a/commands/pane.ts b/commands/pane.ts
new file mode 100644
index 00000000..547aa0b8
--- /dev/null
+++ b/commands/pane.ts
@@ -0,0 +1,104 @@
+/**
+ * rt pane: herdr panes as rt sees them (joined to chat presence).
+ *
+ *   rt pane list [--json]                                         claude panes, presence joined
+ *   rt pane peek <pane> [--lines 8] [--json]                      the last lines of a pane's screen
+ *   rt pane spawn --cwd <path> [--account <a>] [--model <m>]
+ *                 [--effort <e>] [--prompt <text>] [--workspace <label>] [--json]
+ *   rt pane accounts [--json]                                     cswap accounts with headroom
+ *   rt pane directories [--q <text>] [--json]                     repos and worktrees for --cwd
+ *
+ * Every verb needs herdr; without it the daemon answers "herdr unavailable".
+ */
+import type { ChatPane, RtResponse } from "../packages/rt-client/src/index.ts";
+import { paneAccounts as paneAccountsRt, paneDirectories as paneDirectoriesRt, paneList as paneListRt, panePeek as panePeekRt, paneSpawn as paneSpawnRt } from "../packages/rt-client/src/index.ts";
+
+const FLAGS_WITH_VALUES = new Set(["--lines", "--cwd", "--account", "--model", "--effort", "--prompt", "--workspace", "--q", "--sock"]);
+
+function positional(args: string[]): string | undefined {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a.startsWith("--")) {
+      if (FLAGS_WITH_VALUES.has(a)) i++;
+      continue;
+    }
+    return a;
+  }
+  return undefined;
+}
+
+function flagValue(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+function fail(msg: string): never {
+  console.error(`rt pane: ${msg}`);
+  process.exit(1);
+}
+
+function unwrap<T>(res: RtResponse<T>, label: string): T {
+  if (!res.ok || res.data === undefined) fail(res.error ?? `${label} failed`);
+  return res.data;
+}
+
+function opts(args: string[]) {
+  const sockPath = flagValue(args, "--sock");
+  return sockPath ? { sockPath } : {};
+}
+
+function renderPane(p: ChatPane): string {
+  const who = p.presence ? `${p.presence.handle} (${p.presence.status})` : "not signed in";
+  const where = [p.repo, p.branch].filter(Boolean).join(" · ");
+  const title = p.title && p.title !== p.presence?.handle ? ` · ${p.title}` : "";
+  const rooms = p.presence?.rooms.length ? `  #${p.presence.rooms.join(" #")}` : "";
+  return `${p.paneId.padEnd(8)} ${p.agentStatus.padEnd(8)} ${who.padEnd(22)} ${p.workspace}${title}${where ? `  ${where}` : ""}${rooms}`;
+}
+
+export async function paneList(args: string[]): Promise<void> {
+  const data = unwrap(await paneListRt(opts(args)), "pane list");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, panes: data.panes }));
+  if (data.panes.length === 0) return void console.log("no claude panes");
+  console.log(data.panes.map(renderPane).join("\n"));
+}
+
+export async function panePeek(args: string[]): Promise<void> {
+  const paneId = positional(args);
+  if (!paneId) fail("usage: rt pane peek <pane> [--lines 8]");
+  const linesRaw = flagValue(args, "--lines");
+  let lines: number | undefined;
+  if (linesRaw !== undefined) {
+    lines = Number(linesRaw);
+    if (!Number.isInteger(lines) || lines <= 0) fail(`--lines must be a positive integer (got "${linesRaw}")`);
+  }
+  const data = unwrap(await panePeekRt({ paneId, lines }, opts(args)), "pane peek");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, ...data }));
+  console.log(data.lines.join("\n"));
+}
+
+export async function paneSpawn(args: string[]): Promise<void> {
+  const cwd = flagValue(args, "--cwd");
+  if (!cwd) fail("usage: rt pane spawn --cwd <path> [--account <a>] [--model <m>] [--effort <e>] [--prompt <text>] [--workspace <label>]");
+  const data = unwrap(
+    await paneSpawnRt(
+      { cwd, account: flagValue(args, "--account"), model: flagValue(args, "--model"), effort: flagValue(args, "--effort"), prompt: flagValue(args, "--prompt"), workspace: flagValue(args, "--workspace") },
+      opts(args),
+    ),
+    "pane spawn",
+  );
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, ...data }));
+  console.log(`${data.ready ? "ready" : "not ready"}  ${renderPane(data.pane)}`);
+}
+
+export async function paneAccounts(args: string[]): Promise<void> {
+  const data = unwrap(await paneAccountsRt(opts(args)), "pane accounts");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, accounts: data.accounts }));
+  if (data.accounts.length === 0) return void console.log("no cswap accounts");
+  console.log(data.accounts.map((a) => `${String(a.slot).padStart(2)}: ${a.alias ?? a.email}${a.alias ? `  ${a.email}` : ""}${a.headroom ? `  ${a.headroom}` : ""}`).join("\n"));
+}
+
+export async function paneDirectories(args: string[]): Promise<void> {
+  const data = unwrap(await paneDirectoriesRt({ q: flagValue(args, "--q") }, opts(args)), "pane directories");
+  if (args.includes("--json")) return void console.log(JSON.stringify({ ok: true, directories: data.directories }));
+  console.log(data.directories.map((d) => `${d.path}  ${d.repo}${d.branch ? ` · ${d.branch}` : ""}`).join("\n"));
+}
diff --git a/lib/command-tree-def.ts b/lib/command-tree-def.ts
index 33276138..ec0128f9 100644
--- a/lib/command-tree-def.ts
+++ b/lib/command-tree-def.ts
@@ -1048,6 +1048,57 @@ export const TREE: Record<string, CommandNode> = {
     },
   },
 
+  pane: {
+    description: "herdr panes as rt sees them: list with chat presence, peek, spawn claude, cswap accounts, directory suggestions",
+    subcommands: {
+      list: {
+        description: "Claude panes with their chat handle, status and rooms joined in (needs herdr)",
+        module: "./commands/pane.ts",
+        fn: "paneList",
+        args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON instead of one line per pane" }],
+      },
+      peek: {
+        description: "The last lines of a pane's visible screen",
+        module: "./commands/pane.ts",
+        fn: "panePeek",
+        args: [
+          { name: "Pane", type: "text", placeholder: "w7A:pY", hint: "herdr pane id" },
+          { name: "Lines", flag: "--lines", type: "text", optional: true, placeholder: "8", hint: "How many lines from the bottom" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+      spawn: {
+        description: "Open a herdr tab in a directory and start claude in it, optionally under a cswap account",
+        module: "./commands/pane.ts",
+        fn: "paneSpawn",
+        args: [
+          { name: "Directory", flag: "--cwd", type: "text", placeholder: "~/Documents/GitHub/chat", hint: "Absolute directory to start in" },
+          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Assured", hint: "cswap alias, email or slot" },
+          { name: "Model", flag: "--model", type: "text", optional: true, placeholder: "claude-fable-5", hint: "claude --model" },
+          { name: "Effort", flag: "--effort", type: "text", optional: true, placeholder: "high", hint: "claude --effort" },
+          { name: "Prompt", flag: "--prompt", type: "text", optional: true, placeholder: "read AGENTS.md", hint: "Typed once claude is idle" },
+          { name: "Workspace", flag: "--workspace", type: "text", optional: true, placeholder: "chat", hint: "herdr workspace label; default chat.herdrWorkspace" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+      accounts: {
+        description: "cswap accounts with rate-limit headroom, for spawn --account",
+        module: "./commands/pane.ts",
+        fn: "paneAccounts",
+        args: [{ name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" }],
+      },
+      directories: {
+        description: "Repos and worktrees rt knows, as suggestions for spawn --cwd",
+        module: "./commands/pane.ts",
+        fn: "paneDirectories",
+        args: [
+          { name: "Filter", flag: "--q", type: "text", optional: true, placeholder: "chat", hint: "Substring of the path" },
+          { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit JSON" },
+        ],
+      },
+    },
+  },
+
   repos: {
     description: "Register repos with rt (index + tracking)",
     subcommands: {
diff --git a/lib/module-registry.ts b/lib/module-registry.ts
index 7696b733..89a1fdfc 100644
--- a/lib/module-registry.ts
+++ b/lib/module-registry.ts
@@ -19,6 +19,7 @@ export const MODULE_REGISTRY: Record<string, () => Promise<any>> = {
   "./commands/extension.ts": () => import("../commands/extension.ts"),
   "./commands/home.ts": () => import("../commands/home.ts"),
   "./commands/hooks.ts": () => import("../commands/hooks.ts"),
+  "./commands/pane.ts": () => import("../commands/pane.ts"),
   "./commands/port.ts": () => import("../commands/port.ts"),
   "./commands/run.ts": () => import("../commands/run.ts"),
   "./commands/runs.ts": () => import("../commands/runs.ts"),
diff --git a/website/docs/reference/pane/accounts.mdx b/website/docs/reference/pane/accounts.mdx
new file mode 100644
index 00000000..12f87b39
--- /dev/null
+++ b/website/docs/reference/pane/accounts.mdx
@@ -0,0 +1,26 @@
+---
+title: rt pane accounts
+sidebar_label: accounts
+---
+
+# rt pane accounts
+
+`rt › pane › accounts`
+
+cswap accounts with rate-limit headroom, for spawn --account
+
+## Usage
+
+```bash
+rt pane accounts [flags]
+```
+
+## Arguments & flags
+
+| Flag / Arg | Type | Default | Description |
+| --- | --- | --- | --- |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit JSON |
+
+_See code: [commands/pane.ts › paneAccounts](https://github.com/m4ttstack/rt/blob/main/commands/pane.ts)_
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file
diff --git a/website/docs/reference/pane/directories.mdx b/website/docs/reference/pane/directories.mdx
new file mode 100644
index 00000000..42db81a0
--- /dev/null
+++ b/website/docs/reference/pane/directories.mdx
@@ -0,0 +1,27 @@
+---
+title: rt pane directories
+sidebar_label: directories
+---
+
+# rt pane directories
+
+`rt › pane › directories`
+
+Repos and worktrees rt knows, as suggestions for spawn --cwd
+
+## Usage
+
+```bash
+rt pane directories [flags]
+```
+
+## Arguments & flags
+
+| Flag / Arg | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--q` | text |  | Substring of the path |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit JSON |
+
+_See code: [commands/pane.ts › paneDirectories](https://github.com/m4ttstack/rt/blob/main/commands/pane.ts)_
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file
diff --git a/website/docs/reference/pane/index.mdx b/website/docs/reference/pane/index.mdx
new file mode 100644
index 00000000..56e2d7d3
--- /dev/null
+++ b/website/docs/reference/pane/index.mdx
@@ -0,0 +1,28 @@
+---
+title: rt pane
+sidebar_label: pane
+---
+
+# rt pane
+
+`rt › pane`
+
+herdr panes as rt sees them: list with chat presence, peek, spawn claude, cswap accounts, directory suggestions
+
+## Usage
+
+```bash
+rt pane
+```
+
+## Subcommands
+
+| Command | Description |
+| --- | --- |
+| [`list`](list) | Claude panes with their chat handle, status and rooms joined in (needs herdr) |
+| [`peek`](peek) | The last lines of a pane's visible screen |
+| [`spawn`](spawn) | Open a herdr tab in a directory and start claude in it, optionally under a cswap account |
+| [`accounts`](accounts) | cswap accounts with rate-limit headroom, for spawn --account |
+| [`directories`](directories) | Repos and worktrees rt knows, as suggestions for spawn --cwd |
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file
diff --git a/website/docs/reference/pane/list.mdx b/website/docs/reference/pane/list.mdx
new file mode 100644
index 00000000..00563526
--- /dev/null
+++ b/website/docs/reference/pane/list.mdx
@@ -0,0 +1,26 @@
+---
+title: rt pane list
+sidebar_label: list
+---
+
+# rt pane list
+
+`rt › pane › list`
+
+Claude panes with their chat handle, status and rooms joined in (needs herdr)
+
+## Usage
+
+```bash
+rt pane list [flags]
+```
+
+## Arguments & flags
+
+| Flag / Arg | Type | Default | Description |
+| --- | --- | --- | --- |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit JSON instead of one line per pane |
+
+_See code: [commands/pane.ts › paneList](https://github.com/m4ttstack/rt/blob/main/commands/pane.ts)_
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file
diff --git a/website/docs/reference/pane/peek.mdx b/website/docs/reference/pane/peek.mdx
new file mode 100644
index 00000000..996d7a98
--- /dev/null
+++ b/website/docs/reference/pane/peek.mdx
@@ -0,0 +1,28 @@
+---
+title: rt pane peek
+sidebar_label: peek
+---
+
+# rt pane peek
+
+`rt › pane › peek`
+
+The last lines of a pane's visible screen
+
+## Usage
+
+```bash
+rt pane peek <pane> [flags]
+```
+
+## Arguments & flags
+
+| Flag / Arg | Type | Default | Description |
+| --- | --- | --- | --- |
+| `<pane>` | text |  | herdr pane id |
+| `--lines` | text |  | How many lines from the bottom |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit JSON |
+
+_See code: [commands/pane.ts › panePeek](https://github.com/m4ttstack/rt/blob/main/commands/pane.ts)_
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file
diff --git a/website/docs/reference/pane/spawn.mdx b/website/docs/reference/pane/spawn.mdx
new file mode 100644
index 00000000..89efe99f
--- /dev/null
+++ b/website/docs/reference/pane/spawn.mdx
@@ -0,0 +1,32 @@
+---
+title: rt pane spawn
+sidebar_label: spawn
+---
+
+# rt pane spawn
+
+`rt › pane › spawn`
+
+Open a herdr tab in a directory and start claude in it, optionally under a cswap account
+
+## Usage
+
+```bash
+rt pane spawn [flags]
+```
+
+## Arguments & flags
+
+| Flag / Arg | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--cwd` | text |  | Absolute directory to start in |
+| `--account` | text |  | cswap alias, email or slot |
+| `--model` | text |  | claude --model |
+| `--effort` | text |  | claude --effort |
+| `--prompt` | text |  | Typed once claude is idle |
+| `--workspace` | text |  | herdr workspace label; default chat.herdrWorkspace |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit JSON |
+
+_See code: [commands/pane.ts › paneSpawn](https://github.com/m4ttstack/rt/blob/main/commands/pane.ts)_
+
+{/* generated by scripts/gen-docs.ts; edit prose in _partials, not here */}
\ No newline at end of file

From 4bcf8ae90c510912fc8738bae23cb57fb8226e06 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 22:47:30 -0500
Subject: [PATCH 22/30] cli: rt chat invite, rt chat read --last N

---
 commands/__tests__/chat.test.ts | 62 ++++++++++++++++++++++++++++++++
 commands/chat.ts                | 63 ++++++++++++++++++++++++++++++---
 lib/command-tree-def.ts         | 14 ++++----
 website/docs/reference/chat.mdx |  8 +++--
 4 files changed, 134 insertions(+), 13 deletions(-)

diff --git a/commands/__tests__/chat.test.ts b/commands/__tests__/chat.test.ts
index 8d2704da..280955c6 100644
--- a/commands/__tests__/chat.test.ts
+++ b/commands/__tests__/chat.test.ts
@@ -47,6 +47,13 @@ let server: ReturnType<typeof Bun.serve> | null = null;
 // Real child processes (spawnChat); reaped in afterEach so a stray tail can't
 // outlive its test.
 const children: Array<ReturnType<typeof Bun.spawn>> = [];
+// Scripted replies for a command, consulted before the real handlers — for
+// commands whose real handler has side effects a unit test must not trigger
+// (chat:invite would actually type into a herdr pane). Reset every test.
+let canned: Record<string, unknown> = {};
+// Every command this fake daemon dispatched, in order, for asserting exactly
+// what a verb sent the daemon.
+let seen: Array<{ cmd: string; payload: unknown }> = [];
 
 beforeEach(() => {
   origHome = process.env.HOME;
@@ -67,11 +74,15 @@ beforeEach(() => {
   const sockDir = join(home, ".mattstack", "rt");
   mkdirSync(sockDir, { recursive: true });
 
+  canned = {};
+  seen = [];
+
   server = Bun.serve({
     unix: join(sockDir, "rt.sock"),
     async fetch(req) {
       const cmd = new URL(req.url).pathname.slice(1);
       const payload = req.method === "POST" ? await req.json() : {};
+      seen.push({ cmd, payload });
       // The tail drives the events bus directly; the CLI-verb harness has no
       // real bus, so stub just enough for a spawned tail to arm and block.
       if (cmd === "events:head") return Response.json({ ok: true, data: { cursor: 0 } });
@@ -79,6 +90,7 @@ beforeEach(() => {
         await Bun.sleep(300); // empty long-poll round; the tail loops and stays alive
         return Response.json({ ok: true, data: { events: [], cursor: 0 } });
       }
+      if (cmd in canned) return Response.json(canned[cmd]);
       const handlers = createChatHandlers({ db: getStateDb(), emitEvent: () => 0 }) as unknown as Record<string, (p: unknown) => Promise<unknown>>;
       const handler = handlers[cmd];
       if (!handler) return Response.json({ ok: false, error: `unknown command: ${cmd}` });
@@ -1030,3 +1042,53 @@ describe("pidfile identity — only a real rt chat tail reads as live", () => {
     expect(__test__.looksLikeRtChatTail("vim tail-of-a-chat.log")).toBe(false);
   });
 });
+
+// ─── Task 9: `rt chat read --last N` and `rt chat invite <pane>` ───────────
+
+describe("rt chat CLI — read --last, invite", () => {
+  test("read --last N shows the newest N messages regardless of the cursor, then marks read", async () => {
+    await runChat(["join", "build", "--as", "alice"]);
+    await runChat(["post", "build", "seed one", "--as", "alice"]);
+    await runChat(["post", "build", "seed two", "--as", "alice"]);
+    await runChat(["join", "build", "--as", "bob"]);
+    const nothing = await runChat(["read", "build", "--as", "bob", "--json"]);
+    expect(JSON.parse(nothing).rooms[0]?.messages ?? []).toHaveLength(0);
+    const last = await runChat(["read", "build", "--last", "5", "--as", "bob", "--json"]);
+    expect(JSON.parse(last).rooms[0].messages.map((m: { body: string }) => m.body)).toEqual(["seed one", "seed two"]);
+    const again = await runChat(["read", "build", "--as", "bob", "--json"]);
+    expect(JSON.parse(again).rooms[0]?.messages ?? []).toHaveLength(0);
+  });
+
+  test("read --last refuses --since and a non-positive N", async () => {
+    await runChat(["join", "build", "--as", "alice"]);
+    expect((await runChatRaw(["read", "build", "--last", "5", "--since", "5m", "--as", "alice"])).code).toBe(1);
+    expect((await runChatRaw(["read", "build", "--last", "0", "--as", "alice"])).code).toBe(1);
+  });
+
+  test("read --last requires a room", async () => {
+    expect((await runChatRaw(["read", "--last", "5", "--as", "alice"])).code).toBe(1);
+  });
+
+  test("invite sends the pane, room, note, the human handle when not signed in, and the caller pane", async () => {
+    canned = { "chat:invite": { ok: true, data: { paneId: "w1:p1", delivered: "accepted" } } };
+    process.env.HERDR_PANE_ID = "w9:p9";
+    const out = await runChat(["invite", "w1:p1", "--room", "build", "--note", "take vite"]);
+    expect(out).toContain("accepted");
+    const sent = seen.find((s) => s.cmd === "chat:invite")!;
+    expect(sent.payload).toEqual({ paneId: "w1:p1", room: "build", note: "take vite", from: "matt", callerPane: "w9:p9" });
+  });
+
+  test("invite uses the session's own handle when signed in, and reports refusals with exit 0", async () => {
+    await runChat(["sign-in", "--as", "carol", "--session", "sess-c", "--no-room"]);
+    canned = { "chat:invite": { ok: true, data: { paneId: "w1:p1", delivered: "refused", reason: "at a prompt" } } };
+    const r = await runChatRaw(["invite", "w1:p1", "--room", "build", "--session", "sess-c"]);
+    expect(r.code).toBe(0);
+    expect(r.stdout).toContain("refused: at a prompt");
+    expect((seen.find((s) => s.cmd === "chat:invite")!.payload as { from: string }).from).toBe("carol");
+  });
+
+  test("invite requires a pane and --room", async () => {
+    expect((await runChatRaw(["invite"])).code).toBe(1);
+    expect((await runChatRaw(["invite", "w1:p1"])).code).toBe(1);
+  });
+});
diff --git a/commands/chat.ts b/commands/chat.ts
index 65fb68f0..aa759bd8 100644
--- a/commands/chat.ts
+++ b/commands/chat.ts
@@ -5,6 +5,7 @@
  *   rt chat leave <room>
  *   rt chat post <room> <<'EOF' ... EOF          the body on stdin; <text> for a one-liner
  *   rt chat read [room] [--limit 20] [--full] [--since <dur>]
+ *   rt chat read <room> --last <n>                 newest N regardless of cursor, then marks read
  *   rt chat rooms
  *   rt chat who [room]
  *   rt chat mark [room]
@@ -15,6 +16,7 @@
  *   rt chat buddies [--json]                       the roster; bare `who` aliases it
  *   rt chat dm <handle> <<'EOF' ... EOF           same body rules as post
  *   rt chat pulse [--json] [--session <id>]        hook-facing heartbeat; never fails
+ *   rt chat invite <pane> --room <room> [--note <text>]   types /chat:join into a herdr pane
  *
  * Identity resolution is CLIENT-SIDE (see resolveHandle): HERDR_PANE_ID and
  * the cwd's repo only exist in this process, never in the daemon, so the
@@ -57,9 +59,11 @@ import {
   chatBuddies,
   chatDisarm,
   chatDm,
+  chatInvite,
   chatJoin,
   chatLeave,
   chatMark,
+  chatMessages,
   chatPost,
   chatPulse,
   chatRead,
@@ -84,7 +88,7 @@ import type {
 
 // ─── arg parsing (commands/events.ts conventions) ────────────────────────────
 
-const FLAGS_WITH_VALUES = new Set(["--as", "--wake-on", "--limit", "--since", "--room", "--sock", "--session", "--status", "--file"]);
+const FLAGS_WITH_VALUES = new Set(["--as", "--wake-on", "--limit", "--since", "--room", "--sock", "--session", "--status", "--file", "--last", "--note"]);
 
 function positional(args: string[]): string | undefined {
   for (let i = 0; i < args.length; i++) {
@@ -117,6 +121,12 @@ function flagValue(args: string[], flag: string): string | undefined {
   return i >= 0 ? args[i + 1] : undefined;
 }
 
+/** `--sock` as RtClientOptions, or `{}` when unset. */
+function sockOpts(args: string[]): { sockPath?: string } {
+  const sockPath = flagValue(args, "--sock");
+  return sockPath ? { sockPath } : {};
+}
+
 function fail(msg: string): never {
   console.error(`rt chat: ${msg}`);
   process.exit(1);
@@ -733,6 +743,26 @@ async function runRead(args: string[]): Promise<void> {
     sinceMs = Date.now() - ms;
   }
 
+  const lastRaw = flagValue(args, "--last");
+  if (lastRaw !== undefined) {
+    if (sinceRaw !== undefined) fail("--last and --since are mutually exclusive");
+    if (!room) fail("--last needs a room");
+    const n = Number(lastRaw);
+    if (!Number.isInteger(n) || n <= 0) fail(`--last must be a positive integer (got "${lastRaw}")`);
+    // chat:messages orders newest-first, then reverses to oldest-first (same
+    // top-to-bottom order a plain read renders), so no reverse here.
+    const page = unwrap(await chatMessages({ room, limit: n }, sockOpts(args)), "read");
+    unwrap(await chatMark({ handle, room }, sockOpts(args)), "mark");
+    const rooms = [{ room, messages: page.messages }];
+    if (args.includes("--json")) {
+      console.log(JSON.stringify({ ok: true, rooms }));
+      return;
+    }
+    const headingFor = await dmHeadingsFor(handle);
+    console.log(renderReadRooms(rooms, args.includes("--full"), headingFor));
+    return;
+  }
+
   const res = await chatRead({ handle, room, limit, sinceMs });
   const data = unwrap(res, "read");
 
@@ -831,6 +861,30 @@ async function runDm(args: string[]): Promise<void> {
   // prints nothing on success — Global Constraint, same as post
 }
 
+/**
+ * `from` prefers the signed-in session's own handle over the human default:
+ * an agent inviting from a signed-in session should show up as itself, not
+ * as "matt", in the target pane's /chat:join note.
+ */
+async function runInvite(args: string[]): Promise<void> {
+  const paneId = positional(args);
+  if (!paneId) fail("usage: rt chat invite <pane> --room <room> [--note <text>]");
+  const room = flagValue(args, "--room");
+  if (!room) fail("--room is required");
+  requireValidName("room", room);
+  const note = flagValue(args, "--note");
+  const session = readChatSession(currentSessionId(args));
+  const from = session?.handle ?? getSetting<string>("chat.humanHandle").value;
+  const callerPane = process.env.HERDR_PANE_ID;
+  const res = await chatInvite({ paneId, room, note, from, callerPane }, sockOpts(args));
+  const data = unwrap(res, "invite");
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ok: true, ...data }));
+    return;
+  }
+  console.log(data.delivered === "refused" ? `${paneId}: refused: ${data.reason ?? "unknown"}` : `${paneId}: ${data.delivered}`);
+}
+
 // ─── sign-in / sign-out (presence) ───────────────────────────────────────────
 
 /**
@@ -1210,8 +1264,8 @@ export async function chatTail(args: string[]): Promise<void> {
   const roomFilter = flagValue(args, "--room");
   if (roomFilter) requireValidName("room", roomFilter);
 
-  const sockPath = flagValue(args, "--sock");
-  const opts = sockPath ? { sockPath } : {};
+  const opts = sockOpts(args);
+  const sockPath = opts.sockPath;
 
   // Claim the pidfile BEFORE any daemon call, so a live duplicate is refused
   // even when the daemon is down. A stale/foreign pidfile is reclaimed.
@@ -1351,7 +1405,7 @@ export async function chatTail(args: string[]): Promise<void> {
 // ─── dispatcher ────────────────────────────────────────────────────────────────
 
 const USAGE =
-  "usage: rt chat <join|leave|post|read|rooms|who|mark|tail|sign-in|sign-out|away|back|buddies|dm|pulse> ...";
+  "usage: rt chat <join|leave|post|read|rooms|who|mark|tail|sign-in|sign-out|away|back|buddies|dm|pulse|invite> ...";
 
 const VERBS: Record<string, (args: string[]) => Promise<void>> = {
   join: runJoin,
@@ -1369,6 +1423,7 @@ const VERBS: Record<string, (args: string[]) => Promise<void>> = {
   buddies: runBuddies,
   dm: runDm,
   pulse: runPulse,
+  invite: runInvite,
 };
 
 const VERB_HINTS: Record<string, string> = {
diff --git a/lib/command-tree-def.ts b/lib/command-tree-def.ts
index ec0128f9..af720c43 100644
--- a/lib/command-tree-def.ts
+++ b/lib/command-tree-def.ts
@@ -696,23 +696,25 @@ export const TREE: Record<string, CommandNode> = {
   },
 
   // Self-dispatching leaf: chat() routes its own verbs (join/leave/post/read/
-  // rooms/who/mark/tail/sign-in/sign-out/away/back/buddies/dm/pulse), so all
-  // args flow through rather than a subcommand map.
+  // rooms/who/mark/tail/sign-in/sign-out/away/back/buddies/dm/pulse/invite),
+  // so all args flow through rather than a subcommand map.
   chat: {
     description: "Group chat for agents and their human, over the rt daemon",
     module: "./commands/chat.ts",
     fn: "chat",
     omitBehavior: "picker",
     args: [
-      { name: "Verb", type: "text", placeholder: "join | leave | post | read | rooms | who | mark | tail | sign-in | sign-out | away | back | buddies | dm | pulse", hint: "The chat action to run" },
-      { name: "Room", type: "text", optional: true, placeholder: "build", hint: "Room name for join/leave/post/read/who/mark; the target handle for dm; omit on read/rooms/who to span everything, and on sign-in/sign-out/buddies/pulse/back/away, which take no room" },
+      { name: "Verb", type: "text", placeholder: "join | leave | post | read | rooms | who | mark | tail | sign-in | sign-out | away | back | buddies | dm | pulse | invite", hint: "The chat action to run" },
+      { name: "Room", type: "text", optional: true, placeholder: "build", hint: "Room name for join/leave/post/read/who/mark; the target handle for dm; the pane id for invite; omit on read/rooms/who to span everything, and on sign-in/sign-out/buddies/pulse/back/away, which take no room" },
       { name: "Text", type: "text", optional: true, placeholder: "@handle message", hint: "A one-line message body (every word after the room/handle) — post, dm; leave it out and feed the body on stdin (a heredoc) so paragraphs and lists survive; away takes this directly, with no room before it" },
       { name: "As handle", flag: "--as", type: "text", placeholder: "repo-tools-main", hint: "Override the derived handle for this invocation; refused while signed in (sign out first)" },
       { name: "Wake on", flag: "--wake-on", type: "text", placeholder: "mention | all | none", hint: "For join: when this handle's tail wakes (default mention)" },
       { name: "Limit", flag: "--limit", type: "text", placeholder: "20", hint: "For read: max messages (default 20)" },
       { name: "Since", flag: "--since", type: "text", placeholder: "5m", hint: "For read: a non-advancing peek at messages newer than this duration" },
+      { name: "Last", flag: "--last", type: "text", optional: true, placeholder: "10", hint: "read: the newest N messages regardless of your cursor, then mark read" },
       { name: "Full", flag: "--full", type: "boolean", default: false, hint: "For read: uncapped message bodies" },
-      { name: "Room filter", flag: "--room", type: "text", placeholder: "build", hint: "For tail: only emit wakes from this room; for sign-in: override the derived repository room" },
+      { name: "Room filter", flag: "--room", type: "text", placeholder: "build", hint: "For tail: only emit wakes from this room; for sign-in: override the derived repository room; for invite: the room to join the invited pane into" },
+      { name: "Note", flag: "--note", type: "text", optional: true, placeholder: "you own the vite side", hint: "invite: a one-line note appended to the /chat:join command" },
       { name: "Session", flag: "--session", type: "text", placeholder: "abc123", hint: "Session id override (default: CLAUDE_CODE_SESSION_ID); resolves position 0 handle for every verb, and is required by away/back/pulse" },
       { name: "Status", flag: "--status", type: "text", placeholder: "rebasing #67", hint: "For sign-in: an away/status message to set on the presence row" },
       { name: "No room", flag: "--no-room", type: "boolean", default: false, hint: "For sign-in: skip joining the derived repository room" },
@@ -720,7 +722,7 @@ export const TREE: Record<string, CommandNode> = {
       { name: "Body file", flag: "--file", type: "text", placeholder: "post.md", hint: "For post/dm: read the body from a file instead of stdin or the text" },
       { name: "As is", flag: "--as-is", type: "boolean", default: false, hint: "For post/dm: post a long single-line body anyway (500+ characters with no line break is refused by default)" },
       { name: "Quiet", flag: "--quiet", type: "boolean", default: false, hint: "For sign-out: suppress output (the SessionEnd hook's flag)" },
-      { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit machine-readable JSON instead of the plain rendering (join/leave/post/read/rooms/who/mark/buddies/dm/pulse/away/back/sign-in/sign-out)" },
+      { name: "JSON", flag: "--json", type: "boolean", default: false, hint: "Emit machine-readable JSON instead of the plain rendering (join/leave/post/read/rooms/who/mark/buddies/dm/pulse/away/back/sign-in/sign-out/invite)" },
     ],
   },
 
diff --git a/website/docs/reference/chat.mdx b/website/docs/reference/chat.mdx
index af3fac45..d87aa9cc 100644
--- a/website/docs/reference/chat.mdx
+++ b/website/docs/reference/chat.mdx
@@ -20,14 +20,16 @@ rt chat <verb> [<room>] [<text>] [flags]
 | Flag / Arg | Type | Default | Description |
 | --- | --- | --- | --- |
 | `<verb>` | text |  | The chat action to run |
-| `<room>` | text |  | Room name for join/leave/post/read/who/mark; the target handle for dm; omit on read/rooms/who to span everything, and on sign-in/sign-out/buddies/pulse/back/away, which take no room |
+| `<room>` | text |  | Room name for join/leave/post/read/who/mark; the target handle for dm; the pane id for invite; omit on read/rooms/who to span everything, and on sign-in/sign-out/buddies/pulse/back/away, which take no room |
 | `<text>` | text |  | A one-line message body (every word after the room/handle) — post, dm; leave it out and feed the body on stdin (a heredoc) so paragraphs and lists survive; away takes this directly, with no room before it |
 | `--as` | text |  | Override the derived handle for this invocation; refused while signed in (sign out first) |
 | `--wake-on` | text |  | For join: when this handle's tail wakes (default mention) |
 | `--limit` | text |  | For read: max messages (default 20) |
 | `--since` | text |  | For read: a non-advancing peek at messages newer than this duration |
+| `--last` | text |  | read: the newest N messages regardless of your cursor, then mark read |
 | `--full` | boolean | `false` | For read: uncapped message bodies |
-| `--room` | text |  | For tail: only emit wakes from this room; for sign-in: override the derived repository room |
+| `--room` | text |  | For tail: only emit wakes from this room; for sign-in: override the derived repository room; for invite: the room to join the invited pane into |
+| `--note` | text |  | invite: a one-line note appended to the /chat:join command |
 | `--session` | text |  | Session id override (default: CLAUDE_CODE_SESSION_ID); resolves position 0 handle for every verb, and is required by away/back/pulse |
 | `--status` | text |  | For sign-in: an away/status message to set on the presence row |
 | `--no-room` | boolean | `false` | For sign-in: skip joining the derived repository room |
@@ -35,7 +37,7 @@ rt chat <verb> [<room>] [<text>] [flags]
 | `--file` | text |  | For post/dm: read the body from a file instead of stdin or the text |
 | `--as-is` | boolean | `false` | For post/dm: post a long single-line body anyway (500+ characters with no line break is refused by default) |
 | `--quiet` | boolean | `false` | For sign-out: suppress output (the SessionEnd hook's flag) |
-| [`--json`](/guides/common-flags) | boolean | `false` | Emit machine-readable JSON instead of the plain rendering (join/leave/post/read/rooms/who/mark/buddies/dm/pulse/away/back/sign-in/sign-out) |
+| [`--json`](/guides/common-flags) | boolean | `false` | Emit machine-readable JSON instead of the plain rendering (join/leave/post/read/rooms/who/mark/buddies/dm/pulse/away/back/sign-in/sign-out/invite) |
 
 _See code: [commands/chat.ts › chat](https://github.com/m4ttstack/rt/blob/main/commands/chat.ts)_
 

From 9f3e16ca51370728bb76ee0931f4ed51518f93ed Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 22:48:18 -0500
Subject: [PATCH 23/30] chat: drop em dashes from task 9 comments and describe
 block

---
 commands/__tests__/chat.test.ts | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/commands/__tests__/chat.test.ts b/commands/__tests__/chat.test.ts
index 280955c6..a1449380 100644
--- a/commands/__tests__/chat.test.ts
+++ b/commands/__tests__/chat.test.ts
@@ -47,9 +47,9 @@ let server: ReturnType<typeof Bun.serve> | null = null;
 // Real child processes (spawnChat); reaped in afterEach so a stray tail can't
 // outlive its test.
 const children: Array<ReturnType<typeof Bun.spawn>> = [];
-// Scripted replies for a command, consulted before the real handlers — for
-// commands whose real handler has side effects a unit test must not trigger
-// (chat:invite would actually type into a herdr pane). Reset every test.
+// Scripted replies for a command, consulted before the real handlers (for
+// commands whose real handler has side effects a unit test must not trigger:
+// chat:invite would actually type into a herdr pane). Reset every test.
 let canned: Record<string, unknown> = {};
 // Every command this fake daemon dispatched, in order, for asserting exactly
 // what a verb sent the daemon.
@@ -1045,7 +1045,7 @@ describe("pidfile identity — only a real rt chat tail reads as live", () => {
 
 // ─── Task 9: `rt chat read --last N` and `rt chat invite <pane>` ───────────
 
-describe("rt chat CLI — read --last, invite", () => {
+describe("rt chat CLI: read --last, invite", () => {
   test("read --last N shows the newest N messages regardless of the cursor, then marks read", async () => {
     await runChat(["join", "build", "--as", "alice"]);
     await runChat(["post", "build", "seed one", "--as", "alice"]);

From 796bd9aac02d93d5280ac89a72df224d3bf04e51 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 23:13:04 -0500
Subject: [PATCH 24/30] rt-chat skill: read --last, rt chat invite, the rt pane
 group, recruiting flow

---
 skills/rt-chat/SKILL.md | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/skills/rt-chat/SKILL.md b/skills/rt-chat/SKILL.md
index c253fcb0..4ea76264 100644
--- a/skills/rt-chat/SKILL.md
+++ b/skills/rt-chat/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: rt:chat
-description: Use when asked to join or coordinate in an agent chat room, when told you are working alongside other agents, or when you need to reach an agent under a different account.
+description: Use when asked to join or coordinate in an agent chat room, when told you are working alongside other agents, or when you need to reach an agent under a different account, or when asked to put you and another agent into a room together (recruiting through herdr).
 ---
 
 # rt chat (agent coordination)
@@ -119,6 +119,10 @@ that the Monitor task finished (not a chat message — the task exiting). Then:
   not, and does **not** move your read cursor. It is also the way back to
   a message you have already consumed (`--since 2h --full` when a tail
   line truncated it).
+- `rt chat read <room> --last N` shows the newest N messages of a room
+  regardless of your cursor, then marks the room read. Joining puts your
+  cursor at the room's newest message, so this is how you read a room you
+  were just invited to, or catch up on one you were pointed at.
 - `rt chat mark [room]` advances the cursor without printing anything — use
   it if you want to acknowledge messages you've already seen some other way
   (e.g. in the tail's wake lines) without re-reading their bodies.
@@ -140,10 +144,15 @@ that the Monitor task finished (not a chat message — the task exiting). Then:
 | `rt chat join <room> [--wake-on mention\|all\|none]` | join an additional room; creates it if it doesn't exist. No `--as`: your handle comes from the session file |
 | `rt chat leave <room>` | drop membership; kills your tail only if this was your last room |
 | `rt chat post <room> [<text>]` | post a message: the body on stdin from a heredoc, or one line of text — see Posting a message below. Parses `@mentions` and emits wake events; prints only the message link |
+| `rt chat invite <pane> --room <room> [--note <text>]` | type `/chat:join <room>` into one herdr pane, so that agent joins itself; needs herdr. Reports `accepted` \| `queued` \| `refused`; never changes membership. The note is attributed to you |
 | `rt chat rooms` | rooms you're in, member counts, unread, last activity |
 | `rt chat mark [room]` | advance cursor without printing |
 | `rt chat tail` | the streaming wake feed; resolves your handle from the session file once signed in; always run under `Monitor` as above, never bare in Bash |
 
+`rt pane list`, `rt pane peek <pane>`, `rt pane spawn --cwd <path> [...]`,
+`rt pane accounts` and `rt pane directories` are the herdr-facing verbs that
+back this; `rt pane list --json` is how you find another agent's pane.
+
 `@mentions` are how you wake a specific agent: mentioning `@handle` in a
 `post` wakes that handle's armed tail whenever they're in `mention` (the
 default) or `all` mode. `@here` wakes every member in the room except those in
@@ -237,6 +246,34 @@ your line carries only the gist. The link opens the chat viewer
 a heredoc body renders as paragraphs and lists and a one-line body renders
 as one paragraph; that is why the posting form above matters.
 
+## Recruiting another agent
+
+When Matt says "add you and the agent working on foo into a room so you can
+coordinate" (or anything that means: put me and another pane in a room),
+this is the flow. It needs herdr; every step that touches another pane is
+gated on a form.
+
+1. `rt pane list --json`. If it errors with `herdr unavailable`, say this
+   needs herdr and stop.
+2. Match *foo* against each pane's `title`, `repo`, `branch`, `cwd` and
+   `presence.handle`. Exclude your own pane (`HERDR_PANE_ID`) and panes
+   whose `presence.rooms` already includes the target room.
+3. **Always a form.** One `AskUserQuestion` with up to three questions:
+   the candidate panes as options (`title · repo · agentStatus`;
+   `multiSelect: true`; the four best matches as options, the rest listed
+   by pane id and title in the question text, and `Other` accepting a
+   pane id), the proposed room name (a slug from the topic; `Other` to
+   rename), and the seed draft (post as drafted, or rewrite). Touch no pane
+   before the form returns.
+4. Sign in only if you are not already (`rt chat sign-in`, which keeps the
+   repository room), then `rt chat join <room>`. Never `sign-in --room`
+   here: it replaces the derived room and rewrites your session file.
+   Post the seed as yourself with a heredoc. Then, per chosen pane,
+   sequentially: `rt chat invite <pane> --room <room> [--note "<text>"]`.
+5. Report one line per pane (`accepted`, `queued (working)`,
+   `refused: at a prompt`) plus the room link. A refused pane is reported,
+   never retried blind; Matt answers its prompt and asks again.
+
 ## Announce before you take something
 
 The system deliberately does not enforce this in code, so it's a convention

From 5db72adff1bcd6ee31e840c7f2ba28de9f768dcb Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 23:23:02 -0500
Subject: [PATCH 25/30] rt-client: 0.6.2, pane and invite wrappers

---
 packages/rt-client/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/rt-client/package.json b/packages/rt-client/package.json
index b5dfb8ec..5558d171 100644
--- a/packages/rt-client/package.json
+++ b/packages/rt-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@mattstack/rt-client",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "type": "module",
   "exports": {
     ".": {

From 3a68b248827fde5372388d32b3573d6bebb20e74 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Wed, 26 Aug 2026 23:30:48 -0500
Subject: [PATCH 26/30] repo-for-cwd: drop em dashes from the moved doc
 comments

---
 lib/repo-for-cwd.ts | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/repo-for-cwd.ts b/lib/repo-for-cwd.ts
index a6ea8930..52f07bea 100644
--- a/lib/repo-for-cwd.ts
+++ b/lib/repo-for-cwd.ts
@@ -20,7 +20,7 @@ export function safeRealpath(p: string): string {
   }
 }
 
-/** Nearest ancestor directory holding a `.git` entry — a plain walk, never a git spawn. */
+/** Nearest ancestor directory holding a `.git` entry (a plain walk, never a git spawn). */
 export function findGitRoot(start: string): string | null {
   let dir = start;
   while (true) {
@@ -33,11 +33,11 @@ export function findGitRoot(start: string): string | null {
 
 /**
  * The MAIN worktree path for `worktreeRoot`: itself when `.git` is a real
- * directory, or — for a linked worktree — the repo its `.git` FILE's
+ * directory, or (for a linked worktree) the repo its `.git` FILE's
  * `gitdir: <main>/.git/worktrees/<slot>` pointer names, parsed by hand
  * (never `git worktree list`). Null when the pointer is stale or foreign
  * (a worktree whose gitdir survived a home-directory move errors with
- * "fatal: not a git repository" under real git) — this is why the
+ * "fatal: not a git repository" under real git). This is why the
  * resolution order has a position AFTER the repo-name rung: dropping
  * straight to `<user>-<host>` here would give one shared handle to every
  * broken directory on the machine.
@@ -73,8 +73,8 @@ export function resolveMainWorktreePath(worktreeRoot: string): string | null {
  * Reverse lookup: which repos.json alias names `mainWorktreePath`. Index is an
  * explicit param so the derivation stays testable without a real HOME
  * (carry-forward fixture test). Index keys are serialized identities after the
- * RT-62 re-key (`remote:host%2Fpath`) — a wire form whose `%` and `:` the
- * handle charset forbids — so the alias is the key's display label, never the
+ * RT-62 re-key (`remote:host%2Fpath`), a wire form whose `%` and `:` the
+ * handle charset forbids, so the alias is the key's display label, never the
  * key itself (repoLabel passes a legacy name-keyed row through unchanged).
  */
 export function repoAliasForPath(mainWorktreePath: string, index: Record<string, string>): string | null {

From e3b2565cad4ca67e9415c0cb6be782385f21be9c Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Thu, 27 Aug 2026 09:16:20 -0500
Subject: [PATCH 27/30] ci: pass tsc --noEmit and repo-purity

Type the pane list --json assertion through a typed local instead of
indexing an unknown value (tsc --noEmit TS7053).

Replace employer references with neutral placeholders (assured to acme,
the work email to alex@acme.test) across the pane/cswap tests, the
command tree, the spec and the plans; regenerate the reference docs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 commands/__tests__/pane.test.ts               | 11 +++--
 .../plans/2026-08-26-rt-chat-invite-1-rt.md   | 20 ++++----
 .../2026-08-26-rt-chat-invite-2-viewer.md     | 46 +++++++++----------
 .../specs/2026-08-26-rt-chat-invite-design.md |  2 +-
 lib/__tests__/cswap.test.ts                   |  4 +-
 lib/command-tree-def.ts                       |  2 +-
 lib/daemon/__tests__/pane-handlers.test.ts    |  8 ++--
 7 files changed, 47 insertions(+), 46 deletions(-)

diff --git a/commands/__tests__/pane.test.ts b/commands/__tests__/pane.test.ts
index 423095ec..d5702df8 100644
--- a/commands/__tests__/pane.test.ts
+++ b/commands/__tests__/pane.test.ts
@@ -51,12 +51,13 @@ async function run(fn: (args: string[]) => Promise<void>, args: string[]) {
   return { code, stdout: out.join("\n"), stderr: err.join("\n") };
 }
 
-const PANE = { paneId: "w1:p1", workspace: "assured", title: "Evaluate codegen", cwd: "/repos/assured", repo: "assured", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
+const PANE = { paneId: "w1:p1", workspace: "acme", title: "Evaluate codegen", cwd: "/repos/acme", repo: "acme", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
 
 test("pane list --json prints the rows; plain prints one line per pane", async () => {
-  replies = { "pane:list": { ok: true, data: { panes: [PANE, { ...PANE, paneId: "w1:p2", presence: undefined, title: "fred" }] } } };
+  const panes = [PANE, { ...PANE, paneId: "w1:p2", presence: undefined, title: "fred" }];
+  replies = { "pane:list": { ok: true, data: { panes } } };
   const json = await run(paneList, ["--json"]);
-  expect(JSON.parse(json.stdout)).toEqual({ ok: true, panes: replies["pane:list"]!["data"]["panes"] });
+  expect(JSON.parse(json.stdout)).toEqual({ ok: true, panes });
   const plain = await run(paneList, []);
   expect(plain.stdout).toContain("w1:p1");
   expect(plain.stdout).toContain("meg");
@@ -79,8 +80,8 @@ test("pane peek passes the pane id and --lines", async () => {
 
 test("pane spawn passes every flag and prints the pane and readiness", async () => {
   replies = { "pane:spawn": { ok: true, data: { pane: PANE, ready: true } } };
-  const r = await run(paneSpawn, ["--cwd", "/repos/assured", "--account", "Assured", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
-  expect(seen[0]!.payload).toEqual({ cwd: "/repos/assured", account: "Assured", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
+  const r = await run(paneSpawn, ["--cwd", "/repos/acme", "--account", "Acme", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
+  expect(seen[0]!.payload).toEqual({ cwd: "/repos/acme", account: "Acme", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
   expect(JSON.parse(r.stdout)).toMatchObject({ ok: true, ready: true, pane: { paneId: "w1:p1" } });
 });
 
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
index cddef14e..bcb6beb6 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-1-rt.md
@@ -521,12 +521,12 @@ const SNAPSHOT = {
   snapshot: {
     version: "0.8.0",
     protocol: 19,
-    workspaces: [{ workspace_id: "w1", label: "assured", focused: false }],
+    workspaces: [{ workspace_id: "w1", label: "acme", focused: false }],
     tabs: [],
     layouts: [],
     agents: [],
     panes: [
-      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/assured", foreground_cwd: "/tmp/assured", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
+      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/acme", foreground_cwd: "/tmp/acme", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
       { pane_id: "w1:p2", terminal_id: "t2", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "working", cwd: "/tmp/other", terminal_title_stripped: "fred", revision: 1 },
       { pane_id: "w1:p3", terminal_id: "t3", workspace_id: "w1", tab_id: "w1:t2", focused: false, agent_status: "unknown", cwd: "/tmp", revision: 1 },
     ],
@@ -546,7 +546,7 @@ function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string,
 
 test("pane:list lists only claude panes, joined to presence by session id, with rooms", async () => {
   const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
-  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/assured", repo: "assured", branch: "main", pane: "w1:p1" });
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/acme", repo: "acme", branch: "main", pane: "w1:p1" });
   if (!signed.ok) throw new Error(signed.error);
   await chat["chat:join"]({ room: "build", handle: signed.data.handle });
 
@@ -555,7 +555,7 @@ test("pane:list lists only claude panes, joined to presence by session id, with
   if (!res.ok) throw new Error("unreachable");
   expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p1", "w1:p2"]);
   const first = res.data.panes[0]!;
-  expect(first).toMatchObject({ workspace: "assured", title: "Evaluate codegen", cwd: "/tmp/assured", repo: "assured", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
+  expect(first).toMatchObject({ workspace: "acme", title: "Evaluate codegen", cwd: "/tmp/acme", repo: "acme", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
   expect(first.presence).toMatchObject({ handle: "meg", rooms: ["build"] });
   expect(first.presence!.status).not.toBe("offline");
 });
@@ -834,7 +834,7 @@ import { listCswapAccounts, parseCswapList } from "../cswap.ts";
 const CAPTURED = `
 A newer version of claude-swap is available (0.25.0). You are using 0.23.0. Run \`cswap upgrade\` to update.
 Accounts:
-  1: matthew.goodwin@assured.claims [Assured] (history: shared)
+  1: alex@acme.test [Acme] (history: shared)
      ├ $$:    100%   $400.07 / $400.00
      ├ 5h:      0%
      ├ 7d:     40%   resets Aug 30 20:00  in 4d 0h
@@ -845,7 +845,7 @@ Accounts:
 
 test("parses slots, emails, aliases and a compact headroom summary", () => {
   expect(parseCswapList(CAPTURED)).toEqual([
-    { slot: 1, email: "matthew.goodwin@assured.claims", alias: "Assured", headroom: "5h 0% · 7d 40% · Fable 35%" },
+    { slot: 1, email: "alex@acme.test", alias: "Acme", headroom: "5h 0% · 7d 40% · Fable 35%" },
     { slot: 2, email: "someone@example.com", headroom: "5h 12%" },
   ]);
 });
@@ -1636,7 +1636,7 @@ async function run(fn: (args: string[]) => Promise<void>, args: string[]) {
   return { code, stdout: out.join("\n"), stderr: err.join("\n") };
 }
 
-const PANE = { paneId: "w1:p1", workspace: "assured", title: "Evaluate codegen", cwd: "/repos/assured", repo: "assured", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
+const PANE = { paneId: "w1:p1", workspace: "acme", title: "Evaluate codegen", cwd: "/repos/acme", repo: "acme", branch: "main", agentStatus: "idle", presence: { handle: "meg", status: "live", rooms: ["build"] } };
 
 test("pane list --json prints the rows; plain prints one line per pane", async () => {
   replies = { "pane:list": { ok: true, data: { panes: [PANE, { ...PANE, paneId: "w1:p2", presence: undefined, title: "fred" }] } } };
@@ -1664,8 +1664,8 @@ test("pane peek passes the pane id and --lines", async () => {
 
 test("pane spawn passes every flag and prints the pane and readiness", async () => {
   replies = { "pane:spawn": { ok: true, data: { pane: PANE, ready: true } } };
-  const r = await run(paneSpawn, ["--cwd", "/repos/assured", "--account", "Assured", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
-  expect(seen[0]!.payload).toEqual({ cwd: "/repos/assured", account: "Assured", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
+  const r = await run(paneSpawn, ["--cwd", "/repos/acme", "--account", "Acme", "--model", "claude-fable-5", "--effort", "high", "--workspace", "chat", "--prompt", "read AGENTS.md", "--json"]);
+  expect(seen[0]!.payload).toEqual({ cwd: "/repos/acme", account: "Acme", model: "claude-fable-5", effort: "high", workspace: "chat", prompt: "read AGENTS.md" });
   expect(JSON.parse(r.stdout)).toMatchObject({ ok: true, ready: true, pane: { paneId: "w1:p1" } });
 });
 
@@ -1833,7 +1833,7 @@ In `lib/command-tree-def.ts`, add beside `secrets`:
         fn: "paneSpawn",
         args: [
           { name: "Directory", flag: "--cwd", type: "text", placeholder: "~/Documents/GitHub/chat", hint: "Absolute directory to start in" },
-          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Assured", hint: "cswap alias, email or slot" },
+          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Acme", hint: "cswap alias, email or slot" },
           { name: "Model", flag: "--model", type: "text", optional: true, placeholder: "claude-fable-5", hint: "claude --model" },
           { name: "Effort", flag: "--effort", type: "text", optional: true, placeholder: "high", hint: "claude --effort" },
           { name: "Prompt", flag: "--prompt", type: "text", optional: true, placeholder: "read AGENTS.md", hint: "Typed once claude is idle" },
diff --git a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
index 561d40a1..6714f2f5 100644
--- a/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
+++ b/docs/superpowers/plans/2026-08-26-rt-chat-invite-2-viewer.md
@@ -102,9 +102,9 @@ test('invite fixtures answer per pane: a working pane queues, a blocked one refu
 });
 
 test('directories filter by substring; accounts carry headroom; spawn returns a ready pane', () => {
-  expect(fixtureDirectories('assured').every(d => d.path.includes('assured'))).toBe(true);
-  expect(fixtureDirectories().length).toBeGreaterThan(fixtureDirectories('assured').length);
-  expect(fixtureAccounts()[0]).toMatchObject({ slot: 1, alias: 'Assured' });
+  expect(fixtureDirectories('acme').every(d => d.path.includes('acme'))).toBe(true);
+  expect(fixtureDirectories().length).toBeGreaterThan(fixtureDirectories('acme').length);
+  expect(fixtureAccounts()[0]).toMatchObject({ slot: 1, alias: 'Acme' });
   expect(fixtureSpawn('/Users/matt/Documents/GitHub/chat')).toMatchObject({ ready: true, pane: { cwd: '/Users/matt/Documents/GitHub/chat', agentStatus: 'idle' } });
 });
 ```
@@ -127,7 +127,7 @@ export function fixturePanes(): ChatPane[] {
     { paneId: 'w3f:p4', workspace: 'chat', title: 'meg', cwd: '/Users/matt/Documents/GitHub/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-meg', presence: { handle: 'meg', status: 'live', rooms: ['build', 'chat'] } },
     { paneId: 'w9c:p3', workspace: 'gitq', title: 'june', cwd: '/Users/matt/Documents/GitHub/gitq', repo: 'gitq', branch: 'main', agentStatus: 'blocked', sessionId: 'fixture-june', presence: { handle: 'june', status: 'idle', rooms: ['gitq'] } },
     { paneId: 'w2d:p1', workspace: 'deck', title: 'otis', cwd: '/Users/matt/Documents/GitHub/deck', repo: 'deck', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-otis', presence: { handle: 'otis', status: 'deaf', rooms: ['deck'] } },
-    { paneId: 'w7A:pY', workspace: 'assured', title: 'Evaluate house codegen plugin for bundle optimization', cwd: '/Users/matt/Documents/GitHub/assured', repo: 'assured', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-assured' },
+    { paneId: 'w7A:pY', workspace: 'acme', title: 'Evaluate house codegen plugin for bundle optimization', cwd: '/Users/matt/Documents/GitHub/acme', repo: 'acme', branch: 'main', agentStatus: 'idle', sessionId: 'fixture-acme' },
     { paneId: 'wB1:p1', workspace: 'mr-board', title: 'Fix invite onboarding modal focus trap', cwd: '/Users/matt/Documents/GitHub/mr-board-wt-invite-onboarding', repo: 'mr-board', branch: 'invite-onboarding', agentStatus: 'working', sessionId: 'fixture-mrboard' },
   ];
 }
@@ -140,13 +140,13 @@ export function fixturePeek(paneId: string): string[] {
 }
 
 export function fixtureAccounts(): PaneAccount[] {
-  return [{ slot: 1, email: 'matthew.goodwin@assured.claims', alias: 'Assured', headroom: '5h 0% · 7d 40% · Fable 35%' }];
+  return [{ slot: 1, email: 'alex@acme.test', alias: 'Acme', headroom: '5h 0% · 7d 40% · Fable 35%' }];
 }
 
 export function fixtureDirectories(q?: string): PaneDirectory[] {
   const all: PaneDirectory[] = [
-    { path: '/Users/matt/Documents/GitHub/assured', repo: 'assured', branch: 'main' },
-    { path: '/Users/matt/Documents/GitHub/assured-wt-codegen-split', repo: 'assured', branch: 'perf/codegen-split' },
+    { path: '/Users/matt/Documents/GitHub/acme', repo: 'acme', branch: 'main' },
+    { path: '/Users/matt/Documents/GitHub/acme-wt-codegen-split', repo: 'acme', branch: 'perf/codegen-split' },
     { path: '/Users/matt/Documents/GitHub/repo-tools', repo: 'repo-tools', branch: 'main' },
     { path: '/Users/matt/Documents/GitHub/chat', repo: 'chat', branch: 'main' },
   ];
@@ -271,10 +271,10 @@ test('POST /api/panes spawns with every field and answers pane plus ready', asyn
   vi.mocked(rt.paneSpawn).mockResolvedValueOnce({ ok: true, data: { pane: PANE, ready: true } });
   const res = await app.request('/api/panes', {
     method: 'POST',
-    body: JSON.stringify({ cwd: '/repos/chat', account: 'Assured', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }),
+    body: JSON.stringify({ cwd: '/repos/chat', account: 'Acme', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }),
   });
   expect(res.status).toBe(200);
-  expect(rt.paneSpawn).toHaveBeenCalledWith({ cwd: '/repos/chat', account: 'Assured', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }, expect.anything());
+  expect(rt.paneSpawn).toHaveBeenCalledWith({ cwd: '/repos/chat', account: 'Acme', model: 'claude-fable-5', effort: 'high', prompt: 'hi', workspace: 'chat' }, expect.anything());
   expect(await res.json()).toEqual({ pane: PANE, ready: true });
 });
 
@@ -698,7 +698,7 @@ const PANES: ChatPane[] = [
   { paneId: 'w1:p1', workspace: 'repo-tools', title: 'fred', cwd: '/r/repo-tools', repo: 'repo-tools', branch: 'main', agentStatus: 'working', presence: { handle: 'fred', status: 'live', rooms: ['repo-tools'] } },
   { paneId: 'w1:p2', workspace: 'chat', title: 'meg', cwd: '/r/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', presence: { handle: 'meg', status: 'live', rooms: ['build'] } },
   { paneId: 'w1:p3', workspace: 'gitq', title: 'june', cwd: '/r/gitq', repo: 'gitq', branch: 'main', agentStatus: 'blocked', presence: { handle: 'june', status: 'idle', rooms: [] } },
-  { paneId: 'w1:p4', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', repo: 'assured', branch: 'main', agentStatus: 'idle' },
+  { paneId: 'w1:p4', workspace: 'acme', title: 'Evaluate codegen', cwd: '/r/acme', repo: 'acme', branch: 'main', agentStatus: 'idle' },
 ];
 
 function json(body: unknown, status = 200) {
@@ -746,7 +746,7 @@ test('lists claude panes sorted listening, idle, deaf, not signed in, with handl
   expect(rows.map(r => r.getAttribute('data-testid'))).toEqual(['pane-row-w1:p1', 'pane-row-w1:p2', 'pane-row-w1:p3', 'pane-row-w1:p4']);
   expect(within(rows[0]!).getByText('fred')).toBeInTheDocument();
   expect(within(rows[3]!).getByText('not signed in')).toBeInTheDocument();
-  expect(within(rows[3]!).getByText('…/assured')).toBeInTheDocument();
+  expect(within(rows[3]!).getByText('…/acme')).toBeInTheDocument();
 });
 
 test('the filter matches handle, workspace, title, repo and path', async () => {
@@ -811,8 +811,8 @@ test('new pane is hidden without allowCreate and present with it; the form posts
   let release: (r: Response) => void = () => {};
   route({
     'GET /api/panes': () => json({ available: true, panes: PANES }),
-    'GET /api/panes/accounts': () => json({ accounts: [{ slot: 1, email: 'a@b.c', alias: 'Assured', headroom: '5h 0%' }] }),
-    'GET /api/panes/directories': () => json({ directories: [{ path: '/r/assured-wt', repo: 'assured', branch: 'perf' }] }),
+    'GET /api/panes/accounts': () => json({ accounts: [{ slot: 1, email: 'a@b.c', alias: 'Acme', headroom: '5h 0%' }] }),
+    'GET /api/panes/directories': () => json({ directories: [{ path: '/r/acme-wt', repo: 'acme', branch: 'perf' }] }),
     'POST /api/panes': () => new Promise<Response>(r => (release = r)),
   });
   mount();
@@ -824,18 +824,18 @@ test('new pane is hidden without allowCreate and present with it; the form posts
   const results = mount({ allowCreate: true });
   await userEvent.click(screen.getAllByText('open')[1]!);
   await userEvent.click(await screen.findByTestId('pane-new'));
-  await userEvent.type(screen.getByLabelText('Directory'), '/r/assured-wt');
+  await userEvent.type(screen.getByLabelText('Directory'), '/r/acme-wt');
   await userEvent.click(screen.getByTestId('pane-start'));
   expect(await screen.findByText(/starting/)).toBeInTheDocument();
   const body = JSON.parse(String(fetchMock.mock.calls.find(([, i]) => (i as RequestInit)?.method === 'POST')![1]!.body));
-  expect(body).toMatchObject({ cwd: '/r/assured-wt', account: 'Assured' });
+  expect(body).toMatchObject({ cwd: '/r/acme-wt', account: 'Acme' });
   await act(async () => {
-    release(json({ pane: { paneId: 'w9:p1', workspace: 'chat', cwd: '/r/assured-wt', agentStatus: 'idle' }, ready: true }));
+    release(json({ pane: { paneId: 'w9:p1', workspace: 'chat', cwd: '/r/acme-wt', agentStatus: 'idle' }, ready: true }));
   });
   const row = await screen.findByTestId('pane-row-w9:p1');
   expect(within(row).getByTestId('pane-check-w9:p1')).toHaveAttribute('aria-checked', 'true');
   await userEvent.click(screen.getByTestId('pane-use'));
-  expect(results[0]).toEqual([{ paneId: 'w9:p1', workspace: 'chat', cwd: '/r/assured-wt', agentStatus: 'idle' }]);
+  expect(results[0]).toEqual([{ paneId: 'w9:p1', workspace: 'chat', cwd: '/r/acme-wt', agentStatus: 'idle' }]);
 });
 
 test('a ready:false spawn keeps the row, unselectable, with its state', async () => {
@@ -1362,7 +1362,7 @@ import { NewRoomModal } from './NewRoomModal';
 import { PanePickerProvider } from './PanePicker';
 
 const PANES = [
-  { paneId: 'w1:p1', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', repo: 'assured', branch: 'main', agentStatus: 'idle' },
+  { paneId: 'w1:p1', workspace: 'acme', title: 'Evaluate codegen', cwd: '/r/acme', repo: 'acme', branch: 'main', agentStatus: 'idle' },
   { paneId: 'w1:p2', workspace: 'chat', title: 'meg', cwd: '/r/chat', repo: 'chat', branch: 'main', agentStatus: 'idle', presence: { handle: 'meg', status: 'live', rooms: ['codegen-split'] } },
 ];
 
@@ -1558,9 +1558,9 @@ Append to `src/ui/Transcript.test.tsx` (the file has no local render helper; `Ol
 ```tsx
 test('a notice renders at the edge, above the older-messages row, and without any messages at all', () => {
   const one = [{ id: 1, room: 'build', handle: 'meg', body: 'hi', mentions: [], postedAt: 1 }];
-  const { unmount } = renderWithProviders(<Transcript room="build" messages={one} notice={<span>invited 2 · assured accepted</span>} />);
+  const { unmount } = renderWithProviders(<Transcript room="build" messages={one} notice={<span>invited 2 · acme accepted</span>} />);
   const notice = screen.getByTestId('transcript-notice');
-  expect(notice).toHaveTextContent('invited 2 · assured accepted');
+  expect(notice).toHaveTextContent('invited 2 · acme accepted');
   expect(notice.compareDocumentPosition(screen.getByTestId('transcript-edge')) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
   unmount();
   renderWithProviders(<Transcript room="quiet" messages={[]} notice={<span>invited 1</span>} />);
@@ -1592,7 +1592,7 @@ test('add agents invites the picked panes and shows the result line on the trans
   installFetchMock();
   fetchMock.mockImplementation(async (url: string, init?: RequestInit) => {
     const path = String(url).split('?')[0];
-    if (path === '/api/panes') return new Response(JSON.stringify({ available: true, panes: [{ paneId: 'w1:p4', workspace: 'assured', title: 'Evaluate codegen', cwd: '/r/assured', agentStatus: 'idle' }] }));
+    if (path === '/api/panes') return new Response(JSON.stringify({ available: true, panes: [{ paneId: 'w1:p4', workspace: 'acme', title: 'Evaluate codegen', cwd: '/r/acme', agentStatus: 'idle' }] }));
     if (path === '/api/chat/invite' && init?.method === 'POST') return new Response(JSON.stringify({ results: [{ paneId: 'w1:p4', delivered: 'accepted' }] }));
     return new Response(JSON.stringify({}));
   });
@@ -1601,7 +1601,7 @@ test('add agents invites the picked panes and shows the result line on the trans
   await userEvent.click(await screen.findByTestId('add-agents-button'));
   await userEvent.click(await screen.findByTestId('pane-check-w1:p4'));
   await userEvent.click(screen.getByTestId('pane-use'));
-  expect(await screen.findByTestId('transcript-notice')).toHaveTextContent('invited 1 · assured pane accepted');
+  expect(await screen.findByTestId('transcript-notice')).toHaveTextContent('invited 1 · acme pane accepted');
 });
 ```
 
@@ -1814,7 +1814,7 @@ without inviting` (`.btn`), `Create #<room> · invite N` (`.btn.primary`).
 The rooms rail header gains a 24px `.aicon` `+` beside the count. The page
 bar gains `add agents` (`.btn.sm`, user-plus icon) before `mark read`. After
 an invite the transcript opens with a `.notice` row (the `.edge` values, left-aligned): `invited 2 ·
-<ok>assured pane accepted</ok> · <warn>fred queued (working)</warn> ·
+<ok>acme pane accepted</ok> · <warn>fred queued (working)</warn> ·
 members appear as they sign in`. Both entry points hide when rt reports
 herdr unavailable and disable with the daemon down.
 ```
diff --git a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
index dd05bb24..6cd52878 100644
--- a/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
+++ b/docs/superpowers/specs/2026-08-26-rt-chat-invite-design.md
@@ -332,7 +332,7 @@ close and navigate.
 
 `add agents` beside `mark read` in the page bar launches the picker directly
 and invites the result. After either flow, the transcript's edge line reads
-`invited 2 · assured pane accepted · fred queued (working) · members appear
+`invited 2 · acme pane accepted · fred queued (working) · members appear
 as they sign in` until the next room change.
 
 ### Phone
diff --git a/lib/__tests__/cswap.test.ts b/lib/__tests__/cswap.test.ts
index 503a5274..5014ed97 100644
--- a/lib/__tests__/cswap.test.ts
+++ b/lib/__tests__/cswap.test.ts
@@ -4,7 +4,7 @@ import { listCswapAccounts, parseCswapList } from "../cswap.ts";
 const CAPTURED = `
 A newer version of claude-swap is available (0.25.0). You are using 0.23.0. Run \`cswap upgrade\` to update.
 Accounts:
-  1: matthew.goodwin@assured.claims [Assured] (history: shared)
+  1: alex@acme.test [Acme] (history: shared)
      ├ $$:    100%   $400.07 / $400.00
      ├ 5h:      0%
      ├ 7d:     40%   resets Aug 30 20:00  in 4d 0h
@@ -15,7 +15,7 @@ Accounts:
 
 test("parses slots, emails, aliases and a compact headroom summary", () => {
   expect(parseCswapList(CAPTURED)).toEqual([
-    { slot: 1, email: "matthew.goodwin@assured.claims", alias: "Assured", headroom: "5h 0% · 7d 40% · Fable 35%" },
+    { slot: 1, email: "alex@acme.test", alias: "Acme", headroom: "5h 0% · 7d 40% · Fable 35%" },
     { slot: 2, email: "someone@example.com", headroom: "5h 12%" },
   ]);
 });
diff --git a/lib/command-tree-def.ts b/lib/command-tree-def.ts
index af720c43..f20ca933 100644
--- a/lib/command-tree-def.ts
+++ b/lib/command-tree-def.ts
@@ -1075,7 +1075,7 @@ export const TREE: Record<string, CommandNode> = {
         fn: "paneSpawn",
         args: [
           { name: "Directory", flag: "--cwd", type: "text", placeholder: "~/Documents/GitHub/chat", hint: "Absolute directory to start in" },
-          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Assured", hint: "cswap alias, email or slot" },
+          { name: "Account", flag: "--account", type: "text", optional: true, placeholder: "Acme", hint: "cswap alias, email or slot" },
           { name: "Model", flag: "--model", type: "text", optional: true, placeholder: "claude-fable-5", hint: "claude --model" },
           { name: "Effort", flag: "--effort", type: "text", optional: true, placeholder: "high", hint: "claude --effort" },
           { name: "Prompt", flag: "--prompt", type: "text", optional: true, placeholder: "read AGENTS.md", hint: "Typed once claude is idle" },
diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
index 30928da0..72843d82 100644
--- a/lib/daemon/__tests__/pane-handlers.test.ts
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -23,12 +23,12 @@ const SNAPSHOT = {
   snapshot: {
     version: "0.8.0",
     protocol: 19,
-    workspaces: [{ workspace_id: "w1", label: "assured", focused: false }],
+    workspaces: [{ workspace_id: "w1", label: "acme", focused: false }],
     tabs: [],
     layouts: [],
     agents: [],
     panes: [
-      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/assured", foreground_cwd: "/tmp/assured", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
+      { pane_id: "w1:p1", terminal_id: "t1", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "idle", cwd: "/tmp/acme", foreground_cwd: "/tmp/acme", terminal_title_stripped: "Evaluate codegen", agent_session: { source: "herdr:claude", agent: "claude", kind: "id", value: "sess-signed" }, revision: 1 },
       { pane_id: "w1:p2", terminal_id: "t2", workspace_id: "w1", tab_id: "w1:t1", focused: false, agent: "claude", agent_status: "working", cwd: "/tmp/other", terminal_title_stripped: "fred", revision: 1 },
       { pane_id: "w1:p3", terminal_id: "t3", workspace_id: "w1", tab_id: "w1:t2", focused: false, agent_status: "unknown", cwd: "/tmp", revision: 1 },
     ],
@@ -51,7 +51,7 @@ function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string,
 
 test("pane:list lists only claude panes, joined to presence by session id, with rooms", async () => {
   const { chat, pane } = harness((method) => (method === "session.snapshot" ? SNAPSHOT : new HerdrFakeError("invalid_request", method)));
-  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/assured", repo: "assured", branch: "main", pane: "w1:p1" });
+  const signed = await chat["chat:sign-in"]({ sessionId: "sess-signed", baseHandle: "meg", cwd: "/tmp/acme", repo: "acme", branch: "main", pane: "w1:p1" });
   if (!signed.ok) throw new Error(signed.error);
   await chat["chat:join"]({ room: "build", handle: signed.data.handle });
 
@@ -60,7 +60,7 @@ test("pane:list lists only claude panes, joined to presence by session id, with
   if (!res.ok) throw new Error("unreachable");
   expect(res.data.panes.map((p) => p.paneId)).toEqual(["w1:p1", "w1:p2"]);
   const first = res.data.panes[0]!;
-  expect(first).toMatchObject({ workspace: "assured", title: "Evaluate codegen", cwd: "/tmp/assured", repo: "assured", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
+  expect(first).toMatchObject({ workspace: "acme", title: "Evaluate codegen", cwd: "/tmp/acme", repo: "acme", branch: "main", agentStatus: "idle", sessionId: "sess-signed" });
   expect(first.presence).toMatchObject({ handle: "meg", rooms: ["build"] });
   expect(first.presence!.status).not.toBe("offline");
 });

From a402328d939be4311eb1008c998c082b76efb002 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Thu, 27 Aug 2026 09:34:22 -0500
Subject: [PATCH 28/30] ci: omitBehavior for pane peek; normalize CR and line
 separators in invite notes

Rebased onto #117 (the picker-conformance omitBehavior gate). rt pane peek
takes a required pane id, which is discovered via rt pane list, so it declares
omitBehavior { exempt } like the other agent-facing verbs.

inviteText now collapses lone CR, CRLF and the Unicode line separators, not
only LF, so a note can never break the one-line /chat:join invariant
(CodeRabbit). Adds CR and CRLF assertions.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/command-tree-def.ts                    | 1 +
 lib/daemon/__tests__/chat-handlers.test.ts | 3 +++
 lib/daemon/handlers/chat.ts                | 2 +-
 3 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/lib/command-tree-def.ts b/lib/command-tree-def.ts
index f20ca933..bc1aa0a7 100644
--- a/lib/command-tree-def.ts
+++ b/lib/command-tree-def.ts
@@ -1063,6 +1063,7 @@ export const TREE: Record<string, CommandNode> = {
         description: "The last lines of a pane's visible screen",
         module: "./commands/pane.ts",
         fn: "panePeek",
+        omitBehavior: { exempt: "agent-facing; the pane id is passed explicitly (discover panes with rt pane list)" },
         args: [
           { name: "Pane", type: "text", placeholder: "w7A:pY", hint: "herdr pane id" },
           { name: "Lines", flag: "--lines", type: "text", optional: true, placeholder: "8", hint: "How many lines from the bottom" },
diff --git a/lib/daemon/__tests__/chat-handlers.test.ts b/lib/daemon/__tests__/chat-handlers.test.ts
index ba358d7e..1ed8ca69 100644
--- a/lib/daemon/__tests__/chat-handlers.test.ts
+++ b/lib/daemon/__tests__/chat-handlers.test.ts
@@ -453,6 +453,9 @@ const agent = (status: string, kind = "claude") => ({ type: "agent_info", agent:
 test("inviteText is one line: the slash command, then the attributed note with newlines collapsed", () => {
   expect(inviteText("build", "matt")).toBe("/chat:join build");
   expect(inviteText("build", "fred", "take the\nserver half\n")).toBe("/chat:join build note from fred: take the server half");
+  // A lone CR (no LF) and a CRLF must collapse too, or the injected command spans lines.
+  expect(inviteText("build", "fred", "take the\rserver half\r")).toBe("/chat:join build note from fred: take the server half");
+  expect(inviteText("build", "fred", "a\r\nb")).toBe("/chat:join build note from fred: a b");
 });
 
 test("chat:invite prompts an idle pane and reports accepted when it reaches working", async () => {
diff --git a/lib/daemon/handlers/chat.ts b/lib/daemon/handlers/chat.ts
index ab0726e7..b2abb609 100644
--- a/lib/daemon/handlers/chat.ts
+++ b/lib/daemon/handlers/chat.ts
@@ -145,7 +145,7 @@ const INVITE_WAIT_MS = 5_000;
 /** One line, because Claude Code dispatches a slash command from the first line only. */
 export function inviteText(room: string, from: string, note?: string): string {
   const head = `/chat:join ${room}`;
-  const body = note?.replace(/\s*\n+\s*/g, " ").trim();
+  const body = note?.replace(/\s*[\r\n\u2028\u2029]+\s*/g, " ").trim();
   return body ? `${head} note from ${from}: ${body}` : head;
 }
 

From 4861f71e240f4ad631fdb4176c42b8bb304af068 Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Thu, 27 Aug 2026 14:49:38 -0500
Subject: [PATCH 29/30] rt-client: derive pane and invite wrapper types from
 Commands

The six wrapper signatures re-typed their payloads and return data by hand,
so the contract in commands.ts and the wrappers could drift with no compile
error. Each wrapper now takes Commands[cmd]["payload"] and returns
Commands[cmd]["data"], the same source of truth the daemon handler reads and
the pattern agentStart already uses. A contract change now fails tsc at every
call site instead of shipping a mismatched payload (CodeRabbit).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/rt-client/src/client.ts | 32 ++++++++++++++------------------
 1 file changed, 14 insertions(+), 18 deletions(-)

diff --git a/packages/rt-client/src/client.ts b/packages/rt-client/src/client.ts
index 1ee52df3..a5f014e5 100644
--- a/packages/rt-client/src/client.ts
+++ b/packages/rt-client/src/client.ts
@@ -23,10 +23,6 @@ import type {
   PresenceRow,
   AgentRecord,
   Commands,
-  ChatPane,
-  PaneAccount,
-  PaneDirectory,
-  InviteResult,
 } from "./commands.ts";
 
 /**
@@ -365,42 +361,42 @@ export function agentList(a: { repo?: string }, o: RtClientOptions = {}): Promis
 // ─── Panes (rt chat invite) ────────────────────────────────────────────────
 // herdr-facing verbs; the daemon answers `herdr unavailable` without herdr.
 
-export function paneList(o: RtClientOptions = {}): Promise<RtResponse<{ panes: ChatPane[] }>> {
-  return rtCommand<{ panes: ChatPane[] }>("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+export function paneList(o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:list"]["data"]>> {
+  return rtCommand<Commands["pane:list"]["data"]>("pane:list", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
-export function panePeek(a: { paneId: string; lines?: number }, o: RtClientOptions = {}): Promise<RtResponse<{ paneId: string; lines: string[] }>> {
+export function panePeek(a: Commands["pane:peek"]["payload"], o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:peek"]["data"]>> {
   const payload: Record<string, unknown> = { paneId: a.paneId };
   if (a.lines !== undefined) payload.lines = a.lines;
-  return rtCommand<{ paneId: string; lines: string[] }>("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  return rtCommand<Commands["pane:peek"]["data"]>("pane:peek", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 /** The spawn waits on claude starting, so its budget is minutes, not seconds. */
 export function paneSpawn(
-  a: { cwd: string; account?: string; model?: string; effort?: string; prompt?: string; workspace?: string },
+  a: Commands["pane:spawn"]["payload"],
   o: RtClientOptions = {},
-): Promise<RtResponse<{ pane: ChatPane; ready: boolean }>> {
+): Promise<RtResponse<Commands["pane:spawn"]["data"]>> {
   const payload: Record<string, unknown> = { cwd: a.cwd };
   for (const k of ["account", "model", "effort", "prompt", "workspace"] as const) if (a[k] !== undefined) payload[k] = a[k];
-  return rtCommand<{ pane: ChatPane; ready: boolean }>("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90_000 });
+  return rtCommand<Commands["pane:spawn"]["data"]>("pane:spawn", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 90_000 });
 }
 
-export function paneAccounts(o: RtClientOptions = {}): Promise<RtResponse<{ accounts: PaneAccount[] }>> {
-  return rtCommand<{ accounts: PaneAccount[] }>("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+export function paneAccounts(o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:accounts"]["data"]>> {
+  return rtCommand<Commands["pane:accounts"]["data"]>("pane:accounts", {}, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
-export function paneDirectories(a: { q?: string }, o: RtClientOptions = {}): Promise<RtResponse<{ directories: PaneDirectory[] }>> {
+export function paneDirectories(a: Commands["pane:directories"]["payload"], o: RtClientOptions = {}): Promise<RtResponse<Commands["pane:directories"]["data"]>> {
   const payload: Record<string, unknown> = {};
   if (a.q !== undefined) payload.q = a.q;
-  return rtCommand<{ directories: PaneDirectory[] }>("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
+  return rtCommand<Commands["pane:directories"]["data"]>("pane:directories", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 10_000 });
 }
 
 export function chatInvite(
-  a: { paneId: string; room: string; note?: string; from: string; callerPane?: string },
+  a: Commands["chat:invite"]["payload"],
   o: RtClientOptions = {},
-): Promise<RtResponse<InviteResult>> {
+): Promise<RtResponse<Commands["chat:invite"]["data"]>> {
   const payload: Record<string, unknown> = { paneId: a.paneId, room: a.room, from: a.from };
   if (a.note !== undefined) payload.note = a.note;
   if (a.callerPane !== undefined) payload.callerPane = a.callerPane;
-  return rtCommand<InviteResult>("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
+  return rtCommand<Commands["chat:invite"]["data"]>("chat:invite", payload, { sockPath: o.sockPath, timeoutMs: o.timeoutMs ?? 30_000 });
 }

From 30a85fa11e7aea039094487268415c627b66ae2c Mon Sep 17 00:00:00 2001
From: Matthew Goodwin <goodwin.matthew.eric@gmail.com>
Date: Thu, 27 Aug 2026 14:58:47 -0500
Subject: [PATCH 30/30] daemon: bound pane:spawn registration poll by
 wall-clock, not attempt count

The poll ran a fixed Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS) attempts,
each an agent.get that can take up to the 5s socket timeout when herdr is alive
but slow, so the loop could hold pane:spawn's caller far past the 10s the
constant name promises. It now polls until now() crosses a REGISTER_BUDGET_MS
deadline, using the existing clock seam. Adds a test with an injected clock that
locks the wall-clock bound (CodeRabbit).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/daemon/__tests__/pane-handlers.test.ts | 18 ++++++++++++++++--
 lib/daemon/handlers/pane.ts                |  7 ++++++-
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/lib/daemon/__tests__/pane-handlers.test.ts b/lib/daemon/__tests__/pane-handlers.test.ts
index 72843d82..6f09a1ee 100644
--- a/lib/daemon/__tests__/pane-handlers.test.ts
+++ b/lib/daemon/__tests__/pane-handlers.test.ts
@@ -38,14 +38,14 @@ const SNAPSHOT = {
 const CSWAP_EXEC = async (argv: [string, ...string[]]) =>
   argv[1] === "list" ? { stdout: "Accounts:\n  1: me@x.y [Me]\n", stderr: "", exitCode: 0 } : { stdout: "main\n", stderr: "", exitCode: 0 };
 
-function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string, string> } = {}) {
+function harness(handler: FakeHerdrHandler, extra: { repoIndex?: Record<string, string>; now?: () => number } = {}) {
   const { sock, seen, stop } = fakeHerdr(handler);
   stops.push(stop);
   const db = freshDb();
   const herdr: typeof herdrRequest = (method, params, opts) => herdrRequest(method, params, { ...opts, sockPath: sock });
   const exec = CSWAP_EXEC;
   const chat = createChatHandlers({ db, emitEvent: () => 0 });
-  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: Date.now });
+  const pane = createPaneHandlers({ db, repoIndex: () => extra.repoIndex ?? {}, herdr, exec, now: extra.now ?? Date.now });
   return { db, seen, chat, pane };
 }
 
@@ -265,6 +265,20 @@ test("pane:spawn returns ready:false with the pane when idle never arrives, and
   expect(calls).not.toContain("agent.prompt");
 });
 
+test("pane:spawn stops polling for registration at the wall-clock budget, not a fixed attempt count", async () => {
+  // A slow-but-alive herdr: the agent never registers, and the clock jumps past
+  // the budget after the first poll. A fixed attempt count would poll dozens of
+  // times (each agent.get up to the 5s socket timeout); the deadline stops after one.
+  let reads = 0;
+  const now = () => (reads++ < 2 ? 1_000 : 1_000 + 10_000_000);
+  const { handler, calls } = spawnFake({ statuses: ["idle"], agentGetFailures: 999 });
+  const { pane } = harness(handler, { now });
+  const res = await pane["pane:spawn"]({ cwd: "/repos/chat" });
+  if (!res.ok) throw new Error(res.error);
+  expect(res.data.ready).toBe(false);
+  expect(calls.filter((c) => c === "agent.get").length).toBeLessThanOrEqual(2);
+});
+
 test("pane:spawn refuses an unknown cswap account before touching herdr", async () => {
   const { handler, calls } = spawnFake({ statuses: ["idle"] });
   const { pane } = harness(handler);
diff --git a/lib/daemon/handlers/pane.ts b/lib/daemon/handlers/pane.ts
index 1a7d1c9f..3eb2db2f 100644
--- a/lib/daemon/handlers/pane.ts
+++ b/lib/daemon/handlers/pane.ts
@@ -217,8 +217,13 @@ export function createPaneHandlers(opts: {
       if (!sent.ok) return herdrError(sent);
 
       // herdr registers the agent a few hundred ms after the shell starts claude.
+      // Bound the wait by wall-clock, not a fixed attempt count: a slow-but-alive
+      // herdr can make each agent.get take up to the plain socket timeout, so a
+      // count of attempts would run many times the intended budget while pane:spawn
+      // holds its caller.
       let registered = false;
-      for (let attempt = 0; attempt < Math.ceil(REGISTER_BUDGET_MS / REGISTER_POLL_MS); attempt++) {
+      const registerDeadline = now() + REGISTER_BUDGET_MS;
+      while (now() < registerDeadline) {
         const got = await herdr("agent.get", { target: paneId });
         if (got.ok) {
           registered = true;