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

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

@@ -7,87 +7,93 @@ 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
-
-How the `list_worktrees` call and its result look in the transcript — the call line as a headline and the body indented under it:
+```text
+/worktree                              # the list screen, or the same facts as text
+```
 
-<img src="../../assets/tools/list_worktrees.png" alt="The list_worktrees tool's call and result, drawn by the generic fallback" width="100%">
+The model enters with `enter_worktree`; `pi -e . --worktree feature-auth` starts
+the session already isolated.
 
-## The `/worktree` screen
+## Tools
 
-<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%">
+<img src="../../assets/tools/list_worktrees.png" alt="The list_worktrees tool's call and result, drawn by the generic fallback" 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.
+`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.
 
-| Key | |
+| Tool | Usage |
 |---|---|
-| `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 |
+| `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. |
 
-`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.
+`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.
 
-## 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.
+`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`.
 
-## Commands and flags
+While isolated, `read`/`write`/`edit`/`bash`/`grep`/`find`/`ls` all resolve
+relative paths inside the worktree, and:
 
-| | |
-|---|---|
-| `/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) |
-| `/worktree exit` | exit a worktree |
-| `/worktree prune` | remove clean, unused, old managed worktrees |
-| `--worktree <name>` | enter at session start |
+- 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.
 
-Exit asks whether to keep or remove, and `worktree.onExit` answers without
-asking: a clean worktree this session created is removed, one holding work or
-entered by path asks, and only a worktree with no work loses its branch. There
-are no flags to disagree with either. Declining a confirmation (entering an
-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.
+### Status text
 
 `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
@@ -107,19 +113,56 @@ 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.
 
-The model surface mirrors this with four tools:
+## Commands and flags
 
-| Tool | Usage |
+| Command / flag | 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. |
+| `/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) |
+| `/worktree exit` | exit a worktree |
+| `/worktree prune` | remove clean, unused, old managed worktrees |
+| `--worktree <name>` | enter at session start |
+
+Exit asks whether to keep or remove, and `worktree.onExit` answers without
+asking: a clean worktree this session created is removed, one holding work or
+entered by path asks, and only a worktree with no work loses its branch. There
+are no flags to disagree with either. Declining a confirmation (entering an
+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.
+
+### The /worktree screen
+
+<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.
+
+| Key | What it does |
+|---|---|
+| `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"

package/extensions/board/commands.ts

@@ -0,0 +1,87 @@
+/**
+ * `/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(page.status(), joined), "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.
+				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"));
+			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)}`,
+				"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.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,72 @@
+/**
+ * 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 } from "../../lib/board/links.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): string {
+	return [`${cardRef(card.id)} ${card.status} · ${card.title}`, ...detailLines(card, board)].join("\n");
+}
+
+/** A board, in lane order. */
+export function formatCards(cards: readonly Card[]): string {
+	if (cards.length === 0) return "The board is empty.";
+	return cards.map((card) => listLine(card)).join("\n");
+}
+
+/** 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.`;
+}
+
+/** 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(", ")}`;
+	return `${cardRef(card.id)} ${card.status} · ${card.title} · ${holder}${urgency}${waits}`;
+}
+
+/** The state lines under a card's headline. */
+function detailLines(card: Card, board?: BoardIndex): string[] {
+	const lines: string[] = [];
+	if (card.owner !== undefined) lines.push(`  owner: ${card.owner.label}`);
+	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)}`);
+	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();
+	});
+}

package/extensions/board/input.ts

@@ -0,0 +1,54 @@
+/**
+ * A card body as both surfaces read it: the tool's arguments and the page's JSON.
+ *
+ * `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.
+ */
+
+import {
+	type FieldError,
+	normalizeNote,
+	normalizePathHints,
+	normalizePriority,
+	normalizeTitle,
+} from "../../lib/board/card.ts";
+import type { CreateInput } from "../../lib/board/store.ts";
+
+/** The first note, or nothing when the body carries none. */
+function noteOf(raw: unknown): { text?: string } | FieldError {
+	if (raw === undefined) return {};
+	const parsed = normalizeNote(raw);
+	if ("error" in parsed) return parsed;
+	return { text: parsed.text };
+}
+
+/**
+ * The card `add` creates, or the first field that cannot be one.
+ *
+ * The store takes an already-normalized body, so this is the boundary in front of it:
+ * an absent field is its default, and a bad one is refused rather than clamped.
+ */
+export function createInput(body: Record<string, unknown>): { input: CreateInput } | FieldError {
+	const title = normalizeTitle(body.title);
+	if ("error" in title) return title;
+	const paths = normalizePathHints(body.paths);
+	if ("error" in paths) return paths;
+	const priority = normalizePriority(body.priority);
+	if ("error" in priority) return priority;
+	const note = noteOf(body.note);
+	if ("error" in note) return note;
+	return {
+		input: {
+			title: title.title,
+			paths: paths.paths,
+			priority: priority.priority,
+			...(note.text === undefined ? {} : { note: note.text }),
+		},
+	};
+}

package/extensions/board/join.ts

@@ -0,0 +1,42 @@
+/**
+ * Board's side of the team: the one call that puts this session on it.
+ *
+ * The user's surface is `/board` and `team`; the session bus is the transport under
+ * them. So the board joins on the user's behalf — when the page opens, and again the
+ * first time a card is worked — and never asks anybody to run a bus action.
+ *
+ * The seam exists for the same reason `team`'s dispatch does: a board suite drives a
+ * recording join instead of a bus, and the shipped implementation is one in-process
+ * request through `lib/session-tool.ts` (a command context cannot call a tool).
+ */
+
+import type { JoinResult } from "../../lib/session-tool.ts";
+import { DEFAULT_SEAT } from "./seat.ts";
+
+/**
+ * The join itself is `lib/session-tool.ts`'s, because `team` asks for it too; this
+ * module only holds what is the board's — the label it lands on, and how the outcome
+ * reads on a `/board` line.
+ */
+export type { TeamJoin } from "../../lib/session-tool.ts";
+
+/**
+ * The label `/board` lands on: the page's seat when this session serves it, and
+ * nothing when it watches somebody else's page, so a viewer keeps its own name.
+ */
+export function joinLabel(served: boolean): string | undefined {
+	return served ? DEFAULT_SEAT : undefined;
+}
+
+/**
+ * What the join did, as a clause for a `/board` line.
+ *
+ * A board with no bus still serves, so the failure is a clause and not an error: the
+ * page works, and the line says there is no team to hand work over.
+ */
+export function teamLine(result: JoinResult | undefined): string {
+	if (result === undefined) return "";
+	if (!result.ok) return ` · no team (${result.error})`;
+	const state = result.watching.armed ? "listening" : "not listening";
+	return ` · on the team as ${result.label}, ${state}`;
+}