@gavin-hu/my-pi-agent 0.18.0 → 0.20.0

package/{extensions/worktree/README.md → docs/extensions/worktree.md}

@@ -7,73 +7,124 @@ exit, with cleanup that refuses to throw work away. The model keeps calling
 root changes. It is one of two sibling git extensions in this package
 (`rewind` is the other).
 
+## Capabilities
+
+Status records what a reader can rely on: **Shipped** is in a tagged release, **Unreleased** is complete in the current tree but not yet tagged, and **Partial** has one released part and one unreleased part. Rows are ordered by user value, highest first.
+
+### Isolating work
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Isolated checkout | `enter_worktree`, `/worktree enter`, `--worktree` | A new checkout at `<repo>/.pi/worktrees/<name>` on branch `worktree-<name>`, cut from `origin/main`. | Shipped |
+| Root-following built-ins | `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` | The built-in tools keep taking ordinary relative paths, resolved inside the worktree. | Shipped |
+| Escape refusal | `guard.blockFileEscapes`, `guard.blockGitRedirects`, `guard.blockSymlinkEscapes` | Writes, `cd`, and `git` redirects that reach the main checkout are refused, symlink escapes included. | Shipped |
+| Plan-mode refusal | `/worktree`, `enter_worktree` | In plan mode the screen opens read-only and every verb refuses until the plan is approved. | Shipped |
+| PowerShell refusal | `powershell` while isolated | The unparseable shell is refused instead of becoming an unguarded escape. | Shipped |
+| Seeded working copy | `.worktreeinclude`, `include` | Gitignored files such as `.env` are copied into each new worktree. | Shipped |
+| Ignore bootstrap | `enter_worktree` | The first worktree offers to add `.pi/worktrees` to `.gitignore`, so the checkout does not pollute status. | Shipped |
+| PR/MR checkout | `enter_worktree` `name`, `--worktree` | A pull or merge request's head is fetched and checked out as `pr-<n>`. | Shipped |
+| Child sessions | `PI_WORKTREE_ROOT`, `PI_WORKTREE_BRANCH`, `PI_WORKTREE_MAIN` | A `pi` started from a tool binds to the same worktree, read-only for lifecycle. | Shipped |
+
+### Returning and managing
+
+| Capability | How | What you get | Status |
+|---|---|---|---|
+| Return with a handoff | `exit_worktree`, `/worktree exit` | Back in the main checkout, with the branch, its commits, and the merge or PR command that finishes them. | Shipped |
+| Work that survives | `exit_worktree`, `worktree.onExit` | A worktree holding changes or commits is asked about or kept, never force-deleted. | Shipped |
+| Status inventory | `list_worktrees`, `/worktree` | The active root, the gaps isolation does not cover, and every managed worktree with its state. | Shipped |
+| Worktree screen | `/worktree` | One list screen with the focused worktree's path, base, and gaps, and the verbs to act on it. | Shipped |
+| Cleanup | `prune_worktrees`, `/worktree prune` | Clean, unused, old worktrees are removed; every other one is kept with a reason. | Shipped |
+| Concurrent-session safety | `enter_worktree`, `prune_worktrees` | A worktree in use is locked, so another session's sweep cannot remove it. | Shipped |
+| Session restore | `/resume`, `--continue` | An active worktree is restored from the branch, or reported gone. | Shipped |
+| Extension signal | `worktree:changed` | Another extension follows the active root without polling. | Shipped |
+| Doctor finding | `run_doctor` | A degraded `guard.blockPowershell` setting is named in the health report instead of only at use. | Shipped |
+
+## Quickstart
+
 ```bash
 pi --extension ./extensions/worktree   # load just this extension
 pi -e .                                # load the whole @gavin-hu/my-pi-agent package
 pi install ./                          # install the package
-pi -e . --worktree feature-auth        # load the package and enter a worktree at startup
 ```
 
-## Tool rendering
+```text
+/worktree                              # the list screen, or the same facts as text
+```
 
-How the `list_worktrees` call and its result look in the transcript — the call line as a headline and the body indented under it:
+The model enters with `enter_worktree`; `pi -e . --worktree feature-auth` starts
+the session already isolated.
+
+## Tools
 
 <img src="../../assets/tools/list_worktrees.png" alt="The list_worktrees tool's call and result, drawn by the generic fallback" width="100%">
 
-## The `/worktree` screen
+`enter_worktree` creates or enters a checkout, `exit_worktree` returns to the
+main checkout, and `prune_worktrees` and `list_worktrees` manage and report. All
+four are `executionMode: "sequential"`, and only `list_worktrees` is read-only.
 
-<img src="../../assets/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%">
+| 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`, `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. |
 
-`/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.
+`enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch
+`worktree-<name>` cut from `origin/main` (which can lag the local `main`), or
+enters an existing worktree by `path`, and rebinds the session's working root to
+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, 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:
+
+- writes/edits outside the worktree are refused, including through a symlink
+  that points at the main checkout;
+- `git -C <main>`, `GIT_DIR=`, `GIT_WORK_TREE=`, `--git-dir=`, `--work-tree=`,
+  and `cd` outside the worktree are refused in `bash`;
+- remote `git fetch` (the base ref and a PR/MR head) runs with terminal
+  prompting disabled, so a credentials prompt fails fast instead of hanging.
+
+### Status text
 
-| Key | |
-|---|---|
-| `j` / `k`, arrows | move |
-| `g` / `G` | first / last row |
-| Enter, `l` | open the selected worktree's detail |
-| `e` | enter the selected worktree |
-| `x` | exit the active worktree |
-| `p` | prune eligible worktrees in place |
-| Esc, `q` | close |
+`list_worktrees` (and a headless `/worktree`) reports the active worktree, any
+override that is not re-rooted, what isolation does not cover, and the managed
+worktrees:
 
-`e` and `x` close the screen before they act, because an exit asks through the
-normal prompt and a prompt cannot open inside a mounted screen. `p` never asks,
-so it prunes without closing and reports the result in the footer. In plan mode
-the screen still opens and every verb refuses with a notice.
+```text
+Not isolated:
+  ! shell       runs in the main checkout; Pi has no mutable session cwd
+  powershell    allowed by worktree.guard.blockPowershell: false; not re-rooted or guarded
+  unverifiable  $(...), backticks, eval, and sh -c pass through (blockUnparsableCommands is off); 2 ran this session
+```
+
+`powershell` appears only on Windows, with that tool active, and only when
+`guard.blockPowershell` lets it through — by default the guard refuses the call
+instead, so there is no gap to report. `unverifiable` appears only while
+`guard.blockUnparsableCommands` is off; its trailing count is this session's,
+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.
 
-## What it does
-
-- `enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch
-  `worktree-<name>` cut from `origin/main` (which can lag the local `main`), or
-  enters an existing worktree by `path`, and rebinds the session's working root
-  to 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`.
-- While isolated, `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` all resolve
-  relative paths inside the worktree, and:
-  - writes/edits outside the worktree are refused, including through a symlink
-    that points at the main checkout;
-  - `git -C <main>`, `GIT_DIR=`, `GIT_WORK_TREE=`, `--git-dir=`, `--work-tree=`,
-    and `cd` outside the worktree are refused in `bash`;
-  - network `git fetch` runs with terminal prompting disabled, so a credentials
-    prompt fails fast instead of hanging.
-- State is stored as a custom session entry, so `/resume` (and `--continue`)
-  restores an active worktree, or reports when it is gone.
+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 |
 |---|---|
 | `/worktree` | the list screen: managed worktrees, the active one, and its gaps |
 | `/worktree enter [name]` | enter a worktree (a name may be a PR/MR reference) |
@@ -89,37 +140,42 @@ outside path, exiting a worktree with work) is reported as normal feedback, not
 an error. An argument a subcommand does not take prints the usage line instead of
 being ignored.
 
-`list_worktrees` (and a headless `/worktree`) reports the active worktree, any
-override that is not re-rooted, what isolation does not cover, and the managed
-worktrees:
-
-```text
-Not isolated:
-  ! shell       runs in the main checkout; Pi has no mutable session cwd
-  powershell    allowed by worktree.guard.blockPowershell: false; not re-rooted or guarded
-  unverifiable  $(...), backticks, eval, and sh -c pass through (blockUnparsableCommands is off); 2 ran this session
-```
-
-`powershell` appears only on Windows, with that tool active, and only when
-`guard.blockPowershell` lets it through — by default the guard refuses the call
-instead, so there is no gap to report. `unverifiable` appears only while
-`guard.blockUnparsableCommands` is off; its trailing count is this session's,
-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.
+### The /worktree screen
 
-The model surface mirrors this with four tools:
+<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%">
 
-| Tool | Usage |
+`/worktree` on its own opens a list screen: one row per managed worktree with its
+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 |
 |---|---|
-| `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`). |
-| `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. |
+| `j` / `k`, arrows | move |
+| `g` / `G` | first / last row |
+| Enter, `l` | open the selected worktree's detail |
+| `e` | enter the selected worktree |
+| `x` | exit the active worktree |
+| `p` | prune eligible worktrees in place |
+| Esc, `q` | close |
+
+`e` and `x` close the screen before they act, because an exit asks through the
+normal prompt and a prompt cannot open inside a mounted screen. `p` never asks,
+so it prunes without closing and reports the result in the footer. In plan mode
+the screen still opens and every verb refuses with a notice.
 
 ## Configuration
 
-The `worktree` section of the shared `bytefly.json` (global document, then
-`<repo>/.pi/bytefly.json`, project wins):
+The `worktree` section of the shared `bytefly.json`; the project document is read
+from the repository root rather than the active working directory, and the
+project wins. Resolution rules are in
+[`../configuration.md#worktree--isolated-worktrees`](../configuration.md#worktree--isolated-worktrees),
+which also lists every key with its default and accepted values.
 
 ```jsonc
 // bytefly.json → "worktree"
@@ -255,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
@@ -287,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`. |
@@ -364,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

@@ -0,0 +1,105 @@
+/**
+ * `/board` — the page's one entry point.
+ *
+ * Three words, and everything else opens the page: `team` opens it on the Team tab,
+ * `status` prints one line, `stop` closes it. The command is a thin parser over the
+ * lifecycle in `page.ts`, so the idle grace and `session_shutdown` close the same
+ * server this opens.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { plural } from "../../lib/board/round-text.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 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;
+
+export function registerCommands(pi: ExtensionAPI, 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) => {
+			const text = prefix.trimStart();
+			if (text.includes(" ")) return null;
+			const items = BOARD_WORDS.filter((word) => word.startsWith(text));
+			return items.length > 0 ? items.map((value) => ({ value, label: value })) : null;
+		},
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const word = args.trim().toLowerCase();
+			if (word === "status") {
+				ctx.ui.notify(statusLine(await page.status(), joined), "info");
+				return;
+			}
+			if (word === "stop") {
+				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}`,
+						"info",
+					);
+					return;
+				}
+				ctx.ui.notify((await page.stop(ctx)) ? "board: stopped" : "board: not running", "info");
+				return;
+			}
+			if (word !== "" && word !== "team") {
+				ctx.ui.notify(
+					`board: "${word}" is not a word this command knows — try /board, /board team, /board status, /board stop`,
+					"warning",
+				);
+				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.
+			if (started.kind === "failed") return;
+			joined = await team.join(ctx, joinLabel(started.kind === "served"));
+			// 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 · open ${started.url}${teamLine(joined)}`
+					: `board: ${started.seat} serving ${started.where} on :${started.port} · open ${started.url}${teamLine(joined)}`,
+				"info",
+			);
+		},
+	});
+}
+
+/** One line for `/board status`: the page this session serves, watches, or does not have. */
+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)}`;
+	}
+	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";
+}

package/extensions/board/config.ts

@@ -0,0 +1,36 @@
+/**
+ * The board's one setting: the port its page is pinned to.
+ *
+ * The `board` section of the shared `bytefly.json` (global then project, project
+ * wins). `0` — the default — takes one free port for the session and remembers it,
+ * which is what a session that never bookmarks its URL wants; a positive value pins
+ * the page, so a bookmarked URL survives a restart. A pinned port that is taken
+ * fails the start rather than moving the page out from under the bookmark.
+ *
+ * Pin it in the project document when more than one repository runs a board: a
+ * global value is one port for every board on the machine.
+ */
+
+import { clampInteger, loadConfigSection } from "../../lib/config.ts";
+
+/** The `board` section. */
+export interface BoardConfig {
+	/** TCP port on `127.0.0.1`; `0` picks one for the session, a positive value pins it. */
+	port: number;
+}
+
+export const DEFAULT_BOARD_CONFIG: BoardConfig = { port: 0 };
+
+/** Validate and clamp a raw config object over the defaults. */
+export function normalizeBoardConfig(
+	raw: Record<string, unknown> | undefined,
+	base: BoardConfig = DEFAULT_BOARD_CONFIG,
+): BoardConfig {
+	if (!raw) return base;
+	return { port: clampInteger(raw.port, base.port, 0, 65_535) };
+}
+
+/** Load the effective config for a working directory. */
+export function loadBoardConfig(cwd: string): BoardConfig {
+	return loadConfigSection(cwd, "board", DEFAULT_BOARD_CONFIG, normalizeBoardConfig);
+}

package/extensions/board/format.ts

@@ -0,0 +1,170 @@
+/**
+ * The model-facing text for one card or one listing.
+ *
+ * Text is the model's channel, so it carries the facts a next decision needs — the
+ * id, the lane, who holds it, whether it is planned, how urgent it is, and what it
+ * waits for — and the renderer carries the styling. Ages and sizes stay out: a note is
+ * read for what it says, and the page is where "3m ago" belongs.
+ *
+ * `board` is optional because a single card's answer sometimes comes without the rest
+ * of the board: the ids are still named, and only the lane of each dependency is lost.
+ * The rollup's text is `lib/board/round-text.ts`, because `team` prints it too.
+ */
+
+import { type Card, cardRef, DEFAULT_PRIORITY, dependsOf, priorityOf } from "../../lib/board/card.ts";
+import { type BoardIndex, lanesText, openDependentsOf } from "../../lib/board/links.ts";
+import type { Skip } from "../../lib/board/store.ts";
+import { formatAge } from "../../lib/format.ts";
+import { plural } from "../../lib/board/round-text.ts";
+
+/** One card: the headline, then the state a reader needs in order to act on it. */
+export function formatCard(card: Card, board?: BoardIndex, now?: number): string {
+	return [`${cardRef(card.id)} ${card.status} · ${card.title}`, ...detailLines(card, board, now)].join("\n");
+}
+
+/**
+ * What a listing cannot show, and therefore has to say.
+ *
+ * A footnote is the difference between a listing and the board: an omission nobody
+ * accounted for reads as a smaller board — or as history that was deleted.
+ */
+export interface ListingNotes {
+	/** Finished cards the board holds that a lane-less listing left out. */
+	hiddenDone: number;
+	/** Cards set aside in the archive, which no board read opens. */
+	archived: number;
+	/** Card files this build could not read. */
+	skipped: readonly Skip[];
+}
+
+/**
+ * A board's listing: the cards, then the footnotes a reader cannot see.
+ *
+ * One body, because the footnotes belong to the listing: a card file this build cannot
+ * read, the finished cards a plain listing left out, and the cards an `archive` set aside.
+ */
+export function formatBoard(shown: readonly Card[], notes: ListingNotes): string {
+	const lines =
+		shown.length === 0 ? [notes.hiddenDone === 0 ? "The board is empty." : "No open cards."] : shown.map(listLine);
+	// A finished card is history rather than work, so a listing that names no lane leaves
+	// them out; the count is what keeps the omission from reading as a smaller board.
+	if (notes.hiddenDone > 0) {
+		const them = notes.hiddenDone === 1 ? "it" : "them";
+		lines.push(`${plural(notes.hiddenDone, "done card")} hidden; pass status: "done" to read ${them}.`);
+	}
+	for (const note of [archiveNote(notes.archived), formatSkipped(notes.skipped)]) {
+		if (note !== "") lines.push(note);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * The archive's listing: what is set aside, and the files there this build refused.
+ *
+ * The archive is read on request only, so this has no lane footnote of its own — every
+ * card in the pile is finished, and a `done` lane would be a second way to say it.
+ */
+export function formatArchive(shown: readonly Card[], skipped: readonly Skip[]): string {
+	const lines = shown.length === 0 ? ["The archive is empty."] : shown.map(listLine);
+	const unreadable = formatSkipped(skipped);
+	if (unreadable !== "") lines.push(unreadable);
+	return lines.join("\n");
+}
+
+/**
+ * The one sentence a board listing adds so its archive is not mistaken for deleted history.
+ *
+ * Empty when nothing is set aside, so the ordinary board says nothing new.
+ */
+export function archiveNote(count: number): string {
+	if (count === 0) return "";
+	return `${plural(count, "card")} ${count === 1 ? "is" : "are"} set aside in the archive; pass archived: true to read ${count === 1 ? "it" : "them"}.`;
+}
+
+/**
+ * The files the board could not read, or nothing when it read everything.
+ *
+ * A skipped file is not an absent one: a board written by a newer build would
+ * otherwise read as "nobody has planned anything" while the work sits on disk.
+ */
+export function formatSkipped(skipped: readonly Skip[]): string {
+	if (skipped.length === 0) return "";
+	const files = skipped.map((entry) => `${entry.file} (${entry.why})`).join(", ");
+	return `${plural(skipped.length, "file")} this build cannot read: ${files}`;
+}
+
+/** The dropped id, which is the only thing left of the card. */
+export function formatDropped(id: string): string {
+	return `${cardRef(id)} dropped, with its notes.`;
+}
+
+/**
+ * The ids an archive set aside, and how to read them again.
+ *
+ * A move has to name the way back or it reads like a deletion: the card is out of the
+ * board and its notes, plan, and landed commit are still in its file.
+ */
+export function formatArchived(ids: readonly string[]): string {
+	const theirs = ids.length === 1 ? "its" : "their";
+	return `${plural(ids.length, "card")} archived: ${ids.map(cardRef).join(", ")} — out of the board, ${theirs} notes and plan still readable with archived: true.`;
+}
+
+/** A one-line listing: the id, the lane, the title, and who holds it. */
+function listLine(card: Card): string {
+	const holder = card.owner === undefined ? "unassigned" : card.owner.label;
+	const urgency = priorityOf(card) === DEFAULT_PRIORITY ? "" : ` · ${priorityOf(card)}`;
+	const waits = dependsOf(card).length === 0 ? "" : ` · waits on ${dependsOf(card).map(cardRef).join(", ")}`;
+	// The two lanes that carry a fact of their own say it here: what a block waits on, and
+	// what closed a finished card. Both are one short phrase, so a listing stays one line.
+	const blocked = card.blockedBy === undefined ? "" : ` · blocked: ${card.blockedBy}`;
+	const landed = card.landed === undefined ? "" : ` · landed ${card.landed.commit}`;
+	return `${cardRef(card.id)} ${card.status} · ${card.title} · ${holder}${urgency}${waits}${blocked}${landed}`;
+}
+
+/** The state lines under a card's headline. */
+function detailLines(card: Card, board?: BoardIndex, now?: number): string[] {
+	const lines: string[] = [];
+	if (card.owner !== undefined) lines.push(`  owner: ${card.owner.label}`);
+	// An offer's age is the fact a reader acts on, which is the one place an age belongs in
+	// this text: the value is whether anybody has had time to answer.
+	if (card.offeredAt !== undefined && now !== undefined) {
+		lines.push(`  offered: ${formatAge(now, card.offeredAt)} ago, and nobody took it`);
+	}
+	if (card.blockedBy !== undefined) lines.push(`  blocked: ${card.blockedBy}`);
+	if (card.landed !== undefined) lines.push(`  landed: ${card.landed.commit}`);
+	if (priorityOf(card) !== DEFAULT_PRIORITY) lines.push(`  priority: ${priorityOf(card)}`);
+	if (card.plan !== undefined) lines.push(`  plan: ${card.plan}`);
+	if (card.paths.length > 0) lines.push(`  paths: ${card.paths.join(", ")}`);
+	if (dependsOf(card).length > 0) lines.push(`  waits on: ${waitingOf(card, board)}`);
+	// The mirror question, for the same board: what leaving this card undone holds up. Only
+	// a card with the board in hand can answer it, which is why a bare card read omits it.
+	if (board !== undefined) {
+		const dependents = openDependentsOf(card.id, board);
+		if (dependents.length > 0) {
+			const which = dependents.length === 1 ? "card" : "cards";
+			lines.push(`  waited on by ${dependents.length} ${which}: ${lanesText(dependents)}`);
+		}
+	}
+	if (card.notes.length > 0) {
+		const last = card.notes.at(-1);
+		if (last) lines.push(`  last note (${last.by}): ${last.text}`);
+	}
+	const dropped = card.notesDropped > 0 ? ` (${card.notesDropped} earlier dropped)` : "";
+	lines.push(`  ${plural(card.notes.length, "note")}${dropped}`);
+	return lines;
+}
+
+/**
+ * The cards a card waits on, each with its lane when the board is there to say it.
+ *
+ * The lane is what turns a list of ids into a decision: `#2 (done)` is a card about to
+ * start, and `#2 (doing)` is one to leave alone.
+ */
+function waitingOf(card: Card, board: BoardIndex | undefined): string {
+	return dependsOf(card)
+		.map((id) => {
+			const blocker = board?.get(id);
+			return blocker === undefined ? cardRef(id) : `${cardRef(id)} (${blocker.status})`;
+		})
+		.join(", ");
+}

package/extensions/board/index.ts

@@ -0,0 +1,40 @@
+/**
+ * board — one shared feature board per repository.
+ *
+ * Every Pi session on a repository reads and writes the same cards, and `/board`
+ * serves them as a page in the browser that follows the store live. A card is one
+ * *feature*, not one step: the steps of the work live in the owner's plan and in
+ * `todo`, and the board answers who is doing what and what needs a decision.
+ *
+ * The factory only registers. The store is opened on first use by the session, the
+ * page starts when `/board` asks for it, and `session_shutdown` closes it — so a
+ * session that never touches the board writes nothing and binds nothing.
+ *
+ * Load with:  pi --extension ./extensions/board
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isExtensionEnabled } from "../../lib/env.ts";
+import { registerCommands } from "./commands.ts";
+import { type BoardPage, createBoardPage } from "./page.ts";
+import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
+import { registerTools } from "./tools.ts";
+
+export interface BoardDeps {
+	/** Test seam: a session with a temp agent directory and a fixed clock. */
+	session?: BoardSession;
+	/** Test seam: the page lifecycle, so a test drives it without a socket. */
+	page?: BoardPage;
+}
+
+export default function board(pi: ExtensionAPI, deps: BoardDeps = {}): void {
+	if (!isExtensionEnabled("board")) return;
+	const session = deps.session ?? openBoardSession(pi);
+	const page = deps.page ?? createBoardPage(session);
+	registerTools(pi, session);
+	registerCommands(pi, page);
+
+	pi.on("session_shutdown", async () => {
+		await page.closeAll();
+	});
+}