@gavin-hu/my-pi-agent 0.19.0 → 0.21.0

package/docs/extensions/session-bus.md

@@ -16,15 +16,15 @@ Status records what a reader can rely on: **Shipped** is in a tagged release, **
 
 | Capability | How | What you get | Status |
 |---|---|---|---|
-| Membership | `session join [label]`, `/team join [<label>]`, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `w` joins under the name the bus derives and writes nothing to Pi. | Unreleased |
-| Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read. | Shipped |
+| Membership | `session join [label]`, `/team join [<label>]`, `/board`, the first `board` claim, the board's `w` | The join: this session is on the bus under a stable label peers address, and listens for mail unless told not to. A label given to `session join` or `/team join` is also Pi's session name, so the footer and `/resume` agree with the record; `/board` joins as the page's seat (`team-lead`) or, on a page it is only watching, under its own `team-agent-<id>` name; the first `board` claim joins under that same name, and renames nothing; `w` joins under the name the bus derives and writes nothing to Pi. | Shipped |
+| Peer discovery | `session status` | Every active session with its unread count and claims, plus this session's identity, in one read — and a session whose process is gone says so, its paths free from that read on. | Unreleased |
 | Live board | `/sessions` | Sessions, this session's unread mail, and every claim held on the repository, on one screen. | Shipped |
 | Board actions | `/sessions` (`w`, `x`) | Start or stop listening from the board, or release an own claim behind a confirmation, without leaving it. | Shipped |
 | Short messages | `session send` | One message per recipient, addressed by label or id, with a broadcast for events. | Shipped |
 | Message kinds | `session send` with `kind` | A `message`, `event`, `ask`, or `handoff` keeps its meaning; `ask` does not block the sender, and a `handoff` is named as the work it assigns. | Shipped |
 | Message paths | `session send` with `paths` | A message can name the repository paths it concerns, echoed in the inbox row. | Shipped |
 | Inbox on demand | `session inbox` | Up to `limit` messages, oldest first, consumed only when the model asks. | Shipped |
-| Listening | `session join` | New mail reported at the next turn; `join({wake: true})` raises one turn once the agent is idle, and `join({listen: false})` stops it. | Unreleased |
+| Listening | `session join` | New mail reported at the next turn; `join({wake: true})` raises one turn once the agent is idle, and `join({listen: false})` stops it. The record carries whether this session listens, so a peer's status read answers it without asking. | Shipped |
 | Path claims | `session claim`, `session release` | A file or directory prefix held by one session at a time. | Shipped |
 
 ## Quickstart
@@ -55,12 +55,12 @@ collapsed line that expands to the board's rows.
 
 | Action | Inputs | Result |
 |---|---|---|
-| `status` | — | Active sessions with unread counts, claims, and this session's identity. Prunes stale records. A read: it never adds this session to the bus. |
+| `status` | — | Active sessions with unread counts, their state, claims, and this session's identity. A session whose process is gone is listed as `gone` until its heartbeat ages out, and its claims are not listed at all. Prunes stale records. A read: it never adds this session to the bus. |
 | `send` | `to`, `text`, optional `kind`, optional `paths` | Writes one message per recipient. `to: "*"` is only valid with `kind: "event"`. |
 | `inbox` | optional `limit` | Returns and deletes up to `limit` messages, oldest first (default 20, max 50). |
 | `claim` | `paths` | Claims repository-relative files or directory prefixes; returns conflicts with their owner. |
 | `release` | `paths` | Removes claims owned by this session; reports paths owned by someone else. |
-| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused with its owner named, and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
+| `join` | optional `label`, `wake`, `listen` | Joins the bus, names this session on it and in Pi when a label is given — the same path and uniqueness rule as `/team join`, so the footer and `/resume` agree with the record peers address — and starts listening for mail. `wake: true` raises one turn per burst once the agent is idle; `wake: false` reports at the next turn; `listen: false` joins without listening. A label a live session holds is refused, naming the session that holds it — its id, since the label it holds is the one you asked for — and the refusal leaves both names and the watch alone. The result reports the label the bus settled on and whether mail will reach this session. |
 
 A claim is all-or-nothing: if one path conflicts, nothing is claimed. A claim on
 a directory conflicts with claims below it and above it, so `src/api` and
@@ -167,8 +167,11 @@ listening watch is what raises the turn.
   session to the bus, so an unjoined session reads a board it is not on until it
   joins or acts.
 - **Membership is per session and session-only.** It survives neither a resume nor a
-  new process; unread mail is previewed once more after `/resume`, and the record
-  goes when the session stops.
+  new process: the record and every claim it held go when the session stops, and a
+  resumed pane is off the bus until it joins again. What does survive is everything
+  stored as a file — unread mail is previewed once more after `/resume`, and the
+  label a rejoining session takes is the same one, because it derives from Pi's
+  session name (`runtime.test.ts`, *a resume*).
 - **The board acts on your own state only.** `w` starts or stops listening and `x`
   releases a claim it holds. Mail is a preview, not a consume: the board never
   deletes a message, never marks one reported, and never touches a peer's inbox or
@@ -178,8 +181,18 @@ listening watch is what raises the turn.
   both sides to keep replying; the answer is to stop listening on one of them.
 - **No broadcast history.** A broadcast reaches the sessions active at send time;
   a session that joins later does not receive it.
-- **No forced claims.** A crashed owner blocks its paths until the session TTL
-  expires. This is deliberate; stealing a claim is worse than waiting.
+- **No forced claims.** There is no takeover while an owner can still answer: a
+  claim is released by its owner, or by the next bus call once the owner's process
+  is gone. A *hung* owner still blocks its paths until the session TTL expires,
+  because a running process is not evidence of a working one.
+- **A dead process is named, not waited out.** A record carries its `pid` and, where
+  the host can name one, that process's start time. A pid that is no longer running,
+  or one whose start time is not the record's (a reused pid), reads `gone` at once:
+  its label is free, the paths it held are nobody's, and `session status` and
+  `/sessions` count it. It keeps its row until its heartbeat ages out, so a lead can
+  see what died and reclaim it. A record with no `pid` — and a platform without
+  `ps`, such as Windows — falls back to the heartbeat rather than being called dead
+  on no evidence.
 - **Bounded by TTL.** An idle session with a stopped heartbeat is pruned after
   ten minutes; its record, its claims, and an inbox directory left empty go with
   it, and its unread mail expires after 24 hours. A claim belongs to a record
@@ -202,7 +215,7 @@ listening watch is what raises the turn.
 | Tools | `session` — one action-shaped tool; `readOnlyHint: false`, `destructiveHint: true`, `openWorldHint: false`, `executionMode: "sequential"`. |
 | Commands | `/sessions` — the board in `tui`, the listing elsewhere; no arguments and no sub-commands. |
 | UI | `tui` mounts `SessionListComponent` through `withPolledScreen` (rails suppressed, a 1 s read-only poll of `snapshot()` + `peek()`); every other mode prints through `ctx.ui.notify`. No status chip, so listening never changes the footer. |
-| Events | `session_start` resolves the repository and arms the mail trigger, without joining; `before_agent_start` reports queued non-wake mail at the next turn, `agent_settled` retries a wake the run suppressed, and `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
+| Events | `session_start` resolves the repository and arms the mail trigger, without joining; `session_tree` only repaints, since navigating the tree changes no pending record; `agent_start` marks the run busy; `before_agent_start` reports queued non-wake mail at the next turn; `agent_settled` retries a wake the run suppressed; `context` prunes stale notices; `session_shutdown` clears the heartbeat, the watch ticker, and the record. The seven hooks are `lib/report.ts`'s `registerPendingChannel`, not a local copy. |
 | State | Files under `<agent-dir>/session-bus/<repo-key>/`; nothing in the session branch. Listening is session-only. `/resume` re-registers the same session id. |
 | Lifecycle | The factory only registers. The runtime starts on `session_start`; heartbeat, watch ticker, and cleanup belong to it. Disabling `session-bus` through `PI_DISABLED_EXTENSIONS` registers nothing. |
 | Mode | Uses `ctx.mode` to decide whether `/sessions` mounts the board and how a label is derived; nothing joins at start in any mode; `askHuman` is not involved and no status chip is published. |

package/docs/extensions/team.md

@@ -2,14 +2,16 @@
 
 `board` owns the cards. `team` owns the lead's three actions: `assign` hands a card to a
 session that is **already running**, `offer` hands one to whoever is free, and `reclaim`
-takes one back when its owner has gone quiet. The first two are a write on the board and a
-message on the session bus; `reclaim` writes the card alone, so it needs no bus at all. The
-report says what the peer will actually do with it.
+takes one back when its owner is gone or has gone quiet. `assign` writes the card and puts
+a handoff on the session bus, `offer` writes only the moment it was made — never an owner,
+because the first peer to claim is what makes an offer into work — and `reclaim` writes the
+card alone, so it needs no bus.
+The report says what the peer will actually do with it.
 
 Nothing starts a process. A message lands in the peer's inbox and is reported at its next
 turn, so `assign` and `offer` are messages, not launches.
 
-<img src="../../assets/screens/team.png" alt="The Team tab as a dashboard: on the left, a Needs a decision queue of rows with a coloured kind edge, the reason on its own line, and a Reclaim or Claim action on the row edge, or no action on a card that waits; on the right, a Teammates list with a state dot, label, you chip, mail badge, a not listening chip on a peer whose watch is off, and a line of what each holds; and one muted Done line under both" width="100%">
+<img src="../../assets/screens/team.png" alt="The Team tab as a dashboard: on the left, a Needs a decision queue of rows with a coloured kind edge, the reason on its own line, and the owner as a chip on the row's right; on the right, a Teammates list with a state dot, label, you chip, mail badge, a not listening chip on a peer whose watch is off, and a line of what each holds; and one muted Done line under both" width="100%">
 
 *The Team tab: the cards that need the lead, then who is on the team — including an
 owner whose label nothing answers to, and a teammate that is not listening.*
@@ -18,14 +20,14 @@ owner whose label nothing answers to, and a teammate that is not listening.*
 
 | Capability | How | What you get |
 |---|---|---|
-| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or any card you work | The session is on the team under a label peers address, listening, and `/team` and the Team tab list it |
+| Join the team | `/board` as the lead, `/team join <label>` as a teammate, or the first card you claim | The session is on the team under a name peers address, listening, and `/team` and the Team tab list it |
 | Hand a feature to a running session | `team` action `assign` | The card is `doing`, owned by that session, and a handoff is in its inbox |
 | Tell the peer what to do first | `team` action `assign` with `note` | The handoff carries the card, its paths, its plan, and that line |
-| Hand a feature to whoever is free | `team` action `offer` | Every other live session gets an event naming the card; the card stays unowned until one claims it |
+| Hand a feature to whoever is free | `team` action `offer` | Every other live session gets an event naming the card; the card stays unowned until one claims it, and it records when the offer was made, so a lead can tell an offer nobody took from a card nobody has looked at |
 | Know whether a message will be woken for | an `assign` or `offer` result, `/team`, and the Team tab | All three name the peers whose record says their next turn is when it lands: the result as `Not listening: <labels>`, `/team` as a lowercase `not listening:` inside its presence line, the Team tab as a chip |
 | Take a card back | `team` action `reclaim` | The owner clears, the card returns to To do, and its notes stay |
 | Keep the round to the team | `team` | Only `assign`, `offer`, and `reclaim`: no card is created, moved, planned, or finished here — that is `board`'s surface |
-| See the round without a browser | `/team` | `buildRound`'s summary — the one the page's Team tab is served — laid out as text by `formatRound`: what needs a decision, who holds what, then one presence line for who is live, who is not listening, and who has gone quiet. Ten lines at most, then `… N more`; an empty board is one line |
+| See the round without a browser | `/team` | `buildRound`'s summary — the one the page's Team tab is served — laid out as text by `formatRound`: what needs a decision, who holds what, then one line naming the cards a dead owner left behind, and one presence line for who is live, who is not listening, who has gone quiet, and who is gone. The rollup itself is capped at ten lines, then `… N more`, and the gone and presence lines follow the cap rather than counting against it — the cap is a notify's limit, not a screen's. An empty board is one line |
 
 ## Quickstart
 
@@ -56,19 +58,20 @@ its surface is the point: `board` and `team` join this session for you.
 | You are | Action | What happens |
 |---|---|---|
 | The lead | `/board` | The session joins as `team-lead` — the page's own seat name — and listens, so a handoff or an offer is reported at its next turn |
-| A teammate | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name |
-| Either | any `board` action that writes | The first one joins the session under the name it already has, and listens |
-| A viewer | `/board` on a session that is not serving | The page is somebody else's to serve, so this session joins under its own label instead of the seat |
+| A teammate | the first card it claims | The session joins as its own `team-agent-<id>` name and listens, and Pi's footer keeps the name it already had |
+| A teammate who wants a name | `/team join billing-core` | The session joins as `billing-core`, and Pi's footer and `/resume` show that name — the one join that renames |
+| A viewer | `/board` on a session that is not serving | The page is somebody else's to serve, so this session joins under its own name instead of the seat |
 
 Joining is listening: mail is reported at that session's next turn, and **no turn is
 raised** for it, so being on the team never spends a turn. `/team` says who is live and
-who is live but not listening. `/board status` repeats only what the last `/board` in this
-session did about the team — a join made by `/team join` or by a card write is not on that
-line, and a page that is not running prints no team clause at all.
+who is live but not listening. `/board status` reports the team this session is on — which
+label, and whether mail reaches it — whichever door put it there, and prints no team clause
+only when this session never joined at all.
 
-**The seat is not a session.** The page writes as `team-lead` with an id of its own, so a
-card it claimed comes back with `reclaim` rather than a `release` from the terminal. The
-label is shared with the session that serves the page; the ids are not.
+**The seat is not a session.** The page is a view: it has one name, `team-lead`, and an id
+of its own derived from it, and it writes nothing, so it holds no card for a lead to take
+back. Its cards come from the session that serves it, whose label is the same and whose id
+is not: a card that session claimed is the session's, and `release` returns it.
 
 ## Tool
 
@@ -78,12 +81,26 @@ label is shared with the session that serves the page; the ids are not.
 | Action | Parameters | Behaviour |
 |---|---|---|
 | `assign` | `card`, `to`, `note?` | Checks the card's preconditions, sends the handoff as a `handoff` message, then records the owner |
-| `offer` | `card`, `note?` | Checks the preconditions a claim would meet, broadcasts the card as an `event` to every other live session, and writes nothing |
+| `offer` | `card`, `note?` | Checks the preconditions a claim would meet, broadcasts the card as an `event` to every other live session, then records the offer on the card — the moment, and nothing else: status and owner are untouched |
 | `reclaim` | `card` | Clears the owner and returns the card to To do, keeping its notes and plan |
 
 `card` takes `4` or `#4`. `to` is a teammate's label or id, as `/team` lists them — a
 label nobody answers to cannot be handed a card, and the result says so.
 
+The parameters are one flat object, so a field is published to every action at once.
+An action reads only the fields in its row above, and a call carrying one that its
+action does not read is **refused**, naming the action that takes it — not ignored.
+`to` is the one that matters: an `offer` that named a peer was broadcast to every live
+session while the lead believed it had named one, and a `reclaim` that named one took
+the card back from its holder anyway.
+
+```
+offer does not act on to: `assign` takes it.
+```
+
+`ACTION_FIELDS` in `types.ts` is the table that answers this, `lib/stray-fields.ts` is
+the sentence, and a test holds every published parameter to an action that acts on it.
+
 ### The order is the point
 
 `assign` sends **before** it assigns, and each failure leaves a state the report names:
@@ -94,10 +111,15 @@ label nobody answers to cannot be handed a card, and the result says so.
 | the send | untouched — `todo`, no owner | `#4 was not handed off to billing-core: …`, plus `The card is unchanged.` |
 | the assignment, after a successful send | whatever the other writer left | `#4 was handed off to billing-core, but the card changed before it could be assigned: …`, and the peer is told to `board claim` it |
 
-`offer` has no order to get wrong, because it writes nothing: a refused broadcast leaves
-the card exactly as the rules just read it, and the first `board claim` is what turns an
-offer into work. Two peers claiming at once are settled by the store's compare-and-set —
-one claim wins, and the other is refused with the owner named.
+`offer` broadcasts **before** it records, for the same reason: an offer nobody received
+must not leave a record claiming one happened. A refused broadcast leaves the card exactly
+as the rules read it, and the write that follows changes one field — when the offer was
+made. If the card changed in between, the peers already have the message, so the refusal
+says the offer stands as a message and the board is what it now says. The first `board
+claim` is what turns an offer into work, and the claim is what clears the record: every
+answer to an offer — a claim, an assignment, a release — takes it with it, so a record
+here means the offer is still open. Two peers claiming at once are settled by the store's
+compare-and-set; one claim wins, and the other is refused with the owner named.
 
 `delivered` in the details means a message file was written for that label — not that the
 peer read it. `notListening` names the peers it reached whose record says they are not
@@ -118,7 +140,11 @@ read it with `session inbox`, record the plan, and start. The card is already th
 moves it to `done` or `blocked`.
 
 An offer is advice: nothing is theirs until they claim it, and a card nobody claims stays
-`todo`, so it keeps showing up as unassigned in the round.
+`todo`, so it keeps showing up as unassigned in the round — with its age, which is the one
+thing an event cannot carry. `board` prints it as `offered 1m ago, and nobody took it`, the
+card face says `offered 1m ago · nobody took it`, and the Team tab's queue says
+`offered 1m ago — nobody took it` in place of "nobody holds it". A lead reading that has a
+decision the plain unassigned row never offered: re-offer, `assign` it, or take it.
 
 ## Security
 
@@ -133,7 +159,7 @@ An offer is advice: nothing is theirs until they claim it, and a card nobody cla
 
 - **Nothing here can start a peer's turn.** A message is reported at the recipient's next
   turn; a session that is not listening at all reads it only when it reads its inbox.
-- **`to` must be on the team.** A session that never opened the board, joined, or worked a
+- **`to` must be on the team.** A session that never opened the board, joined, or claimed a
   card cannot be handed a card, and an offer to nobody says so.
 - **`team-lead` is a label, not a person.** The seat is not a session, so its actor id
   `board:team-lead` answers no message; the label is the one the session serving the page
@@ -150,8 +176,10 @@ An offer is advice: nothing is theirs until they claim it, and a card nobody cla
   every ten seconds and the record is believed for ten minutes, so `quiet:` means the
   record went stale rather than that the peer died, while `not listening` is the separate
   `watching` field, written when the session joins or arms and disarms its watch.
-- **Plan mode makes this unavailable.** `session` is a mutating tool, so while plan mode is
-  active the bus call is refused. Assign after the plan is approved.
+- **Plan mode makes this unavailable.** Neither `team` nor `session` is a read-only tool, so
+  plan mode refuses both by name and tells the model to exit and get approval; the board
+  stays readable, since `list` is the one action it admits. Assign after the plan is
+  approved.
 - **Ownership is advisory.** `assign` does not create a path claim; the peer still claims
   the paths it edits through `session`.
 
@@ -179,9 +207,9 @@ An offer is advice: nothing is theirs until they claim it, and a card nobody cla
   and must work with the bus disabled; `team` is the lead's round and is the only thing
   that needs the bus. If the round ever stops needing it, `team` folds back in.
 - **Joining is the bus's, wearing `board`'s clothes.** A lead should not have to learn a
-  second tool to be on a team, so `/board` joins, a card write joins, and `/team join` is
-  the one naming action. `wake` stays a bus-level choice and is never armed on a user's
-  behalf, because it spends turns.
+  second tool to be on a team, so `/board` joins, the first claimed card joins, and
+  `/team join` is the one naming action. `wake` stays a bus-level choice and is never
+  armed on a user's behalf, because it spends turns.
 - **Push and pull are two verbs.** `assign` writes the owner and sends one message;
   `offer` broadcasts and writes nothing. One verb with an optional `to` would have two
   outcomes and one details shape, and a reader could not tell which happened.

package/docs/extensions/wechat.md

@@ -594,7 +594,8 @@ status, which is what the old start/stop guidance used to do.
 | File | Responsibility |
 |---|---|
 | `index.ts` | Factory: gate, register the command and tool, wire the lifecycle events, build the bridge, open peer sessions from the host context. |
-| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, slash dispatch, the status snapshot, and `sendToOwner`. |
+| `bridge.ts` | The composition root: wires the poll loop, delivery, presence, admission, and inbound modules to the live client/account/cursor/state; owns the connection lifecycle, the status snapshot, and `sendToOwner`. |
+| `intake.ts` | The inbound path: who is refused, what is a replay, what is a command, what answers a pending prompt, and what is queued or turned away; the admission predicates live here too. |
 | `tools.ts` | The `send_wechat` tool: owner-only proactive text or one image, with the neither-or-both refusal. |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
 | `types.ts` | Wire and domain types. |

package/docs/extensions/worktree.md

@@ -65,7 +65,7 @@ four are `executionMode: "sequential"`, and only `list_worktrees` is read-only.
 | Tool | Usage |
 |---|---|
 | `enter_worktree` | `name` to create a worktree, or `path` to enter an existing one. Errors if already isolated. |
-| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `merged`). |
+| `exit_worktree` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `commits`, `merged`). |
 | `prune_worktrees` | no parameters. Removes eligible managed worktrees and reports the rest. |
 | `list_worktrees` | no parameters. Read-only status: active root, inactive overrides, isolation gaps, managed worktrees. |
 
@@ -77,11 +77,14 @@ it.
 `exit_worktree` returns to the main checkout. A clean worktree is removed
 automatically; one with uncommitted changes or new commits prompts (or is kept
 in non-interactive mode). Its result ends with a **handoff**: the branch, how
-many commits it holds beyond the merge target, whether that target already
-contains them, and the `git merge --no-ff` and `gh pr create` commands that
-finish the task. The tool never commits, merges, pushes, or opens the PR. A
-branch that still holds work (uncommitted changes, or commits not reachable from
-the recorded base) is never force-deleted, even with `remove: true`.
+many commits it holds beyond the merge target, how many it made since it was
+created, whether that target already contains them, and the `git merge --no-ff`
+and `gh pr create` commands that finish the task. A branch with no commits of its
+own says so rather than claiming a merge — a worktree that never committed is an
+ancestor of its base, and "merged" would read as work that landed. The tool
+never commits, merges, pushes, or opens the PR. A branch that still holds work
+(uncommitted changes, or commits not reachable from the recorded base) is never
+force-deleted, even with `remove: true`.
 
 While isolated, `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` all resolve
 relative paths inside the worktree, and:
@@ -113,6 +116,12 @@ instead, so there is no gap to report. `unverifiable` appears only while
 reset at session start. `doctor` reports the `powershell` switch as `degraded`
 when it is off and notes the two structural gaps, which no setting closes.
 
+Managed worktrees follow the header, one row each, as `path`, branch, and the
+marks in brackets: `current`, `missing`, `dirty (2)`, `ahead 3`, `behind 1`, `no
+commits`, `commits 4  merged`, `locked`, `used 2d ago`. A row with nothing else to
+report says `clean` — the same word the `/worktree` screen prints, because both
+read `statusMarks` rather than each deciding what an empty row means.
+
 ## Commands and flags
 
 | Command / flag | What it does |
@@ -136,10 +145,14 @@ being ignored.
 <img src="../../assets/screens/worktree.png" alt="The /worktree screen: a Worktrees title rule with a `4 worktrees · 1 dirty · 1 ahead` summary, the current dark-mode row carrying its ahead count, a dirty row, a merged row, and a stale-locked row, the focused row's path and base with the Not isolated gap under it, and the key hints" width="100%">
 
 `/worktree` on its own opens a list screen: one row per managed worktree with its
-state (current, dirty, ahead, behind, merged, locked, last used), the active
-worktree's base and isolation gaps under the focused row, and a detail pane for
-the selected one. Outside a terminal — print, RPC, JSON — the same facts print as
-text instead, which is also what the model's `list_worktrees` reads.
+state (current, dirty, ahead, behind, commits, merged, locked, last used), the
+active worktree's base and isolation gaps under the focused row, and a detail
+pane for the selected one. A worktree that has not committed since it was created
+says `no commits` instead of `merged`: it is an ancestor of its base, which git
+alone cannot tell from a branch that landed. When work did land, the row says how
+much — `commits 2  merged`. Outside a terminal — print, RPC, JSON — the same
+facts print as text instead, which is also what the model's `list_worktrees`
+reads.
 
 | Key | What it does |
 |---|---|
@@ -298,10 +311,11 @@ use, falling back to directory mtime for a worktree with no record.
   writes are guarded (relative paths are not isolated), and `list_worktrees`
   reports it. `skipOverrides` is read at load time, from the process working
   directory.
-- `git branch --merged main` calls a worktree branch merged whenever it matches
-  its base, so a worktree that never committed looks landed while its
-  uncommitted work is still there. Read `git -C <path> status` before removing
-  one; `list_worktrees` reports the same clean/merged flags.
+- The commit count behind `no commits` comes from the commit a worktree was
+  created at, which the registry records. A worktree this package did not create
+  has no fork point on record, so it falls back to what `git branch --merged`
+  says: for one of those, a worktree that never committed still reads as merged.
+  Read `git -C <path> status` before removing one.
 - The guard is best-effort at the shell level: command substitution, `eval`, and
   `sh -c` are only covered when `blockUnparsableCommands` is enabled, and real
   isolation of arbitrary shell writes needs an OS sandbox. `/worktree` names the
@@ -330,7 +344,7 @@ use, falling back to directory mtime for a worktree with no record.
 | Contract | Detail |
 |---|---|
 | Registration | The default export calls `registerWorktree`: root-tool overrides, the `--worktree` flag, lifecycle listeners, model tools, and the `/worktree` command. Nothing long-lived starts at load. |
-| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, merged }`. |
+| Tools | `enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees` via `registerTool`. All `executionMode: "sequential"`. Annotations: `enter_worktree` destructive + open-world; `exit_worktree`/`prune_worktrees` destructive; `list_worktrees` read-only. No `outputSchema`; structured state is returned in tool-result `details` — `exit_worktree` carries `{ state, removed, handoff }`, where `handoff` is `{ branch, base, ahead, commits, merged }` (`commits` absent when the worktree has no recorded base commit). |
 | Built-in overrides | `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` are re-registered under the same names with `defaultActive: false`; each spreads the built-in definition and replaces only `execute`. `skipOverrides` is applied at load time. `powershell` is deliberately not overridden: it cannot be re-rooted without a guard, so the `tool_call` handler refuses it (see `guard.blockPowershell`). |
 | Commands | `/worktree` via `registerCommand`, with argument completions for `enter`, `exit`, and `prune`. The bare command mounts `screen.ts` in a terminal and prints the status text otherwise; `enter`/`exit`/`prune` refuse while plan mode is read-only. |
 | Flags | `--worktree` via `registerFlag`. |
@@ -407,6 +421,7 @@ one read and two renderings.
 | `root-tools.ts` | Load-time built-in overrides bound to the active root |
 | `git.ts` | Git plumbing (shared runner + read helpers) |
 | `guard.ts` | Path, shell, and git-redirect isolation checks, plus the `powershell` refusal |
+| `shell.ts` | The command-line reader those checks ask: words, segments, and redirection targets |
 | `gaps.ts` | The isolation gaps a session carries, and how they read (pure) |
 | `include.ts` | `.worktreeinclude` matcher and copy |
 | `config.ts` / `state.ts` / `status.ts` | Config, session entry shape, status text and the shared snapshot |

package/extensions/board/commands.ts

@@ -9,21 +9,25 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { plural } from "../../lib/board/round-text.ts";
+import type { BoardTeam } from "../../lib/board/session.ts";
 import type { JoinResult } from "../../lib/session-tool.ts";
 import { createTeamJoin, type TeamJoin } from "../../lib/session-tool.ts";
-import { joinLabel, teamLine } from "./join.ts";
+import { teamLine } from "./join.ts";
 import type { BoardPage, BoardPageStatus } from "./page.ts";
 
 /** The command's name, which is also the word a user types. */
 export const BOARD_COMMAND = "board";
 
 /** The words the command accepts, in the order a user is likely to want them. */
-export const BOARD_WORDS = ["status", "stop", "team"] as const;
+const BOARD_WORDS = ["status", "stop", "team"] as const;
 
-export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team?: TeamJoin } = {}): void {
+export function registerCommands(
+	pi: ExtensionAPI,
+	session: BoardTeam,
+	page: BoardPage,
+	deps: { team?: TeamJoin } = {},
+): void {
 	const team = deps.team ?? createTeamJoin(pi);
-	/** What the last `/board` did about the team, for the status line. */
-	let joined: JoinResult | undefined;
 	pi.registerCommand(BOARD_COMMAND, {
 		description: "Open the shared board in a local browser: /board [team | status | stop]",
 		getArgumentCompletions: (prefix: string) => {
@@ -35,12 +39,24 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			const word = args.trim().toLowerCase();
 			if (word === "status") {
-				ctx.ui.notify(statusLine(page.status(), joined), "info");
+				ctx.ui.notify(statusLine(await page.status(), session.team.last()), "info");
 				return;
 			}
 			if (word === "stop") {
-				const status = page.status();
-				// A viewer's page is somebody else's to stop, and saying whose is the answer.
+				const status = await page.status();
+				// A note nobody answers is not a page to leave for the next session to trip over:
+				// it is dropped here, and the line says whose it was.
+				if (status.stale === true) {
+					const dropped = await page.dropStale(ctx);
+					ctx.ui.notify(
+						dropped
+							? `board: dropped ${status.seat}'s note for :${status.port} — it answered nobody`
+							: `board: nothing to stop here — ${status.seat} is answering on :${status.port}`,
+						"info",
+					);
+					return;
+				}
+				// A page another session serves is that session's to stop, and saying whose it is is the answer.
 				if (status.attached === true) {
 					ctx.ui.notify(
 						`board: nothing to stop here — ${status.seat} serves this repository on :${status.port}`,
@@ -48,7 +64,11 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 					);
 					return;
 				}
-				ctx.ui.notify((await page.stop(ctx)) ? "board: stopped" : "board: not running", "info");
+				const stopped = await page.stop();
+				// The word is this session saying it serves nothing now: the page clears the seat too
+				// when it closes itself (the idle grace), and both writes are the same fact.
+				session.serve(undefined);
+				ctx.ui.notify(stopped ? "board: stopped" : "board: not running", "info");
 				return;
 			}
 			if (word !== "" && word !== "team") {
@@ -59,15 +79,21 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 				return;
 			}
 			const started = await page.start(ctx, word === "team" ? "team" : "board");
-			// A failed start has already said why. Otherwise the join happens here, because
-			// opening the page is the lead's one action: the seat when this session serves it,
-			// this session's own label when it watches a page somebody else serves.
+			// A failed start has already said why. Otherwise the seat is set from the page's own
+			// answer — the page a session serves is a role, and every name this session writes and
+			// is addressed by follows from it — and the join happens here, because opening the page
+			// is the lead's one action.
 			if (started.kind === "failed") return;
-			joined = await team.join(ctx, joinLabel(started.kind === "served"));
+			session.serve(started.kind === "served" ? started.seat : undefined);
+			const joined = await team.join(ctx, { label: session.who(ctx, ctx.cwd).label });
+			session.team.record(joined);
+			// The address is on the line because the browser is not the only way in: a machine
+			// with no default browser prints it here, and a tab closed by mistake is one
+			// command from being opened again.
 			ctx.ui.notify(
 				started.kind === "attached"
-					? `board: ${started.seat} is serving this repository on :${started.port} — viewing${teamLine(joined)}`
-					: `board: ${started.seat} serving ${started.where} on :${started.port}${teamLine(joined)}`,
+					? `board: ${started.seat} is serving this repository on :${started.port} — viewing · open ${started.url}${teamLine(joined)}`
+					: `board: ${started.seat} serving ${started.repo} on :${started.port} · open ${started.url}${teamLine(joined)}`,
 				"info",
 			);
 		},
@@ -78,10 +104,15 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 export function statusLine(status: BoardPageStatus, team?: JoinResult): string {
 	if (status.running) {
 		const watching = plural(status.watchers ?? 0, "tab");
-		return `board: ${status.seat} serving on :${status.port} · ${watching} watching · ${status.where}${teamLine(team)}`;
+		return `board: ${status.seat} serving ${status.repo} on :${status.port} · ${watching} watching · ${status.where}${teamLine(team)}`;
+	}
+	if (status.stale === true) {
+		return `board: watching ${status.seat} on :${status.port} — that note answers nobody; /board stop drops it${teamLine(team)}`;
 	}
 	if (status.attached === true) {
 		return `board: watching ${status.seat} on :${status.port} — nothing to stop here${teamLine(team)}`;
 	}
-	return "board: not running — /board opens it";
+	// The team outlives the page: a session that claimed a card is on it with no page open, so
+	// the line says which team this session is on whichever door put it there.
+	return `board: not running — /board opens it${teamLine(team)}`;
 }