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

package/docs/extensions/worktree.md

@@ -9,35 +9,33 @@ root changes. It is one of two sibling git extensions in this package
 
 ## 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Isolated checkout | `worktree` action `enter`, `/worktree enter`, `--worktree` | A new checkout at `<repo>/.pi/worktrees/<name>` on branch `worktree-<name>`, cut from `origin/main`. |
+| Root-following built-ins | `read`, `write`, `edit`, `bash`, `grep`, `find`, `ls` | The built-in tools keep taking ordinary relative paths, resolved inside the worktree. |
+| Escape refusal | `guard.blockFileEscapes`, `guard.blockGitRedirects`, `guard.blockSymlinkEscapes` | Writes, `cd`, and `git` redirects that reach the main checkout are refused, symlink escapes included. |
+| Plan-mode refusal | `/worktree`, `worktree` action `enter` | In plan mode the screen opens read-only and every verb refuses until the plan is approved. |
+| PowerShell refusal | `powershell` while isolated | The unparseable shell is refused instead of becoming an unguarded escape. |
+| Seeded working copy | `.worktreeinclude`, `include` | Gitignored files such as `.env` are copied into each new worktree. |
+| Ignore bootstrap | `worktree` action `enter` | The first worktree offers to add `.pi/worktrees` to `.gitignore`, so the checkout does not pollute status. |
+| PR/MR checkout | `worktree` action `enter` with `name`, `--worktree` | A pull or merge request's head is fetched and checked out as `pr-<n>`. |
+| 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. |
 
 ### 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 |
+| Capability | How | What you get |
+|---|---|---|
+| Return with a handoff | `worktree` action `exit`, `/worktree exit` | Back in the main checkout, with the branch, its commits, and the merge or PR command that finishes them. |
+| Work that survives | `worktree` action `exit`, `worktree.onExit` | A worktree holding changes or commits is asked about or kept, never force-deleted. |
+| Status inventory | `worktree` action `list`, `/worktree` | The active root, the gaps isolation does not cover, and every managed worktree with its state. |
+| Worktree screen | `/worktree` | One list screen with the focused worktree's path, base, and gaps, and the verbs to act on it. |
+| Cleanup | `worktree` action `prune`, `/worktree prune` | Clean, unused, old worktrees are removed; every other one is kept with a reason. |
+| Concurrent-session safety | `worktree` actions `enter` and `prune` | A worktree in use is locked, so another session's sweep cannot remove it. |
+| Session restore | `/resume`, `--continue` | An active worktree is restored from the branch, or reported gone. |
+| Extension signal | `worktree:changed` | Another extension follows the active root without polling. |
+| Doctor finding | `run_doctor` | A degraded `guard.blockPowershell` setting is named in the health report instead of only at use. |
 
 ## Quickstart
 
@@ -51,30 +49,32 @@ pi install ./                          # install the package
 /worktree                              # the list screen, or the same facts as text
 ```
 
-The model enters with `enter_worktree`; `pi -e . --worktree feature-auth` starts
+The model enters with `worktree` action `enter`; `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%">
+<img src="../../assets/tools/worktree-list.png" alt="The worktree tool's list action: the call line and the indented status it reports" width="100%">
 
-`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.
+One tool with four actions — `enter`, `exit`, `list`, `prune` — because they are
+one lifecycle. It is `executionMode: "sequential"` and takes the strictest
+annotation of the four, `destructiveHint: true` with `openWorldHint: true`,
+because `enter` writes into the checkout the session is bound to; `list` writes
+nothing, and the fold cannot say that with one hint.
 
-| Tool | Usage |
+| Action | 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. |
+| `enter` | `name` to create a worktree, or `path` to enter an existing one. Errors if already isolated. |
+| `exit` | optional `remove` and `keepBranch`. Returns the clean/keep/remove decision and a `handoff` (`branch`, `base`, `ahead`, `commits`, `merged`). |
+| `list` | no fields. Read-only status: active root, inactive overrides, isolation gaps, managed worktrees. |
+| `prune` | no fields. Removes eligible managed worktrees and reports the rest. |
 
-`enter_worktree` creates `<repo>/.pi/worktrees/<name>` on branch
+`enter` 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
+`exit` 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
@@ -98,7 +98,7 @@ relative paths inside the worktree, and:
 
 ### Status text
 
-`list_worktrees` (and a headless `/worktree`) reports the active worktree, any
+`list` (and a headless `/worktree`) reports the active worktree, any
 override that is not re-rooted, what isolation does not cover, and the managed
 worktrees:
 
@@ -151,7 +151,7 @@ pane for the selected one. A worktree that has not committed since it was create
 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`
+facts print as text instead, which is also what the model's `list` action
 reads.
 
 | Key | What it does |
@@ -204,10 +204,10 @@ which also lists every key with its default and accepted values.
 tool names: Pi refuses to load two extensions that register the same tool, so
 exclude the name here to load alongside it. It is read when the extension
 loads, from the process working directory; reload after changing it. `/worktree`
-and `list_worktrees` list any overridden tool that is not re-rooted.
+and `worktree` action `list` name any overridden tool that is not re-rooted.
 
 `.gitignore` must cover the managed directory, or worktrees show up as untracked
-files in the main checkout. `enter_worktree` offers once per session to append
+files in the main checkout. `enter` offers once per session to append
 `.pi/worktrees/`, and skips the offer when `git check-ignore` already reports the
 directory as ignored, so a wider rule is enough and no literal line is needed:
 
@@ -266,7 +266,7 @@ config/secrets.json
 
 ## Pull / merge requests
 
-`enter_worktree` accepts a PR/MR reference in `name`, as does the startup flag:
+`enter` accepts a PR/MR reference in `name`, as does the startup flag:
 
 ```
 pi --worktree '#1234'
@@ -282,8 +282,8 @@ While isolated, the extension exports `PI_WORKTREE_ROOT`, `PI_WORKTREE_BRANCH`,
 and `PI_WORKTREE_MAIN` (the main checkout) into the process environment. A child
 `pi` process — a subagent spawned by an extension, or any `pi` you start from a
 tool — inherits it and binds to the same worktree instead of the main checkout.
-The child is read-only with respect to lifecycle: `enter_worktree` and
-`exit_worktree` refuse, and the parent owns cleanup.
+The child is read-only with respect to lifecycle: `enter` and `exit`
+refuse, and the parent owns cleanup.
 
 Extensions can also follow changes on the `pi.events` channel
 `worktree:changed`, which receives `{ active, path, branch, borrowed }`.
@@ -292,7 +292,7 @@ Extensions can also follow changes on the `pi.events` channel
 
 Entering a managed worktree takes a `git worktree lock` (reason
 `pi:<pid>:<session>`), so a concurrent sweep cannot remove it; exiting and
-shutdown release it. `/worktree prune` (or the `prune_worktrees` tool) removes
+shutdown release it. `/worktree prune` (or `worktree` action `prune`) removes
 managed worktrees that are clean, have no new commits, are not the current or a
 live-locked one, and are older than `pruneAfterDays`. It releases locks whose
 owning process is gone first, and any failure keeps the worktree with a reason.
@@ -308,7 +308,7 @@ use, falling back to directory mtime for a worktree with no record.
   extension owns `bash` (or another overridden name), set
   `skipOverrides: ["bash"]` so this extension does not register it; that tool
   then runs in the main checkout with **no re-rooting**, so only its absolute
-  writes are guarded (relative paths are not isolated), and `list_worktrees`
+  writes are guarded (relative paths are not isolated), and `list`
   reports it. `skipOverrides` is read at load time, from the process working
   directory.
 - The commit count behind `no commits` comes from the commit a worktree was
@@ -323,11 +323,15 @@ use, falling back to directory mtime for a worktree with no record.
 - Only the model's `bash` tool is re-rooted and guarded. A shell command the
   user runs directly (`!` in the TUI / the `user_bash` event) is not re-rooted
   and still runs in the main checkout; Pi has no mutable session cwd to change
-  that. `/worktree` and `list_worktrees` report the active root, and list the
+  that. `/worktree` and `list` report the active root, and list the
   shell under `Not isolated:` on every status read.
 - Windows `powershell` is refused while isolated, or — with
   `guard.blockPowershell: false` — allowed and unguarded. There is no third
   state: a parsed PowerShell command that keeps the tool.
+- **`list` is not available while planning.** One annotation set cannot be both
+  read-only and destructive, so plan mode hides the whole tool and a planning
+  session reads the inventory with `/worktree` instead. A per-tool filter is
+  all-or-nothing for the same reason, so disabling `worktree` loses every verb.
 
 ## Non-goals
 
@@ -344,7 +348,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, commits, merged }` (`commits` absent when the worktree has no recorded base commit). |
+| Tools | one `worktree` tool via `registerTool`, with four actions (`enter`, `exit`, `list`, `prune`), `executionMode: "sequential"`, and one annotation set for all four: `destructiveHint: true`, `openWorldHint: true` — the strictest, because `enter` writes into the checkout the session is bound to. The block is bytefly's generic fallback, as the four tools' was: the verb reads as the subject and its fields as the aside (`worktree enter (name feat)`, `worktree list`). No `outputSchema`; structured state is returned in tool-result `details` discriminated by `action` — `exit` carries `{ action, 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`. |
@@ -389,7 +393,7 @@ one read and two renderings.
   `--continue` restore the binding or report accurately when the directory is
   gone; the registry is reconciled against `git worktree list` on every
   management read and is never the source of truth.
-- **Never force out work.** `exit_worktree` never force-deletes a branch that
+- **Never force out work.** `exit` never force-deletes a branch that
   still holds uncommitted changes or commits not reachable from the recorded
   base, even with `remove: true`.
 - **A handoff is read, not performed.** The exit reports the branch's state and
@@ -416,7 +420,7 @@ one read and two renderings.
 | `errors.ts` | Cancellation error that distinguishes a user decline from a failure |
 | `enter.ts` / `exit.ts` / `prune.ts` | The lifecycle phases |
 | `handoff.ts` | The `Handoff:` block an exit leaves: the branch's lead, whether the base contains it, and the merge or PR command. |
-| `tools.ts` / `commands.ts` | Model tools / slash commands |
+| `tools.ts` / `commands.ts` | The one model tool and its four actions / slash commands |
 | `screen.ts` | The `/worktree` list screen: rows, keys, detail pane, and verbs |
 | `root-tools.ts` | Load-time built-in overrides bound to the active root |
 | `git.ts` | Git plumbing (shared runner + read helpers) |
@@ -436,7 +440,9 @@ bun run test:watch
 ```
 
 The suite covers the pure logic (`include.ts` gitignore matcher, `guard.ts` path
-and command checks, `parsePrReference`), drives the `/worktree` screen against a
+and command checks, `parsePrReference`), the folded tool's own surface
+(`tools.test.ts`: the four actions in one schema and its annotations), drives the
+`/worktree` screen against a
 snapshot (`ui.test.ts`: rows, marks, verbs, and width bounds), and drives the
 extension end-to-end against real temporary git repositories through a mocked
 `pi` API: enter/exit, isolation guards, borrowed worktrees, prune, and

package/extensions/board/commands.ts

@@ -1,31 +1,39 @@
 /**
- * `/board` — the page's one entry point.
+ * `/board` — the page's one entry point, and the person's door to the two signs.
  *
- * 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.
+ * `team` opens the page on the Team tab, `status` prints one line, `stop` closes it, and
+ * `approve <id>` / `review <id>` write the two signs as the person at the keyboard, which is what
+ * a session that is not the board's lead cannot do. Everything else opens the page. The command
+ * is a thin parser — the lifecycle is `page.ts`'s, the transitions are `lib/board/steps.ts`'s —
+ * so the idle grace and `session_shutdown` close the same server this opens.
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { cardRef, normalizeCardId } from "../../lib/board/card.ts";
+import { PERSON_LABEL, personActor, type Sign, signOf } from "../../lib/board/lead.ts";
 import { plural } from "../../lib/board/round-text.ts";
+import { type BoardSession } 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 = ["approve", "review", "status", "stop", "team"] as const;
 
-export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team?: TeamJoin } = {}): void {
+export function registerCommands(
+	pi: ExtensionAPI,
+	session: BoardSession,
+	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]",
+		description:
+			"Open the shared board in a local browser, or sign its two gates as the person: /board [team | status | stop | approve <id> | review <id>]",
 		getArgumentCompletions: (prefix: string) => {
 			const text = prefix.trimStart();
 			if (text.includes(" ")) return null;
@@ -33,9 +41,14 @@ export function registerCommands(pi: ExtensionAPI, page: BoardPage, deps: { team
 			return items.length > 0 ? items.map((value) => ({ value, label: value })) : null;
 		},
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
-			const word = args.trim().toLowerCase();
+			const [word = "", rawCard] = args.trim().toLowerCase().split(/\s+/);
+			const sign = signOf(word);
+			if (sign !== undefined) {
+				ctx.ui.notify(await signLine(session, sign, rawCard, ctx), "info");
+				return;
+			}
 			if (word === "status") {
-				ctx.ui.notify(statusLine(await page.status(), joined), "info");
+				ctx.ui.notify(statusLine(await page.status(), session.team.last()), "info");
 				return;
 			}
 			if (word === "stop") {
@@ -60,40 +73,79 @@ 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") {
-				ctx.ui.notify(
-					`board: "${word}" is not a word this command knows — try /board, /board team, /board status, /board stop`,
-					"warning",
-				);
+				ctx.ui.notify(`board: "${word}" is not a word this command knows — try ${wordHelp()}`, "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.
+			// 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: (await 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 · open ${started.url}${teamLine(joined)}`
-					: `board: ${started.seat} serving ${started.where} on :${started.port} · open ${started.url}${teamLine(joined)}`,
+					: `board: ${started.seat} serving ${started.repo} on :${started.port} · open ${started.url}${teamLine(joined)}`,
 				"info",
 			);
 		},
 	});
 }
 
+/** The words, as the warning that names them: a sign takes a card, and nothing else does. */
+function wordHelp(): string {
+	return BOARD_WORDS.map((entry) => (signOf(entry) === undefined ? `/board ${entry}` : `/board ${entry} <id>`)).join(
+		", ",
+	);
+}
+
+/**
+ * Sign one of the card's two gates as the person at the keyboard.
+ *
+ * The write is the same `mutate` the tool uses, so the rules are the state machine's: an
+ * `approve` outside `plan`, a `review` outside `execute`, an unknown id, and a card already
+ * signed are each refused with the sentence the tool would give. The one thing that differs
+ * is the actor — the person, whose id no session can have — which is what makes the sign a
+ * sign even when the session that typed it holds the card.
+ */
+async function signLine(
+	session: BoardSession,
+	sign: Sign,
+	rawCard: string | undefined,
+	ctx: ExtensionCommandContext,
+): Promise<string> {
+	const id = rawCard === undefined ? undefined : normalizeCardId(rawCard);
+	if (id === undefined) {
+		return `board: ${sign} needs a card id — try /board ${sign} 4`;
+	}
+	const store = await session.store(ctx.cwd);
+	const result = await store.mutate(id, { kind: sign }, personActor(), session.now());
+	if (!result.ok) return `board: ${result.error}`;
+	const done = sign === "approve" ? "approved" : "reviewed";
+	return result.changed
+		? `board: ${cardRef(id)} ${done} by ${PERSON_LABEL}`
+		: `board: ${cardRef(id)} is already ${done} by ${PERSON_LABEL}`;
+}
+
 /** 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)}`;
+		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)}`;
@@ -101,5 +153,7 @@ export function statusLine(status: BoardPageStatus, team?: JoinResult): string {
 	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)}`;
 }

package/extensions/board/format.ts

@@ -11,15 +11,26 @@
  * 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 Card, type CardBlock, cardRef, DEFAULT_PRIORITY, dependsOf, priorityOf } from "../../lib/board/card.ts";
 import { type BoardIndex, lanesText, openDependentsOf } from "../../lib/board/links.ts";
+import { skippedText } from "../../lib/board/skipped.ts";
 import type { Skip } from "../../lib/board/store.ts";
-import { formatAge } from "../../lib/format.ts";
+import { formatAge, shortenPath } from "../../lib/format.ts";
 import { plural } from "../../lib/board/round-text.ts";
 
+/**
+ * What a claim adds to the card: the next step, in the order the board enforces.
+ *
+ * A claim is the one call that commits a session to a card, and the board will not record
+ * that card's plan until one exists — so the call that opens the work is the one place the
+ * order has to be said. It is a line of the transcript, not a field: nothing reads it back.
+ */
+export const CLAIM_NEXT =
+	"  next: design it in plan mode, `plan` action `write`, then `contract` with the path it returned";
+
 /** 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");
+	return [`${cardRef(card.id)} ${card.lane} · ${card.title}`, ...detailLines(card, board, now)].join("\n");
 }
 
 /**
@@ -50,9 +61,9 @@ export function formatBoard(shown: readonly Card[], notes: ListingNotes): string
 	// 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}.`);
+		lines.push(`${plural(notes.hiddenDone, "done card")} hidden; pass lane: "done" to read ${them}.`);
 	}
-	for (const note of [archiveNote(notes.archived), formatSkipped(notes.skipped)]) {
+	for (const note of [archiveNote(notes.archived), skippedText(notes.skipped)]) {
 		if (note !== "") lines.push(note);
 	}
 	return lines.join("\n");
@@ -66,7 +77,7 @@ export function formatBoard(shown: readonly Card[], notes: ListingNotes): string
  */
 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);
+	const unreadable = skippedText(skipped);
 	if (unreadable !== "") lines.push(unreadable);
 	return lines.join("\n");
 }
@@ -81,18 +92,6 @@ export function archiveNote(count: number): string {
 	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.`;
@@ -109,6 +108,12 @@ export function formatArchived(ids: readonly string[]): string {
 	return `${plural(ids.length, "card")} archived: ${ids.map(cardRef).join(", ")} — out of the board, ${theirs} notes and plan still readable with archived: true.`;
 }
 
+/** A block as one line: the sentence, and the kind beside it when one was recorded. */
+function blockText(block: CardBlock): string {
+	const note = block.note ?? "nothing recorded";
+	return block.kind === undefined ? note : `${note} (${block.kind})`;
+}
+
 /** 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;
@@ -116,9 +121,9 @@ function listLine(card: Card): string {
 	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 blocked = card.blocked === undefined ? "" : ` · blocked: ${blockText(card.blocked)}`;
 	const landed = card.landed === undefined ? "" : ` · landed ${card.landed.commit}`;
-	return `${cardRef(card.id)} ${card.status} · ${card.title} · ${holder}${urgency}${waits}${blocked}${landed}`;
+	return `${cardRef(card.id)} ${card.lane} · ${card.title} · ${holder}${urgency}${waits}${blocked}${landed}`;
 }
 
 /** The state lines under a card's headline. */
@@ -130,10 +135,24 @@ function detailLines(card: Card, board?: BoardIndex, now?: number): string[] {
 	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.blocked !== undefined) lines.push(`  blocked: ${blockText(card.blocked)}`);
 	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}`);
+	// The card stores the path resolved, so the line is shortened the way the `write` action shows
+	// it: an absolute home directory is noise in every read of the same card.
+	if (card.planPath !== undefined) lines.push(`  plan: ${shortenPath(card.planPath)}`);
+	// The contract is what a reader is asked to agree to, so the block says it in full and
+	// says who signed it: an approval is a fact about that wording, and a review about the
+	// work, and neither is inferable from the lane.
+	if (card.contract !== undefined) {
+		lines.push(`  goal: ${card.contract.goal}`);
+		lines.push(`  acceptance: ${card.contract.acceptance}`);
+		lines.push(`  scope out: ${card.contract.scopeOut}`);
+		const approved = card.contract.approved;
+		lines.push(`  approved: ${approved === undefined ? "nobody yet" : approved.by}`);
+	}
+	if (card.review !== undefined) lines.push(`  reviewed: ${card.review.by}`);
+
 	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
@@ -158,13 +177,13 @@ function detailLines(card: Card, board?: BoardIndex, now?: number): string[] {
  * 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.
+ * start, and `#2 (execute)` 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})`;
+			return blocker === undefined ? cardRef(id) : `${cardRef(id)} (${blocker.lane})`;
 		})
 		.join(", ");
 }

package/extensions/board/index.ts

@@ -4,7 +4,7 @@
  * 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.
+ * `todo`, and the board answers who is holding 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
@@ -15,8 +15,10 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { requestMount } from "../../lib/http/mount.ts";
 import { registerCommands } from "./commands.ts";
-import { type BoardPage, createBoardPage } from "./page.ts";
+import { createLazyBoardPage } from "./lazy-page.ts";
+import type { BoardPage } from "./page.ts";
 import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
 import { registerTools } from "./tools.ts";
 
@@ -30,9 +32,20 @@ export interface BoardDeps {
 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);
+	/** The session the page serves as; the mount lands on this session's one server. */
+	let sessionId = "";
+	const page =
+		deps.page ??
+		createLazyBoardPage(session, {
+			mount: (spec) => requestMount(pi, spec),
+			session: () => sessionId,
+		});
 	registerTools(pi, session);
-	registerCommands(pi, page);
+	registerCommands(pi, session, page);
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionId = ctx.sessionManager.getSessionId();
+	});
 
 	pi.on("session_shutdown", async () => {
 		await page.closeAll();

package/extensions/board/input.ts

@@ -1,14 +1,9 @@
 /**
- * A card body as both surfaces read it: the tool's arguments and the page's JSON.
+ * A card body as `add` reads it: the four fields the tool creates a card from.
  *
- * `add` is reachable two ways, and the fields it takes are the same four — title,
- * path hints, priority, and an optional first note. The normalization, the order the
- * refusals come in, and the shape handed to the store were written twice, which is how
- * a field added to one surface reaches the store unnormalized from the other. This is
- * that body's one owner.
- *
- * Only the *fields* are shared: a refusal is translated per surface, because the tool
- * answers a model with a failed result and the page answers a browser with a status.
+ * The normalization, the order the refusals come in, and the shape handed to the store are
+ * one body, so a field added to `add` cannot reach the store unnormalized. This is the
+ * boundary in front of `store.create`; a refusal is the first field that cannot be one.
  */
 
 import {