# Plannotator

A plan review UI for Claude Code that intercepts `ExitPlanMode` via hooks, letting users approve or request changes with annotated feedback. Also provides code review for git diffs and annotation of arbitrary markdown files.

> **Reusing the document UI (theme / markdown / editor / settings / comments / layout) in the commercial Workspaces app? Read `packages/ui/README.md` FIRST.** It explains the published `@plannotator/ui` + `@plannotator/core` packages and the host-override seams a host plugs its own backend into via `configurePlannotatorUI()`. A prior from-scratch reimplementation of this UI broke the app and was reverted — do **not** rebuild it or recreate `packages/document-ui`. Add a seam to `@plannotator/ui` instead, keep Plannotator's app unchanged, and never delete working code until a human confirms parity in the browser.

## Project Structure

```
plannotator/
├── apps/
│   ├── hook/                     # Claude Code plugin (no commands/ — core skills installed to ~/.claude/skills act as slash commands)
│   │   ├── .claude-plugin/plugin.json
│   │   ├── hooks/hooks.json      # PermissionRequest hook config + "modules" (the Claude Code mod)
│   │   ├── hooks/mod/            # The Claude Code mod: non-blocking plan review/annotate/review/last + Ask this session (see "Claude Code mod")
│   │   ├── tests/                # `claude plugin test` harness tests (scripts/test-claude-code-mod.sh; bun skips them)
│   │   ├── server/index.ts       # Entry point (plan + review + annotate + archive subcommands)
│   │   └── dist/                 # Built single-file apps (index.html, review.html)
│   ├── opencode-plugin/          # OpenCode plugin
│   │   ├── commands/             # Slash command stubs (review, annotate, last — plugin intercepts execution)
│   │   ├── index.ts              # OpenCode 1 entry with submit_plan tool + review/annotate event handlers
│   │   ├── server.ts             # OpenCode 2 adapter (stable @opencode/plugin types; older-host capability fallbacks)
│   │   ├── plannotator-tool.ts   # OpenCode 2 `plannotator` tool + per-session launch record (list/close); see "OpenCode 2: the plannotator tool"
│   │   ├── plannotator.html      # Built plan review app
│   │   └── review-editor.html    # Built code review app
│   ├── amp-plugin/               # Amp plugin
│   │   ├── plannotator.ts        # Native Amp command-palette integration
│   │   └── README.md             # Install and local development notes
│   ├── droid-plugin/             # Droid plugin
│   │   ├── .factory-plugin/plugin.json
│   │   ├── commands/             # Slash command entrypoints
│   │   └── lib/                  # Shared command wrapper helpers
│   ├── marketing/                # Marketing site, docs, and blog (plannotator.ai)
│   │   └── astro.config.mjs      # Astro 5 static site with content collections
│   ├── vibe/                     # Mistral Vibe integration source (consumed by scripts/install.sh; auto-detected via $VIBE_HOME, default ~/.vibe)
│   │   ├── hooks/hooks.toml      # Reference copy of the managed pre_tool hook block install.sh writes into $VIBE_HOME/hooks.toml (macOS/Linux only)
│   │   └── skills/               # Vibe-specific skills (review, annotate, last) with PLANNOTATOR_ORIGIN=mistral-vibe baked in; not installed on Windows
│   ├── kiro-cli/                 # Kiro CLI integration source (consumed by scripts/install.sh; auto-detected via ~/.kiro)
│   │   ├── agents/plannotator.json   # Example Kiro custom agent
│   │   └── skills/               # Kiro-specific skill packages (review, annotate); setup-goal + visual-explainer install from apps/skills/extra
│   ├── paste-service/            # Paste service for short URL sharing
│   │   ├── core/                 # Platform-agnostic logic (handler, storage interface, cors)
│   │   ├── stores/               # Storage backends (fs, kv, s3)
│   │   └── targets/              # Deployment entries (bun.ts, cloudflare.ts)
│   ├── inbox/                    # The Plannotator Inbox window's Vite single-file build (packages/inbox); build:hook copies it to apps/hook/dist/inbox.html, and the phone's surface (build:surface) to apps/hook/dist/surface.html
│   ├── review/                   # Standalone review server (for development)
│   │   ├── index.html
│   │   ├── index.tsx
│   │   └── vite.config.ts
│   ├── guides-show/               # guides.show — portable Guided Review viewer (multi-file CDN build) + Cloudflare Worker (viewer/, worker/, share/, build/); the Worker is the only host target, self-hosting = deploying it under your own account
│   ├── relay/                     # The Inbox relay (mobile steps R1, R2, R3): a Cloudflare Worker + one Durable Object per mailbox (src/index.ts, src/mailbox.ts), holding only ciphertext and hashes: pushes, and the phone's reads and answers while it is away; src/apns-h2.ts is a standalone HTTP/2 client for APNs over connect(); src/fcm.ts sends Android pushes through FCM HTTP v1 with plain fetch. Private, own version line, owner-deployed (never from CI; README.md has the deploy); its proof (test/) runs `wrangler dev` in the relay workflow and is skipped by the root `bun test`
│   ├── vscode-extension/         # VS Code extension — opens plans in editor tabs
│   │   ├── bin/                   # Router scripts (open-in-vscode, xdg-open)
│   │   ├── src/                   # extension.ts, cookie-proxy.ts, ipc-server.ts, panel-manager.ts, editor-annotations.ts, vscode-theme.ts
│   │   └── package.json           # Extension manifest (publisher: backnotprop)
│   └── skills/                    # Agent skills (agentskills.io format)
│       ├── core/                  # CORE skills (single-sourced) — installed to ~/.claude/skills and ~/.agents/skills (Codex)
│       │   ├── plannotator/           # Knowledge layer: model-invocable CLI reference (subcommands, flags, exit codes) an agent loads on generic "use Plannotator" intent; freshness-guarded against apps/hook/server/cli.ts by plannotator-skill-reference.test.ts. Unreleased subcommands (`HIDDEN_SUBCOMMANDS` in cli.ts: today `t3` and `t3-hook`, the opt-in T3 Code connection, and `card`, the Board's card call from a shell; `inbox` was the last to launch) still run and keep `<sub> --help`, but stay out of `plannotator --help`, "Did you mean" suggestions and this skill (the test requires their absence); un-hide by deleting from that set, adding the top-level usage lines and documenting it here
│       │   ├── plannotator-review/    # Lightweight: opens review UI
│       │   ├── plannotator-annotate/  # Lightweight: opens annotate UI
│       │   └── plannotator-last/      # Lightweight: annotates last message
│       └── extra/                 # EXTRA skills — NOT default-installed (except Kiro); add via `npx skills add backnotprop/plannotator/apps/skills/extra --global`
│           ├── plannotator-compound/        # Research analysis agent (map-reduce over denied plans)
│           ├── plannotator-setup-goal/      # Goal package scaffolder for /goal workflows
│           └── plannotator-visual-explainer/ # Visual HTML generator (plans, diagrams, PR explainers) with Plannotator theming
├── packages/
│   ├── server/                   # Shared server implementation
│   │   ├── index.ts              # startPlannotatorServer(), handleServerReady()
│   │   ├── review.ts             # startReviewServer(), handleReviewServerReady()
│   │   ├── annotate.ts           # startAnnotateServer(), handleAnnotateServerReady()
│   │   ├── inbox.ts              # startInboxServer(), handleInboxServerReady(): the Plannotator Inbox (Bun-only, loopback-only; see "Plannotator Inbox")
│   │   ├── inbox-mcp.ts          # The Inbox's MCP tools (send_message, read_thread, resolve_message, wait_for_reply, get_guide_brief, submit_guide)
│   │   ├── inbox-tailscale.ts    # "Over your tailnet": `plannotator inbox --tailscale`, the owner-only tailnet listener and its serve mapping (see "Plannotator Inbox")
│   │   ├── storage.ts            # Re-exports from @plannotator/shared/storage
│   │   ├── share-url.ts          # Server-side share URL generation for remote sessions
│   │   ├── remote.ts             # isRemoteSession(), getServerPort()
│   │   ├── browser.ts            # openBrowser()
│   │   ├── draft.ts              # Re-exports from @plannotator/shared/draft
│   │   ├── integrations.ts       # Obsidian, Bear integrations
│   │   ├── ide.ts                # VS Code diff integration (openEditorDiff)
│   │   ├── editor-annotations.ts  # VS Code editor annotation endpoints
│   │   └── project.ts            # Project name detection for tags
│   ├── ui/                       # Shared React components + theme
│   │   ├── theme.css             # Single source of truth for color tokens + Tailwind bridge
│   │   ├── components/           # Viewer, Toolbar, Settings, etc.
│   │   │   ├── icons/            # Shared SVG icon components (themeIcons, etc.)
│   │   │   ├── diagram/          # The diagram engine's viewer (DiagramViewer, DiagramCanvas, DiagramOverlay, DiagramComposer, DiagramSourcePane, DiagramPopout + hooks); DiagramBlock.tsx is the fence side
│   │   │   ├── plan-diff/        # PlanDiffBadge, PlanDiffViewer, clean/raw diff views
│   │   │   └── sidebar/          # SidebarContainer, SidebarTabs, VersionBrowser, ArchiveBrowser
│   │   ├── shortcuts/            # Keyboard shortcut registry (see Keyboard Shortcuts section below)
│   │   │   ├── core.ts           # Engine: parser, formatter, dispatcher, validator
│   │   │   ├── runtime.ts        # Engine: useShortcutScope, useDoubleTapShortcuts hooks
│   │   │   ├── index.ts          # Barrel — re-exports engine + scopes from both subfolders
│   │   │   ├── plan-review/      # Scopes for plan-editor surfaces (annotationMode, annotationPanel, annotationToolbar, commentPopover, documentView, goalSetup, htmlAnnotate, imageAnnotator, inputMethod, sidebar, viewer, vimSelection)
│   │   │   └── code-review/      # Scopes for review-editor surfaces (ai, allFilesDiff, annotationToolbar, fileTree, prComments, suggestionModal, tourDialog)
│   │   ├── shortcuts.test.ts     # Registry unit tests (parser, dispatcher, validator)
│   │   ├── utils/                # parser.ts, sharing.ts, storage.ts, planSave.ts, agentSwitch.ts, planDiffEngine.ts, planAgentInstructions.ts, annotateAgentInstructions.ts
│   │   ├── hooks/                # useAnnotationHighlighter.ts, useSharing.ts, usePlanDiff.ts, useSidebar.ts, useLinkedDoc.ts, useAnnotationDraft.ts, useCodeAnnotationDraft.ts, useArchive.ts
│   │   └── types.ts
│   ├── ai/                       # Provider-agnostic AI backbone (providers, sessions, endpoints)
│   ├── core/                     # @plannotator/core — browser-safe, zero-dep universal slice (pure utils + types) shared by ui + shared; published so @plannotator/ui can be installed standalone. `shared` re-exports the moved modules via one-line shims so Plannotator is unchanged.
│   ├── shared/                   # Node/git/server logic + cross-runtime types (re-exports browser-safe modules from @plannotator/core)
│   │   ├── storage.ts            # Plan saving, version history, archive listing (node:fs only)
│   │   ├── draft.ts              # Annotation draft persistence (node:fs only)
│   │   ├── project.ts            # Pure string helpers (sanitizeTag, extractRepoName, extractDirName)
│   │   └── inbox/                # The Inbox store (store.ts, append-only JSONL; thread routing), the per-thread list sections (list.ts), layout + line reader (schema.ts), registry (registry.ts: inbox/inbox.json)
│   ├── inbox/                    # The Plannotator Inbox window (App, sidebar, list, thread, empty state, Settings), composed from ui, and surface/ (what a phone hosts); built by apps/inbox
│   ├── t3-code/                  # @plannotator/t3-code — the opt-in T3 Code connection (Ask this session through a Claude Bash hook); loaded by the CLI only for `t3` / `t3-hook` (see "T3 Code")
│   ├── guide-viewer/             # @plannotator/guide-viewer — the Guided Review chain (GuideView → GuideSectionCard → GuideFileCard → GuideViewportManager) behind a narrow GuideHost context; used by review-editor (ReviewGuideHost + AllFilesCodeView) and by the guides.show viewer (readOnly). Also home of diffParser, DiffFile, and the two markdown renderers.
│   ├── editor/                   # Plan review app
│   │   ├── App.tsx               # Main plan review app
│   │   └── shortcuts.ts          # planReviewSurface + annotateSurface — composes plan-review scopes into per-surface registries
│   └── review-editor/            # Code review UI
│       ├── App.tsx               # Main review app
│       ├── shortcuts.ts          # codeReviewSurface — composes code-review scopes into the review registry
│       ├── components/           # DiffViewer, FileTree, ReviewSidebar
│       ├── dock/                 # Dockview center panel infrastructure
│       ├── demoData.ts           # Demo diff for standalone mode
│       └── index.css             # Review-specific styles
├── .claude-plugin/marketplace.json  # For marketplace install
└── legacy/                       # Old pre-monorepo code (reference only)
```

## Server Runtimes

There are two separate server implementations with the same API surface:

- **Bun server** (`packages/server/`) — used by both Claude Code (`apps/hook/`) and OpenCode (`apps/opencode-plugin/`). These plugins import directly from `@plannotator/server`.
- **Pi server** (`apps/pi-extension/server/`) — a standalone Node.js server for the Pi extension. It mirrors the Bun server's API but uses `node:http` primitives instead of Bun's `Request`/`Response` APIs.

When adding or modifying server endpoints, both implementations must be updated. Runtime-agnostic logic (store, validation, types) lives in `packages/shared/` and is imported by both.

**Exception: the Plannotator Inbox.** The Inbox server (`packages/server/inbox.ts`, `plannotator inbox`) is Bun-only and lives in the compiled binary. Pi and OpenCode are its clients, never its hosts, so it has no `node:http` mirror; its routes change in one place. See "Plannotator Inbox".

## Installation

**Via plugin marketplace** (when repo is public):

```
/plugin marketplace add backnotprop/plannotator
```

**Local testing:**

```bash
claude --plugin-dir ./apps/hook
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `PLANNOTATOR_REMOTE` | Set to `1` / `true` for remote mode, `0` / `false` for local mode, or leave unset for SSH auto-detection. Uses a fixed port in remote mode; browser-opening behavior depends on the environment. Remote mode binds `0.0.0.0` and turns off these features: Ask this session (in-process and pull bridge), host control, the agent terminal, open-in, Update now, live app annotation, the strict-gate client lease. Everything else (approve/deny, feedback, agent jobs, `/api/git-add`, `/api/pr-action`, `/api/source/save`, `/api/save-notes`, SDK Ask AI) stays reachable by anyone who can reach the URL. WSL2 does not need it (#1983): local mode binds `127.0.0.1`, WSL2's `localhostForwarding` (default on; mirrored networking too) makes that reachable from Windows at `http://localhost:<port>`, and local mode already opens the Windows browser through `cmd.exe` when neither `BROWSER` nor `PLANNOTATOR_BROWSER` is set and WSL interop is on (`isWSL` in `packages/server/browser.ts`; Pi's `network.ts` likewise), so the guide tells WSL2 users to leave it unset. A "remote but bind loopback" knob was considered and not added: its reachability is exactly local mode's. Remote ready messages also render a terminal QR code of the advertised URL when stderr is a TTY and the advertised host is overridden away from localhost (a QR of a localhost URL scans to nowhere), so another device can join without retyping the URL. |
| `PLANNOTATOR_AGENT_TERMINAL_REMOTE` | Set to `1` / `true` to enable the annotate-mode agent terminal while `PLANNOTATOR_REMOTE` is active or the session is published with `--tailscale`. Off by default in both cases because the session is reachable by network peers and the PTY token is not an auth boundary. |
| `PLANNOTATOR_INBOX_PHONES` | Switch for the Plannotator Inbox's whole phone surface (see "Phones" under "Plannotator Inbox"): pairing, the device door `/api/inbox/device/*`, the tailnet and Wi-Fi listeners, the relay connection, and Phones and Pair a phone in Settings → Devices. **Default: off**, until the iPhone app and the relay ship. Off, the Inbox does nothing phone-related: every pairing, device and reach-switch route answers the unknown-route `404 { code: "not_found" }`, no LAN or door listener opens, nothing connects to the relay, no certificate is made and no `openssl`, `tailscale` or Bonjour process runs, even when `inbox.json`, `relay.json` or `devices.jsonl` hold state from a run that had it on (that state is kept for the next run with it on). `1` / `true` / `on` turn it on, `0` / `false` / `off` / `disabled` off; empty or unrecognized counts as unset. Also `~/.plannotator/config.json` `{ "inboxPhones": true }`; the env var wins (`resolveInboxPhones` in `packages/shared/config.ts`). Read once when the Inbox starts (`startInboxServer`'s `phones` option overrides it); `GET /api/inbox/settings` carries it as `phones`, which is how the window decides to draw the block. The iPhone app's proofs, the relay proof, `tests/e2e/inbox-phones.spec.ts`, the phone server tests (`createInboxWorld(..., { phones: true })`, `phones: true`) and the DAST target set it; `packages/server/inbox-phones-gate.test.ts` proves both states. Not in the public docs. |
| `PLANNOTATOR_RELAY_URL` | The Inbox relay a new mailbox is made at (`packages/server/inbox-relay.ts`). Default `https://relay.plannotator.ai`. Proofs point it at a `wrangler dev` relay; tests at a closed loopback port. A mailbox, once made, stays at the URL `inbox/relay.json` names. |
| `PLANNOTATOR_PORT` | Fixed port to use. Default: random locally, `19432` for remote sessions. The Plannotator Inbox ignores it (and `PLANNOTATOR_REMOTE`): it always binds `127.0.0.1` on its last port or a random one; to reach it from your other devices use `plannotator inbox --tailscale` / `PLANNOTATOR_INBOX_TAILSCALE`; see "Plannotator Inbox". |
| `PLANNOTATOR_URL_HOST` | Display-only hostname for advertised session URLs (issue #657), e.g. a Tailscale MagicDNS name or tailnet IP, so remote-mode links are reachable from another device instead of `http://localhost:<port>`. Host only — bare hostname, IPv4, or bracketed IPv6 (`[fd7a::1]`); the runtime-chosen port is always appended, and anything carrying a scheme, port, path, credentials, or whitespace warns once on stderr and falls back to `localhost`. Strictly display-only and remote-only: binding stays governed by `PLANNOTATOR_REMOTE`; a local session ignores the override (localhost is advertised and opened, since only loopback is bound) with a once-per-process stderr warning to set `PLANNOTATOR_REMOTE=1`, and spawned agent-review jobs keep a pinned `http://127.0.0.1:<port>` API URL so a tailnet-only hostname cannot break local jobs. The sentinel `auto` resolves the host from Tailscale once per process, at first use in a remote session: `tailscale status --json` → `Self.DNSName` (trailing dot stripped), falling back to the single `tailscale ip -4` CGNAT (100.64.0.0/10) address; detection failure warns once on stderr and falls back to `localhost`, and detection never changes binding — `auto` is as display-only as any explicit host. Can also be set via `~/.plannotator/config.json` (`{ "urlHost": "host" }` or `{ "urlHost": "auto" }`); the env var takes precedence, and an empty-but-set env var (`PLANNOTATOR_URL_HOST=`) suppresses a config-file `urlHost`. Default: unset (`localhost`). |
| `PLANNOTATOR_ALLOWED_HOSTS` | Extra hostnames the servers answer on, for the Host allowlist every plan, review, annotate, archive and goal-setup server (and the Plannotator Inbox) applies to every request (see "Host allowlist" under Server API). Comma list of hostnames; a leading dot (`.example.com`) also matches subdomains; `*` turns the check off. For proxies and tunnels that forward their own hostname (a reverse proxy, a Docker service name, a LAN DNS name in remote mode). Not needed for GitHub Codespaces or VS Code dev tunnels (their forwarders present `Host: localhost:<port>`) or for a code-server / Coder port proxy (recognized from `VSCODE_PROXY_URI`). Read once per server start. An entry named explicitly (exact or `.suffix`, never `*`) is also accepted as a page Origin by the cross-origin write guard, for a plain-HTTP reverse proxy that rewrites Host: name the proxy's public hostname here (read on each request; see "Cross-origin write guard" under Server API). Default: unset. |
| `PLANNOTATOR_BROWSER` | Custom browser to open plans in. macOS: app name or path. Linux/Windows: executable path. `--browser <value>` sets it for one run. A "none" value, `none` `false` `0` `off` `no` `true` `1` `:` (trimmed, any case), opens NOTHING, local or remote: no VS Code IPC, no Glimpse, no `BROWSER`, no system opener (`resolveBrowserIntent` in `packages/shared/browser-intent.ts`, vendored to Pi; `none` / `default` / `explicit`), for every caller (sessions, the Inbox, `sessions --open`, `t3 login`). The Bun CLI prints `  Not opening a browser (PLANNOTATOR_BROWSER=<value>).` under the ready line (`openBrowser` prints it itself for direct callers; `handleServerReady` never calls the opener then, and says nothing when the host opens the browser itself, `skipBrowserOpen`); Pi says it in its "opened" message and returns `notOpening` from `openBrowser`. `BROWSER` is different: hosts set it (Claude Code's agent view sets `BROWSER=true`), so its #756 values (`true` `false` `none` `0` `1` `:`) are still read as unset and the default chain runs. Every session prints `  Plannotator session ready: <url>` on stderr before any launch (`SESSION_READY_LINE_PREFIX`, `handleServerReady`), so nothing is lost by opening nothing. |
| `PLANNOTATOR_AI` | Set to `disabled` to disable Ask AI and the Review Agents / Guided Review execution surfaces, including provider and agent-job endpoints. Persisted guide data is retained and its server APIs remain available, but the in-app history browser is hidden while AI is disabled. External agents can still open reviews and submit annotations. The explicit annotate-mode agent terminal is separate and remains controlled by its own settings. Default: enabled. |
| `PLANNOTATOR_SHARE` | Set to `disabled` to turn off URL sharing entirely, including Guided Review share links (the review UI hides "Create share link", `POST /api/guide/:jobId/share` answers `403 { error: "sharing disabled" }`, and `plannotator guide share` refuses with exit 1). Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "share": "disabled" }`); the env var takes precedence. |
| `PLANNOTATOR_SHARE_URL` | Custom base URL for share links (self-hosted portal). Default: `https://share.plannotator.ai`. |
| `PLANNOTATOR_PASTE_URL` | Base URL of the paste service API for short URL sharing. Default: `https://plannotator-paste.plannotator.workers.dev`. |
| `PLANNOTATOR_CLAUDE_MOD` | Switch for the Claude Code mod (non-blocking plan review, annotate, code review and annotate-last, the `plannotator` tool, the take-over of agent-run Bash `plannotator` commands, plus Ask this session; see "Claude Code mod"). **Default: on** wherever Claude Code runs hooks modules (2.1.287+, interactive CLI sessions; the mod still stands down by itself in `-p` / SDK sessions and where `/bin/sh` is missing, i.e. Windows). Set to `0` / `false` / `off` / `disabled` to turn it off, which leaves the module inert (every hook passes through, no command or tool is registered, no Bash command is taken over, no environment is set) so the classic PermissionRequest hook and `/plannotator-*` skills run exactly as before; `1` / `true` / `on` force it on, and empty or unrecognized counts as unset (on). Can also be turned off via `~/.plannotator/config.json` (`{ "claudeCodeMod": false }`, read from the data dir); the env var takes precedence (`resolveClaudeCodeMod` in `packages/shared/config.ts`, mirrored by `apps/hook/hooks/mod/enabled.ts` because a hooks module can import only its own files; `enabled.test.ts` keeps them in step). Read once when Claude Code starts, so a change applies to the next session start. Set it in the shell that starts Claude Code or in Claude Code's `settings.json` `env`. The plugin installs from the repo and the `plannotator` binary updates separately, so the mod also runs against older binaries; see "Version skew" in the mod section for what degrades. |
| `PLANNOTATOR_AGENT_TOOL` | Switch for the `plannotator` agent tool (`packages/shared/plannotator-tool.ts`) on the hosts that register it. **Default per host** (owner's call, one table: `AGENT_TOOL_DEFAULTS` in `packages/shared/config.ts`): **on for the Claude Code mod** (the tool is deferred behind tool search there, so it costs about its name until used), **on in Oh My Pi** (host key `oh-my-pi`: the Pi extension running inside OMP, which lists an extension tool as one `xd://plannotator` line of its system prompt, measured on OMP 18.10.2 at 212 characters, about 50 tokens, with the tools array unchanged, and loads the schema only when the model reads it; owner's call 2026-10-12, #1814), **off on Pi and OpenCode 2** (a full tool definition in every request: 2,993 bytes, about 800 tokens; 2,901 bytes, about 780 tokens, measured on Pi 0.84.4 before #1907 added review's `gate`, which grew the entry Pi sends by 92 bytes). The Pi extension tells OMP from Pi by its ExtensionAPI object (`detectPiHost` in `apps/pi-extension/pi-host.ts`: OMP's carries `arktype`, its omptype schema builder, and `pi`, its SDK module; Pi's has neither) and resolves with that host; the Inbox tool is not affected (it registers as `pi` in OMP too, `InboxToolHost`). `1` / `true` / `on` turn it on and `0` / `false` / `off` / `disabled` turn it off on every host, overriding the host default in both directions; empty or unrecognized counts as unset. Off removes ONLY the tool: the `/plannotator-*` slash commands, plan review, Ask this session and (Claude Code) the take-over of agent-run Bash `plannotator` commands, which adds nothing to the model's context, are unchanged, and an agent that wants Plannotator runs the CLI. Can also be set via `~/.plannotator/config.json` (`{ "agentTool": true }` / `false`, read from the data dir; allowlisted, boolean only, on `POST /api/config` in both runtimes, which refuses a cross-origin write with `403` on every plan, review and annotate server: `isSameOriginOrNoOrigin` in `packages/shared/request-origin.ts`, the guard every plan, review, annotate and goal-setup server now runs on EVERY `POST` / `PUT` / `PATCH` / `DELETE` before routing (see "Cross-origin write guard" under Server API), and that these routes also run themselves: review progress, guide share links, the CallDiff install, annotate's Edit Mode `/api/source/save`, `/api/open-in` on the annotate and review servers, `/api/save-notes`, `/api/plan/vscode-diff` and the review server's `/api/agents/jobs` launch and kill, since a page on another site can send a preflight-free `text/plain` POST. It passes a request with no Origin, an Origin naming the request host, or the browser's own `Sec-Fetch-Site: same-origin`, and refuses `Origin: null`, and `same-site` or `cross-site` fetch metadata whatever Origin says (a request with no Origin included). The `Sec-Fetch-Site` leg is what lets the VS Code panel write: its cookie proxy serves the page from `http://127.0.0.1:<proxy port>` and rewrites Host to the server, so Origin and Host differ. Before it, `/api/review-progress` and `/api/call-flow/install` were already refused in the VS Code panel (silently: the client ignores the failure); they work there now too. `cookie-proxy.ts` additionally re-anchors an Origin equal to its own origin onto the upstream, for browsers without Fetch Metadata; `vscode-proxy-writes.test.ts` (Bun and Pi) covers both shapes); the env var takes precedence (`resolveAgentTool(config, env, host)` in `packages/shared/config.ts`; the mod's mirror `resolveAgentToolEnabled` lives in `apps/hook/hooks/mod/enabled.ts`, kept equal to the claude-code row by `enabled.test.ts`). `getServerConfig(gitUser, agentToolIntegration)` advertises it for a later Settings toggle / one-time "turn it on" offer, but only where the integration that started the server registers the tool: `agentToolHost` is the session-bridge host, not the agent origin (Bun: `agentToolHostForServer` in `packages/server/ai-runtime.ts`, an in-process bridge's host, else `launchingSessionHost()`, the `PLANNOTATOR_SESSION_BRIDGE_HOST` the Claude Code mod / OpenCode 2 plugin hand the CLI, read once at startup and kept in remote mode and after the `--tailscale` discard, where Ask this session is off but the integration still started the session; Pi: the extension's own host, `pi` or `oh-my-pi` (`currentPiHost()`, recorded by the extension at load), since its servers run inside the extension). With no such integration (the classic Claude Code hook, the mod off, `-p`, Windows, OpenCode 1, a person at a shell) every `agentTool*` field is absent except an `agentTool` config.json sets. Known gap: OpenCode 2's embedded plan review passes its bridge only when the host has `session.generate`, so on an older V2 host that one review advertises nothing. Fields: `agentTool` (the config value, or the host default while unset), `agentToolConfigured` (config.json holds an explicit choice), `agentToolEnv` (present when the env var overrides the file) and `agentToolEnabled` (the effective value, for the NEXT session). **Read once per session start and never mid-session**, because the tool list is part of every request's prompt prefix and changing it would miss the prompt cache: a change applies to the next session (Pi: the next session or `/reload`; Oh My Pi: the next OMP start, the conservative promise the Settings row makes; OpenCode 2: the next OpenCode start; Claude Code: the next Claude Code start). |
| `PLANNOTATOR_INBOX_TOOL` | Switch for the Plannotator Inbox's `plannotator_inbox` agent tool and its reply wake on the hosts that register it (the Claude Code mod, see "The Plannotator Inbox" in the mod section; Pi and OpenCode, see "Agent connections" in "Plannotator Inbox"; OpenCode 1 gets the tool without the wake). On Pi and OpenCode only where `inbox/inbox.json` exists in the data dir (the person ran the Inbox once); otherwise nothing is registered and nothing polls there. The Claude Code mod registers the tool even before the Inbox ever ran (from the list bundled with the mod; the first call starts the Inbox), and stays silent (no HTTP, no files) until an Inbox exists. The same switch also gates the session-start reminder (config-only `inboxReminder`, below): never without the tool. Default per host `INBOX_TOOL_DEFAULTS` (= `AGENT_TOOL_DEFAULTS`: on for the Claude Code mod, off on Pi and OpenCode 2). `1` / `true` / `on` and `0` / `false` / `off` / `disabled` decide every host; empty or unrecognized counts as unset. Also `~/.plannotator/config.json` `inboxTool`: a boolean for every host, or one per host (`{ "inboxTool": { "pi": true } }`), which the Inbox's own Settings writes (`POST /api/inbox/settings`). The env var wins (`resolveInboxTool(config, env, host)` in `packages/shared/config.ts`; the mod's mirror `resolveInboxToolEnabled` in `apps/hook/hooks/mod/enabled.ts`, kept equal to the claude-code entry by `enabled.test.ts`). Independent of `PLANNOTATOR_AGENT_TOOL`. Read once per session start and never mid-session (the tool list is part of the prompt prefix), so a change applies to the next session: Pi, the next session or `/reload`; OpenCode, the next OpenCode start; Claude Code, the next Claude Code start (the mod decides at the process's first `session.start`). Documented for users in `apps/marketing/src/content/docs/reference/inbox.md`. |
| `PLANNOTATOR_INBOX_TAILSCALE` | Publish the Plannotator Inbox over your tailnet at every start ("Over your tailnet", `packages/server/inbox-tailscale.ts`): `tailscale serve --bg --https=<the Inbox's port> http://127.0.0.1:<a tailnet-only listener>`, HTTPS, serve and never funnel, for the Tailscale login that owns this machine only. `1` / `true` / `on` and `0` / `false` / `off` / `disabled` decide; empty or unrecognized counts as unset. Also `~/.plannotator/config.json` `inboxTailscale` (boolean), which the Inbox's Settings switch writes (`POST /api/inbox/settings` `{ tailscale: { on } }`; the switch is locked while the env var is set). Precedence: env (a hard switch both ways: `0` keeps it off even against `--tailscale` and the control route) > `plannotator inbox --tailscale` (this run only; the flag only turns it on) > config > off (`resolveInboxTailscale` in `packages/shared/config.ts`). Read at each start and at each switch change. Tailscale missing, stopped or signed out never stops the Inbox: Settings, `inbox.json` `tailscale.error` and stderr say why. Other logins: config-only `inboxTailscaleAllow`. See "Over your tailnet" under "Plannotator Inbox". Default: off. |
| `PLANNOTATOR_INBOX_NOTES` | Set to `0` / `false` / `off` / `disabled` to hide the Inbox window's note dialog (the offer to add a note to each agent's instructions), show a note row in Settings → Agents only for a note already written (so it can still be switched off), and refuse new notes (`plannotator inbox --notes` too). Notes already written stay until switched off or uninstalled. Default: on. See "The note in each agent's instructions" under "Plannotator Inbox". |
| `PLANNOTATOR_INBOX_CONNECT` | Set to `0` / `false` / `off` / `disabled` to skip the step in which a person's `plannotator inbox` connects the agents on this computer to the Inbox (see "Connecting the agents on this computer" under "Plannotator Inbox"). Default: on. Read from the shell that runs `plannotator inbox` and from the Inbox's own environment; either one off skips it. Dotfiles and managed setups use it; the test preload, `worldEnv` and every test sandbox that spawns the CLI set it to `0` so no test ever runs a real agent's CLI. No config.json key. |
| `PLANNOTATOR_HOST_RESULT_FILE` | Set by a host that starts the CLI detached (the Claude Code mod): when a review, annotate, annotate-last or `claude-mod-plan` session settles, the CLI writes one JSON decision record there atomically (mode 0600), with the agent message composed from the configured prompts. Only a path named `result.json` inside `<data dir>/claude-code-mod/` is accepted (`isAllowedHostResultPath`); anything else is ignored with a stderr warning, so the variable cannot make the CLI create or replace an arbitrary file. Taken at startup and removed from the environment. Stdout is unchanged. See "Claude Code mod". |
| `PLANNOTATOR_HOST_MESSAGES_FILE` | Set by the Claude Code mod for `annotate-last --stdin` (ignored without `--stdin`): a `messages.json` inside `<data dir>/claude-code-mod/` (`isAllowedHostMessagesPath`; anything else is ignored with a stderr warning) holding `{ v: 1, messages: [{ messageId, text, timestamp? }] }`, newest first, which the CLI shows as the message picker instead of the single stdin message. Validated fail-closed (1..25 entries, string fields, unique ids, 2 MiB per message, 8 MiB file); a malformed file exits 1 with the reason. Taken at startup and removed from the environment. A CLI that predates it ignores it and opens the stdin text. See "Claude Code mod". |
| `PLANNOTATOR_SESSION_TAG` | Set by the Claude Code mod in its session's environment (`claude-code:<session id>`), so processes the session starts can be matched to it; recorded as `hostSession` in the `sessions/` registry, and read by `plannotator inbox mcp`, which sends as that session when the agent leaves `agent_session` out (see "Plannotator Inbox"). Only `<host>:<id>` with host `claude-code`, `pi` or `opencode` counts; anything else is ignored. Not meant to be set by hand. |
| `PLANNOTATOR_HOST_REVIEW_ID` | Set per launch by the Claude Code mod and the OpenCode plugin to the review's `pn-` id; the CLI takes it at startup (validated `pn-` + 6 hex, scrubbed from the environment) and records it as `reviewId` in the `sessions/` registry, which `plannotator sessions` (and `--json`) prints beside each session's full `target`. Not meant to be set by hand. |
| `PLANNOTATOR_MOD_DEBUG` | Set to `1` before starting Claude Code to have the Claude Code mod write `claude-code-mod/debug.log` in the data dir (launches, results, turns, bridge commands). Default: off. |
| `PLANNOTATOR_INBOX_AUTO_SEND_MS` | Testing knob for the Plannotator Inbox (see "Undelivered replies go in by themselves" under "Questions and Send"): how long a reply, message or Re-ask note waits on a busy agent before the Inbox puts it into the running turn by itself (a 👍 note never does; it waits for the turn to end). Whole milliseconds from 1000 up to the default: it can only shorten the wait, and only in a build that is not a release (`__CLI_VERSION__` not X.Y.Z, e.g. `0.0.0-dev` or a source run) or under the test sandbox (`PLANNOTATOR_TEST_SANDBOX`); a release ignores it, so an agent that starts the Inbox cannot make replies jump into turns. Anything else is ignored. Default `INBOX_AUTO_SEND_AFTER_MS`, 300000 (5 min). Read once when `plannotator inbox` starts (`autoSendAfterMsFromEnv`, `apps/hook/server/inbox-command.ts`, `inbox-auto-send-knob.test.ts`); used by `tests/e2e/inbox-undelivered.spec.ts`. Not in the public docs. |
| `PLANNOTATOR_T3_WORKER_IDLE_MS` | Testing knob for the opt-in T3 Code connection (see "T3 Code"): how long a per-thread worker with no open review and no pending delivery waits before it exits. Default 600000 (10 min). |
| `PLANNOTATOR_ORIGIN` | Explicit agent-origin override at the top of the detection chain. Valid values: `claude-code`, `amp`, `droid`, `opencode`, `codex`, `copilot-cli`, `gemini-cli`, `kiro-cli`, `mistral-vibe`, `pi`, `oh-my-pi`. Invalid values silently fall through to env-based detection. Unset by default. |
| `PLANNOTATOR_JINA` | Set to `0` / `false` to disable Jina Reader for URL annotation, or `1` / `true` to enable. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "jina": false }`) or per-invocation via `--no-jina`. |
| `PLANNOTATOR_ANNOTATE_HISTORY` | Set to `0` / `false` to disable ALL annotate-session writes to the data dir: per-file version history (no copies of annotated files are written; the annotate version diff is unavailable) AND the durable submitted-feedback records (#678) that single-local-file annotate sessions otherwise write to `history/{project}/{slug}/submissions/` before deleting the draft on submit. Disabling it keeps annotate sessions fully stateless but also gives up that submit crash-recovery record. URL and annotate-last sessions never write either kind of data regardless of this flag. Folder sessions write no submitted-feedback records, but they do participate in per-file version history: the first time a session serves a file through /api/doc it snapshots that file (lazily, memoized per resolved path for the life of the server), which is what powers the per-file version diff when a folder file is reopened later; setting this flag to 0 disables those folder snapshots too. A review of several files (bundle) snapshots each of its text files when it opens, through the same pipeline, governed the same way. Setting it to 0 additionally suppresses **feedback archive** records for every annotate surface (single file, folder, URL, live app, annotate-last), so "fully stateless annotate session" stays literally true regardless of `PLANNOTATOR_FEEDBACK_HISTORY`, with one exception: annotation drafts (`drafts/`, including the path-keyed copies described under "Annotate drafts follow the file") are crash recovery and are still written; they are deleted when the review is decided. Raw-HTML and live-app pinpoints write their element context (selector, ancestor path, allowlisted attributes, visible text, a collapsed HTML skeleton, and the live route) into the submission records and drafts too; form values and inline handlers are never captured. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "annotateHistory": false }`); the env var takes precedence. |
| `PLANNOTATOR_FEEDBACK_HISTORY` | Set to `0` / `false` to stop archiving submitted feedback under `~/.plannotator/feedback/` (or `PLANNOTATOR_DATA_DIR`). Default: enabled, which appends one record per submission at decision-settlement time on all three surfaces and in both runtimes: plan approve/deny, code review Send Feedback / Approve (LGTM) / Close, and every annotate submit / approve / close. A review posted straight to GitHub, GitLab or Bitbucket with `POST /api/pr-action` is delivered to the platform and is not archived locally yet. **Note that this writes the user's own feedback text, the document and code excerpts it quotes, and per-annotation metadata to disk, and nothing prunes the directory** (same policy as `plans/`, `history/`, and `guides/`); delete `~/.plannotator/feedback/` or a project subdirectory to forget, or set this to 0 to never write. Code-review records carry diff IDENTITY only (vcsType, diffType, base, gitRef, snapshotId, cwd, PR metadata, changed-file count, patch byte count), never the patch bytes; plan records carry the decision text plus a reference to the `history/{project}/{slug}/NNN.md` version the decision was made on, never a second copy of the plan. Externally sourced annotations (linters, review agents, WebMCP browser agents) are included but keep their `source` / `author` tags, so `source == null` selects the reviewer's own comments; agent job outputs (guides, tours) are not archived. This knob governs only the new archive: the `planSave` decision snapshots in `plans/` and the #678 annotate submission records under `history/` are unaffected. Annotate surfaces honor `PLANNOTATOR_ANNOTATE_HISTORY` as well. Can also be set via `~/.plannotator/config.json` (`{ "feedbackHistory": false }`); the env var takes precedence. |
| `PLANNOTATOR_GUIDE_VIEWER_URL` | Base URL of the portable Guided Review viewer that exported guides pin (default `https://guides.show/v1/`). Must be `https:` (or `http:` on localhost for local viewer builds — `bun run --cwd apps/guides-show serve:local`); anything else is ignored. Read by the export endpoints of both servers and by `plannotator guide export` (which also accepts `--viewer-url`). |
| `PLANNOTATOR_GUIDE_SHARE_URL` | Base URL of the guide host that Guided Review share links are created on: the review UI's "Create share link", `plannotator guide share`, and `plannotator guide unshare` upload to and delete from it (default `https://guides.show`; the origin of your own deployment of its Cloudflare Worker otherwise, see the `apps/guides-show` README). Must be `http(s)`; credentials, query and fragment are dropped and a trailing slash is trimmed; an invalid value warns once on stderr and falls back to the default so a share setting can never break a server launch or CLI run. An empty-but-set env var counts as unset. Can also be set via `~/.plannotator/config.json` (`{ "guideShareUrl": "https://guides.example.com" }`); the env var takes precedence; there is no per-invocation flag. Resolved by `resolveGuideShareUrl` in `packages/shared/config.ts`. Whether sharing is allowed at all is `PLANNOTATOR_SHARE` (`disabled` turns guide share links off entirely). Removal always goes to the host a saved guide's record names, never merely the currently configured URL, so changing this after sharing does not strand a link. |
| `PLANNOTATOR_BITBUCKET_TOKEN` | Atlassian API token for Bitbucket Cloud PR review (`plannotator review https://bitbucket.org/<workspace>/<repo>/pull-requests/<id>`). Bitbucket has no gh-like CLI, so the provider (`packages/shared/pr-bitbucket.ts`, vendored to Pi) calls the REST API 2.0 with `fetch`. Scopes needed: `read:user:bitbucket`, `read:repository:bitbucket`, `read:pullrequest:bitbucket`, `write:pullrequest:bitbucket` (app passwords are deprecated by Atlassian and not supported). A missing, rejected or under-scoped token fails `checkAuth` with a message naming these env vars and scopes; the token is never logged, echoed in an error, or sent to the browser (`getServerConfig` allowlists its keys). Can also be set via `~/.plannotator/config.json` (`{ "bitbucketToken": "..." }`, plain text, so prefer the env var); the env var takes precedence, and the token and email always come from the same source (`resolveBitbucketCredentials` in `packages/shared/config.ts`). |
| `PLANNOTATOR_BITBUCKET_EMAIL` | The Atlassian account email that owns `PLANNOTATOR_BITBUCKET_TOKEN`; with it the token goes out as HTTP basic auth, without it as a Bearer token. Config key `bitbucketEmail`. |
| `PLANNOTATOR_BITBUCKET_API_URL` | Testing / proxy knob: base URL of the Bitbucket Cloud REST API (default `https://api.bitbucket.org/2.0`). The fake API in `tests/test-fixtures/bitbucket/fake-bitbucket.ts` is reached through it. Only `https:` or loopback `http:` is accepted (credentials are sent there); anything else warns once and uses the default. Redirects (the PR `/diff` and `/diffstat` endpoints answer with one) and pagination `next` links are followed only within this origin. |
| `PLANNOTATOR_GUIDE_HISTORY` | Set to `0` / `false` to disable persisting successful Guided Reviews (no guide copies are written to the data dir; the "Previous guides" list is then never populated, though already-saved guides remain readable and listed). **Note that a persisted guide includes a full copy of the diff it was generated against** — `history/.../guides/{id}.patch` beside the `{id}.json` envelope, uncapped, as large as the diff — because that patch is what a later portable export or share link renders (the diff is captured when the guide job launches, never re-read from the working tree). Deleting a guide removes both files; nothing prunes the directory otherwise. Turning this flag off skips the patch copy too, at the cost of exports and share links for guides from that session once the server exits. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "guideHistory": false }`); the env var takes precedence. |
| `PLANNOTATOR_REVIEW_PROGRESS` | Set to `0` / `false` (also `off` / `disabled`) to stop code review remembering which files you marked viewed across review sessions. Default: enabled, which writes one small JSON record per file you mark viewed or unviewed under `review-progress/{scopeHash}/{pathHash}.json` in the data dir (`~/.plannotator` or `PLANNOTATOR_DATA_DIR`), for local Git and PR reviews. **Each record carries the repo-relative file path in plain text** (plus a content fingerprint and the viewed flag; the scope directory name is a hash of the worktree root, branch and comparison, or of the PR URL). Nothing prunes the directory; delete `review-progress/` to forget, and `plannotator uninstall --purge` removes it (a plain uninstall keeps it). With the knob off the review server neither reads nor writes these records: `/api/review-progress` answers `{ available: false }` and viewed marks ride the annotation draft instead, exactly as in workspace, non-Git and piped-patch reviews. Records already on disk are left alone. Can also be set via `~/.plannotator/config.json` (`{ "reviewProgress": false }`); the env var takes precedence, and an empty or unrecognized env value counts as unset. Resolved by `resolveReviewProgress` in `packages/shared/config.ts`, read on every review snapshot in both runtimes. |
| `PLANNOTATOR_AUTO_UPDATE` | Opt-in background auto-update (#1634). Set to `1` / `true` / `on` to enable, `0` / `false` / `off` / `disabled` to force off; empty or unrecognized counts as unset. **Default: off**; nothing changes for anyone who has not opted in. Can also be set via `~/.plannotator/config.json` (`{ "autoUpdate": true }`) or Settings → General → "Keep Plannotator up to date" (allowlisted on `POST /api/config` in both runtimes; `getServerConfig` always sends the config-file value plus `autoUpdateEnv` when this env var overrides it, and the toggle is disabled with a note in that case); the env var takes precedence (`resolveAutoUpdate` in `packages/shared/config.ts`). The whole mechanism is "run the normal install script": the compiled CLI (`apps/hook/server/index.ts`, `registerCliSession`) calls `scheduleAutoUpdateCheck` (`packages/server/auto-update.ts`) each time a session registers, which returns immediately and runs on a later, unref'd tick, so it is never awaited and adds no latency to any hook, review, annotate or CLI command. That tick first runs the shared release check (`PLANNOTATOR_UPDATE_CHECK` row: one GitHub request per 24h per data dir), then auto-update, which answers from the same `latestRelease` cache and never runs while update checks are off (outcome `checks-off`). The check is skipped for dev/source runs (no `__CLI_VERSION__`), when the running executable is not the file the install script manages (`~/.local/bin/plannotator`, `%LOCALAPPDATA%\plannotator\plannotator.exe`), and is throttled to once per 24h (`lastCheckAt` in `update-state.json` in the data dir). It reads the newest stable release from the shared cache (asking GitHub `releases/latest` only when the cache is stale; strictly newer, never a downgrade); if another Plannotator session is open (a live pid other than ours in the `sessions/` registry) it logs, does NOT spend the 24h window, and retries on the next session start. Otherwise it takes `update.lock` (stale after 1h) and spawns a detached wrapper that downloads `https://plannotator.ai/install.sh` (Windows: `install.ps1`) and runs it with `--version vX.Y.Z --non-interactive` (`-Version … -NonInteractive`), all output to `update.log`; the wrapper writes the exit code to `update-result.json` and releases the lock. The script applies the user's own `skipInstall` config and saved install prefs as a manual run would, and install flags are remembered: after a successful run each installer (`install.sh`, `install.ps1`, `install.cmd`, including the `--minimal` early exit) writes the install-affecting choices it took from its COMMAND LINE to `install-flags.json` in the data dir as neutral ids (`{"v":1,"flags":["minimal","skip-codex"]}`; the set is `minimal`, `no-minimal`, `verify-attestation`, `skip-attestation`, `with-call-flow`, `skip-codex`, `skip-gemini`, `skip-kiro`, `skip-vibe`, `skip-opencode`, `skip-skills`, `skip-claude-plugin`; never raw argv, paths or secrets), and a manual run with none of them overwrites it with an empty set, i.e. back to defaults. Auto-update reads it (`readInstallFlags`), keeps only allowlisted ids (unknown entries and a mutually-exclusive pair are dropped and logged), and passes them re-spelled per installer (`--skip-codex` / `-SkipCodex`): as argv after the `sh -c` wrapper (`"$@"`) on POSIX, and on Windows as the `PLANNOTATOR_UPDATE_FLAGS` env var that the `-EncodedCommand` wrapper re-checks against the same allowlist and splats as an array. A missing or malformed file means no flags (today's behavior) plus an `update.log` line. Inside the script the flag still beats the env var, which beats config. The OpenCode and Pi runtimes never arm the trigger. The next UI load (plan, annotate, review) shows a one-time toast from `autoUpdateNotice` on `/api/plan` / `/api/diff` (Bun servers only, and only when the compiled CLI enabled it): "Updated to vX" once the running binary is that version, or "Auto-update failed" with the log path when the script exited non-zero; "seen" is the `plannotator-auto-update-notice-seen` cookie. Install scripts replace the binary safely for this: `install.sh` stages next to the target and renames over it (a running process keeps its inode), `install.ps1` / `install.cmd` rename a running `plannotator.exe` aside to `plannotator.exe.old*` and sweep those on a later run. `plannotator uninstall --purge` removes the four `update*` files and `install-flags.json`. |
| `PLANNOTATOR_UPDATE_CHECK` | Update notices (owner-approved design; design record, not in this repo). **Default: on.** `0` / `false` / `off` / `disabled` turn it off, `1` / `true` / `on` force it on; empty or unrecognized counts as unset. Also `~/.plannotator/config.json` `{ "updateCheck": false }` (allowlisted on `POST /api/config` in all six servers; `getServerConfig` always sends `updateCheck`, the config-file value, plus `updateCheckEnv` when this env var overrides it); the env var wins (`resolveUpdateCheck` in `packages/shared/config.ts`). The machine asks, never the browser (the review windows' own GitHub fetch is gone, below): `runReleaseCheck` in `packages/shared/update-check.ts` (vendored to Pi) sends one unauthenticated `GET https://api.github.com/repos/backnotprop/plannotator/releases/latest` with `user-agent: plannotator-update-check` (no version, no cookies) at most once per 24h per data dir, claims the attempt in `update-state.json` (`releaseCheck.attemptedAt`) before the request so concurrent starts ask once, and after a failure (offline, 403/429, a proxy) waits 6h, never retrying in a loop; a failure writes one `update.log` line and keeps the last known `latestRelease`. The tag is reduced to a canonical `X.Y.Z` before it is stored (pre-releases and junk are failures). Besides that one daily `api.github.com` request, the Inbox (and only the Inbox) downloads, in the background whether or not What's new is opened, up to 12 images per release that the saved notes show, from GitHub's release-attachment image hosts (`github.com/user-attachments`, `private-user-images.githubusercontent.com`, `user-images.githubusercontent.com`, this repository on `raw.githubusercontent.com`), with the same user agent and a per-version claim and back-off (`releaseImagesFetch`); only while update checks are on (see "Images in the notes" under the Inbox's update control). The release notes (the body from `## What's New in` up to `## Install / Update`, 64 KB cap, plus the "Missed recent releases?" table) go to `update-notes/<version>.json`. Who asks: the compiled CLI at `registerCliSession` (the same unref'd tick as auto-update; never in a build that is not a release, whose `__CLI_VERSION__` is absent or not `X.Y.Z`, e.g. `0.0.0-dev`); and the Plannotator Inbox of a release build, on start and on each health tick (`packages/server/inbox-updates.ts`; it answers from the cache within the window, so it adds no request); and the Pi extension, once per process at its first review-window payload (`apps/pi-extension/server/update-advert.ts`). Everything else reads the cache only. Off means no automatic request to GitHub at all (machine or browser): no terminal hint, no review-window notice, no Inbox Update button for a release that is only available (a binary already on disk still shows Ready), and no auto-update; an explicit `plannotator update` (or `--check`) still asks, and says so on stderr. The terminal hint: after a `review` / `annotate` / `annotate-last` / `last` / `archive` session the compiled CLI prints `Plannotator X is available (you have Y). Update: plannotator update` on stderr, only when stderr is a TTY, never with `--json` / `--hook`, never with `CLAUDECODE` or `PLANNOTATOR_SESSION_TAG` set (an agent's shell or the mod), at most once per 24h (`hintShownAt`), read from the cache (`takeUpdateHint`). `plannotator --version` is unchanged (the Inbox parses it). `plannotator update [--check]` (`apps/hook/server/update-command.ts`) forces a check, then runs the SAME wrapper as auto-update in the foreground (`beginManualUpdate` + `runInstallerForeground`: `update.lock`, pinned tag, remembered `install-flags.json`, output shown and appended to `update.log`, `update-result.json`), without auto-update's 24h window and its open-sessions gate (open sessions keep their old binary); it refuses a build that is not a release (no request at all) and a binary the install script does not manage (printing the install command with the remembered flags); exit 0 up to date / updated / `--check`, 1 failed or could not run, 2 usage, 130 interrupted. Interruption: the POSIX wrapper traps INT / TERM / HUP and the PowerShell wrapper writes its result in `finally`, so a Ctrl-C records exit 130 in `update-result.json` and removes `update.lock` at once (it never waits out the 1h stale-lock window); `runInstallerForeground` passes an INT / TERM sent only to the CLI on to the wrapper, and a wrapper killed outright still ends with the lock released and `-1` recorded (`abortLaunch`). `update-command-entry.ts` runs the same function alone, for the process tests (the full entry imports the built HTML). `uninstall --purge` also removes `update-notes/`. Review windows (design §4.5, owner's answer 3): the browser never asks GitHub any more (`useUpdateCheck` lost its fetch; `?preview-update=X` still simulates one). The compiled CLI's plan, review and annotate servers add `updateAvailable: { version, current, releaseUrl, action, command, publishedAt? }` to `/api/plan` and `/api/diff` (`getUpdateAdvert(origin)` in `packages/server/auto-update.ts`, read from the cache only), where `action` is `opencode` for an OpenCode-launched CLI, `script` for the binary the install script manages in a session only this computer reaches, `copy` otherwise (an unmanaged binary, and every remote-mode or `--tailscale` session, so a device on the LAN or tailnet is shown the command, never offered the installer), and `command` is the install command with the remembered flags (`installCommandFor`; PowerShell scriptblock form on Windows). Pi's three servers send the same field with `action: "pi"` and `command: "pi update --extensions"`, compared with the Pi package's own version (`apps/pi-extension/server/update-advert.ts`, which also schedules the daily check once per process from the vendored module; nothing for `oh-my-pi`). Known gap: OpenCode's in-process embedded plan server sends nothing (it knows no version). The toast (`useUpdateToast`, `packages/ui/hooks/`) shows at most once per version and at most once every 3 days across versions (`claimUpdateToast`, cookie `plannotator-update-toast` = `<version>@<ms>`, shared by every localhost port), first looks 5 s after load (past the first-run announcements' own window), waits while a first-run dialog of this load shows or a composer / dialog has focus (re-checking every 5 s for up to 2 min, unconsumed), never for a share link, archive or a session without a server, and never while auto-update is active. Its actions are **What's new** (the GitHub release) and, for `script`, **Update** (`POST /api/update`, `handleUpdateRoute`: `403 forbidden_host` unless the Host is loopback with this server's port (`isLoopbackHostHeader`), `403` cross-origin, `403 update_exposed` for a remote-mode or `--tailscale` session, `409 session_mismatch` for a body `serverSession` naming another session (the client sends it, `withServerSession`); then `startManualUpdateForThisBinary`, the same wrapper and `update.lock` as the Inbox's Update now; `409 update_locked` / `update_unmanaged` / `update_dev_build` / …), else **Copy command**. The Options button keeps its dot (no label shimmer any more) and its version section shows "X is available · What's new", the host's command with Copy, and Update now for `script`. Settings → General gains "Tell me when a new version is out" (`useUpdateCheckSetting`, shown when `serverConfig.updateCheck` is present; written with `POST /api/config`, deliberately NOT a settings-registry entry, because the registry is bundled into the pinned guides.show viewer and must not change its build) above "Keep Plannotator up to date", which is locked with "Needs update checks" while checks are off. |
| `PLANNOTATOR_UPDATE_API_URL` | Testing / mirror knob for the update check: the URL answering like GitHub's `releases/latest` (`releaseApiUrl` in `packages/shared/update-check.ts`). Only `https:` or loopback `http:` is accepted; anything else is ignored. One release's notes by its tag go to the URL resolved against it (`tags/v<version>` in place of its last segment, `releaseTagApiUrl`). The `plannotator update` process test serves a fake one on loopback. A loopback `http:` value also lets the Inbox fetch What's new images from that same origin (`allowedReleaseImageUrl` in `packages/server/inbox-whats-new-images.ts`); any other value adds no image host. |
| `PLANNOTATOR_INSTALL_SCRIPT_URL` | Testing / mirror knob: the install script the update wrapper downloads (`installScriptUrl` in `packages/server/auto-update.ts`; default `https://plannotator.ai/install.sh`, `install.ps1` on Windows), for `plannotator update`, Update now and auto-update alike. Only `https:` or loopback `http:` is accepted. |
| `PLANNOTATOR_CURSOR_SANDBOX` | Set to `0` / `false` / `disabled` to stop passing `--sandbox enabled` when launching Cursor's `agent` CLI for review jobs — the flag pair is omitted entirely, deferring to the user's own Cursor Agent sandbox configuration. For systems where Cursor's sandbox cannot start (NixOS, AppArmor-restricted Linux). Default: enabled (`--sandbox enabled` is passed). Can also be set via `~/.plannotator/config.json` (`{ "cursorSandbox": false }`); the env var takes precedence. Note: opting out means the review job's write protection relies on `--mode ask` plus the user's own Cursor configuration. |
| `PLANNOTATOR_CLAUDE_SANDBOX` | Set to `0` / `false` / `disabled` to turn Claude Code's own sandbox OFF for Claude-engine agent jobs (code review, Code Tour, Guided Review) by passing `--settings '{"sandbox":{"enabled":false}}'` (#1627). For Linux systems where the sandbox cannot start (no bubblewrap/socat, AppArmor-restricted user namespaces) while `~/.claude/settings.json` enables it: jobs run with `--permission-mode dontAsk`, so Claude's unsandboxed fallback is refused and every Bash call fails. Default: enabled, meaning Plannotator passes nothing and the user's own Claude Code sandbox setting applies. Opting out runs the job's commands without OS containment, the same as for any user who never enabled Claude's sandbox (Claude Code's default). `--tools`, the `--allowedTools` prefixes, the `--disallowedTools` list and `dontAsk` are unchanged, but the command rules limit what the model can run rather than containing it (Claude Code matches rule text, so a deny rule covers the spellings a model normally writes, not every spelling a program accepts), so treat the opt-out as removing the only OS-level boundary. Managed (enterprise) settings still outrank `--settings`. When a Claude job finishes with no shell command that ran and at least one refused command its own `--allowedTools` admits outright — a plain invocation with no operators, substitutions or variables, which `dontAsk` never refuses unless the shell itself cannot run (`detectClaudeShellBlocked`), the job carries a `warning` pointing at this knob, shown in the Agents tab and the job detail panel; the sandbox is never turned off automatically. Independently of this knob, every Claude agent job passes `--strict-mcp-config` (no `--mcp-config`, so none of the user's MCP servers load into a job) and an `--append-system-prompt` telling the model to run one simple command at a time, since `dontAsk` refuses compound commands (`$(...)`, `&&`, pipes) as a whole (`claudeJobIsolationArgs` in `packages/server/claude-review.ts`, vendored to Pi), plus `--setting-sources user`, so the user's own settings (auth, env, sandbox preference) and managed policy apply but the job directory's project/local `.claude/settings*.json` (a PR checkout is someone else's branch) cannot add allow rules or hooks to a job. Side effects: Claude auth or provider env kept only in a repo's `.claude/settings.json` / `.claude/settings.local.json` does not apply to jobs, and neither does a sandbox setting or `permissions.deny` set only in project settings; managed settings still apply. All three job kinds share ONE command allow/deny definition (`CLAUDE_JOB_ALLOWED_TOOLS` / `CLAUDE_JOB_DISALLOWED_TOOLS` via `claudeJobToolArgs`, same file): exactly the read-only commands the prompts instruct (git status/diff/log/show/blame/merge-base/rev-parse/ls-files/ls-tree, `git branch --show-current`, `git remote -v` / `get-url`, the read-only jj commands, `gh pr view|diff` / `gh issue view` and the glab equivalents, `wc`), with deny rules for git `--output` and `-c` / `--config-env`, jj `--config*` / `--tool`, and `git grep`, `git ls-remote`, `gh api`, `glab api`. There is no `git -C`: workspace prompts send the combined diff inline and point the model at the folder-prefixed files. `claude-job-isolation.test.ts` reads the commands out of the real prompt text and fails if the allowlist stops admitting one. `detectClaudeShellBlocked` also takes the job's `--disallowedTools`, so a refusal a deny rule issues by design never reads as a blocked shell. Can also be set via `~/.plannotator/config.json` (`{ "claudeSandbox": false }`); the env var takes precedence. |
| `PLANNOTATOR_GIT_REMOTE_CHECK` | Set to `0` / `false` / `disabled` to stop code review contacting the git remote (issue #1553). Default: enabled, which runs `git ls-remote --symref origin HEAD` to discover the remote default branch and to compare the remote tip against the local tracking ref for the "Baseline is behind GitHub" banner. That probe is **not** on a timer: it runs at startup (the compare-target detection plus the staleness probe), on `/api/diff` page load, on `/api/diff/switch` (the diff-type/base pickers and the "Diff out of date · Refresh" button), and on the explicit `/api/fetch-base`, each rate limited to once per 60s per session, with the interval DOUBLING on failure up to a 15-minute cap and resetting to 60s on the next success (`nextRemoteBaseCheckInterval` in `packages/shared/review-core.ts`, shared by both runtimes). It is deliberately absent from `/api/diff/fresh`, which the client polls every 5s for as long as the page is open — hanging the probe there made an idle review query the remote once a minute forever, which on a smartcard-backed SSH setup is one hardware-key touch prompt per minute with nothing on screen to explain it. With the check off the session makes **zero** `ls-remote` calls, startup probes included: the compare target stays whatever LOCAL ref discovery resolved (`getDefaultBranch`: `origin/HEAD` → `origin/main` → `main` → …), `baseBehindRemote` never rides any payload so the banner never shows, and `POST /api/fetch-base` stays available because an explicit Fetch is the user asking for the network — note that with the banner gone so is its one-click Fetch button, which lives in that banner, so the endpoint matters to API callers rather than to the reviewer, and its post-fetch `refreshRemoteBaseInfo()` is a no-op under the opt-out. Only plain local git sessions are affected (PR, jj, GitButler, P4, workspace and static-patch sessions never ran the check). Can also be set via `~/.plannotator/config.json` (`{ "gitRemoteCheck": false }`); precedence is `review --no-git-remote-check` flag > env var > config (`resolveGitRemoteCheck` in `packages/shared/config.ts`). The flag is parsed by the shared `parseReviewArgs`, so it works on every host that forwards review arguments — Claude Code, OpenCode, and Pi — not just the Bun CLI. |
| `PLANNOTATOR_TODO_PROVIDER` | Set to `off` / `0` / `false` / `disabled` to stop mirroring the approved plan checklist into an editable todo provider during execution. Default: enabled, which syncs only when a provider is detected (currently pi-todos: detected when its todo directory exists — `<cwd>/.pi/todos` by default, or wherever `PI_TODO_PATH` redirects it when set). The repo-implied `<cwd>/.pi/todos` must realpath to a location inside the project or the provider reads as absent and never writes, so a symlink committed into a hostile repo cannot redirect todo writes out of it; an explicitly set `PI_TODO_PATH` is the user's own choice and is honored verbatim, including outside the project. The mirror is additive — the progress widget is unaffected either way — and sync is one-way, so provider-side edits never feed back into plan execution. Can also be set via `~/.plannotator/config.json` (`{ "todoProvider": "off" }`); the env var takes precedence. |
| `JINA_API_KEY` | Optional Jina Reader API key for higher rate limits (500 RPM vs 20 RPM unauthenticated). Free keys include 10M tokens. |
| `PLANNOTATOR_DATA_DIR` | Override the base data directory. Supports `~` expansion. Default: `~/.plannotator`. When unset, an existing `~/.plannotator` always wins; if it doesn't exist and `$XDG_DATA_HOME` is set to an absolute path, `$XDG_DATA_HOME/plannotator` is used; otherwise `~/.plannotator` (the XDG spec's implicit `~/.local/share` default is deliberately not applied). All data (plans, history, drafts, config, hooks, sessions, debug logs, IPC registry) is stored under this directory. |
| `PLANNOTATOR_FILE_BROWSER_MAX_FILES` | File-discovery limit: regular files inspected by CLI markdown/folder resolution and startup code-file warming, supported files returned by the file browser, and directories scanned during multi-repo workspace discovery (symlinks may point outside the workspace, so the budget — not the root — bounds that walk). Must be a positive integer; invalid, zero, or negative values use the default of `5000`. |
| `PLANNOTATOR_GLIMPSE` | Set to `0` / `false` to disable the Glimpse native window even when `glimpseui` is installed. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "glimpse": false }`). |
| `PLANNOTATOR_GLIMPSE_WIDTH` | Width in pixels for the Glimpse native window. Default: `1280`. |
| `PLANNOTATOR_GLIMPSE_HEIGHT` | Height in pixels for the Glimpse native window. Default: `900`. |
| `PLANNOTATOR_VERIFY_ATTESTATION` | **Read by the install scripts only**, not by the runtime binary. Set to `1` / `true` to have `scripts/install.sh` / `install.ps1` / `install.cmd` run `gh attestation verify` on every install. Off by default. Can also be set persistently via `~/.plannotator/config.json` (`{ "verifyAttestation": true }`) or per-invocation via `--verify-attestation`. Requires the `gh` CLI, but not a login: the attestation bundle is fetched from GitHub's public attestations API (single unauthenticated attempt, never retried; the endpoint allows 60 requests/hour per IP) and verified with `--bundle`; the extraction needs one JSON tool on PATH (node, python3, or jq). gh's authenticated fetch is the fallback whenever the bundle path is unavailable or does not complete (missing extractor, fetch failure, or a gh that cannot verify the fetched bundle, e.g. an older gh without `--bundle`). Verification still needs network on every run because the Sigstore TUF trust root is fetched per-run; that failure is reported as connectivity, distinct from a real provenance failure, and both fail closed. |
| `PLANNOTATOR_SKIP_CODEX_INSTALL` | **Read by the install scripts only.** Set to `1` / `true` to skip writing the Codex integration (`hooks.json` / `config.toml` under `CODEX_HOME`, and the Codex-home stale-skill cleanup) even when Codex is detected. The installer reports the honest state ("Codex: detected, skipped (...)" vs installed; an agent that was not detected gets no closing-summary section at all, so the summary lists only the agents the machine has) and never removes an integration a previous install wired. Also settable via `~/.plannotator/config.json` (`{ "skipInstall": { "codex": true } }`); precedence is `--skip-codex` flag > env var > config. Off by default. |
| `PLANNOTATOR_SKIP_GEMINI_INSTALL` | **Read by the install scripts only.** Same opt-out shape for the Gemini CLI integration (`~/.gemini` policy file, settings hook, slash commands). Config key: `skipInstall.gemini`; flag: `--skip-gemini`. Off by default. |
| `PLANNOTATOR_SKIP_KIRO_INSTALL` | **Read by the install scripts only.** Same opt-out shape for the Kiro CLI integration (`~/.kiro` skills and agent, including the `~/.kiro` stale-skill sweep). Config key: `skipInstall.kiro`; flag: `--skip-kiro`. Off by default. |
| `PLANNOTATOR_SKIP_VIBE_INSTALL` | **Read by the install scripts only.** Same opt-out shape for the Mistral Vibe integration (`$VIBE_HOME` skills and the managed plan-review hook block in `$VIBE_HOME/hooks.toml`, plus the `~/.vibe` stale-skill sweep). Hooks are stable in Vibe 2.25+ (no config flag), so the installer writes only the `hooks.toml` block; its `command` is argv-only (absolute binary path, no env prefix) because Vibe's hook executor may be shell-free, and plannotator detects the Vibe origin from the hook payload (`pre_tool` + `exit_plan_mode`), with `PLANNOTATOR_ORIGIN=mistral-vibe` as the manual override. The hook is macOS/Linux-only, so the Windows installer never writes `hooks.toml` — it prints manual setup instructions, mirroring Codex-on-Windows. The Windows installers also skip the Vibe-specific skills (their `PLANNOTATOR_ORIGIN=mistral-vibe plannotator …` env-prefix only runs when Vibe's Windows shell tool resolves Git Bash, not on its PowerShell fallback), so they write nothing under `$VIBE_HOME`. Vibe still reads the shell-neutral core skills from `~/.agents/skills`, so `/plannotator-review` and `/plannotator-annotate` work there without a Vibe origin label; `/plannotator-last` is **not** supported for Vibe on Windows yet (with no `PLANNOTATOR_ORIGIN` it takes the Claude Code transcript path, so it fails or could read a Claude session in the same project). On Windows, Vibe counts as detected only when `$VIBE_HOME` exists, as in `install.sh`. Config key: `skipInstall.vibe`; flag: `--skip-vibe`. Off by default. |
| `PLANNOTATOR_SKIP_OPENCODE_INSTALL` | **Read by the install scripts only.** Do-not-write switch for the OpenCode integration (command stubs under `~/.config/opencode/commands`, the OpenCode plugin cache clear, and the stale command-stub sweep). OpenCode has no detection leg, so there is no detected/not-detected reporting, just a skip note. Config key: `skipInstall.opencode`; flag: `--skip-opencode`. Off by default. |
| `PLANNOTATOR_SKIP_SKILLS_INSTALL` | **Read by the install scripts only.** Set to `1` / `true` to skip the skills/slash-command sparse checkout entirely — no `git clone` of the release tag, so nothing is written to any skill or command scope (`~/.claude/skills`, `~/.agents/skills`, the OpenCode command stubs, the Gemini `.toml` commands, `~/.kiro`), the extras are not offered, and the skill-scope cleanup sweeps stay suspended (skip means do-not-write, never remove). The binary, sem sidecar, agent-terminal runtime, hooks, and per-agent config still install, and git stops being a hard requirement. The installer reports `Skills: skipped (...)` and the closing banner stops claiming the `/plannotator-*` commands are ready. Unlike the per-agent opt-outs this is not one agent's home — it covers every scope the checkout writes. Config key: `skipInstall.skills`; flags: `--skip-skills` (bash/cmd), `-SkipSkills` (PowerShell); precedence is flag > env var > config. Used by the `install-script-smoke` CI job, which installs a synthetic `v9.9.9` whose tag has no GitHub counterpart. Off by default. |
| `PLANNOTATOR_SKIP_CLAUDE_PLUGIN_UPDATE` | **Read by the install scripts only.** Set to `1` / `true` to stop the installers from updating an already-installed Claude Code plugin. The plugin comes from a GitHub marketplace, which Claude Code does not auto-update, so by default each installer (`install.sh` `update_claude_plugin_if_installed`, `install.ps1` `Update-ClaudePluginIfInstalled`, `install.cmd` `:UpdateClaudePlugin`, keep the three in step), right after the legacy marketplace-clone `hooks.json` repair, runs `claude plugin marketplace update plannotator` then `claude plugin update plannotator@plannotator --scope user` (always `--scope user`: current Claude Code auto-detects the scope and, run inside a project with a project-scope install, would update that record instead; every printed manual command carries it too) when BOTH the `claude` CLI is on PATH and `plannotator@plannotator` has a user-scope record in `${CLAUDE_CONFIG_DIR:-~/.claude}/plugins/installed_plugins.json` (a record without `scope`, the v1 file, counts as user; a project- or local-scope-only install is left alone). It never installs the plugin and never touches another marketplace or plugin. A pinned install skips it with `Claude Code plugin: not updated: pinned to vX; updating would install the newest plugin.`: pinned means `--version` / `-Version` named a tag other than `PLANNOTATOR_UPDATE_VERSION`, which background auto-update exports with the newest release it just resolved and passes as `--version`, so auto-update runs are not pinned (no extra network call). Each command runs with stdin from `/dev/null` (on Windows the process is started directly, not with `Start-Process`, whose `-RedirectStandardInput` raised "Broken pipe" when claude exited first; its stdin pipe is closed at once in its own try/catch, and only a failing start reads as "could not run claude"), `CLAUDECODE` cleared (an auto-update started under Claude Code inherits it), and a time limit (120 s; pure shell on POSIX, with claude's output and the timeout marker in one private `mktemp -d` directory removed afterwards, the update skipped with the manual commands if `mktemp` fails; `WaitForExit` + kill on Windows; `PLANNOTATOR_CLAUDE_PLUGIN_TIMEOUT` seconds overrides it, an internal knob for the tests). When claude's output says the marketplace is missing (a line naming `marketplace` with `not found` / `not exist` / `no such` / `unknown`), it prints `claude plugin marketplace add backnotprop/plannotator` plus the user-scope plugin update instead of the two update commands. Before/after it reads the record's `version` / `gitCommitSha` / `installPath` and prints `Claude Code plugin: updated to X (restart Claude Code to load it).` or `already up to date (X).`; a non-zero exit or timeout never fails the install and prints `Claude Code plugin: could not update it (<reason>). Run these, then restart Claude Code:` plus the two commands. The closing banner drops the install/update instructions when it updated or found it current, prints only the two manual commands when the plugin is installed but was skipped, failed, or there is no `claude` CLI, and keeps the install instructions when it is not installed. `--non-interactive` does not skip it; `--minimal` exits before it. Config key: `skipInstall.claudePlugin`; flags: `--skip-claude-plugin` (bash/cmd), `-SkipClaudePlugin` (PowerShell), remembered in `install-flags.json` as `skip-claude-plugin`; precedence is flag > env var > config. Off by default (the update runs). |
| `PLANNOTATOR_SKIP_AGENT_TERMINAL_INSTALL` | Set to `1` / `true` to skip installing the managed Node/WebTUI runtime used by compiled Bun builds for the annotate-mode agent terminal. Read by `plannotator install-runtime agent-terminal`, which the installers call automatically. |
| `PLANNOTATOR_MINIMAL` | **Read by the install scripts only**, not by the runtime binary. Set to `1` / `true` / `yes` to have `scripts/install.sh` / `install.ps1` / `install.cmd` install **only** the `plannotator` binary, skipping the sem sidecar, the agent-terminal runtime, all per-agent skills, hooks, slash commands, and config, and the CallDiff runtime even when its opt-in is set. Equivalent to the `--minimal` (aliased to `--binary-only`) flag; `--no-minimal` overrides it. Off by default. |
| `PLANNOTATOR_SKIP_SEM_INSTALL` | **Read by the install scripts only.** Set to `1` / `true` to skip installing the optional `sem` semantic-diff sidecar (used by code review). Off by default. |
| `PLANNOTATOR_INSTALL_CALLDIFF` | **Read by the install scripts only.** Set to `1` / `true` / `yes` to ALSO install the optional pinned, pruned CallDiff core used by code review's Call Flow analysis (about 5 MB on macOS arm64, Node.js 22+). The runtime is strictly opt-in and is NOT installed by default. The normal path is in-app: enabling Call flow consents to one background install of core plus exactly the language packs required by the current changed files; later missing languages install automatically under the same consent, while the Languages list supports install-ahead. Each target gets one automatic attempt per review session; a failed target then requires an explicit Retry in that session. Equivalent to `--with-call-flow` (PowerShell: `-WithCallFlow`) or `{ "installCallFlow": true }` in `~/.plannotator/config.json`; precedence is flag > env var > config. `--minimal` always excludes it. Off by default. |
| `PLANNOTATOR_CALLDIFF_PATH` | Development override for a built CallDiff `0.4.1` package root containing `dist/run.js`; the exact pinned Tree-sitter core and any desired optional grammars must already exist under its `node_modules`. Managed language-pack installation is disabled for overrides. Normal installs use the selective managed core and grammar cache under the Plannotator data directory. |

**Config-only settings (`~/.plannotator/config.json`)**: Some settings have no env-var equivalent and are toggled by editing the config file directly:

- `markdownExtensions` (array of strings, default none) — extra file extensions the **annotate** path treats as markdown, e.g. `{ "markdownExtensions": [".livemd"] }` for Livebook notebooks (#1307). A listed extension is accepted everywhere `.md` is on that path: CLI target resolution (`plannotator annotate notes.livemd`), folder discovery and the file browser, `/api/doc` plus relative and wiki-link navigation between sibling docs, the 2MB `MAX_ANNOTATABLE_FILE_BYTES` cap, and per-file version history. Listed extensions render as **markdown** (frontmatter stripped), never as raw HTML, and they only widen the set: nothing built in is removed. Entries must start with a dot and be free of path separators, globs, and whitespace (`".livemd"`, not `"livemd"` or `"*.livemd"`); invalid entries are dropped silently, built-in extensions are deduplicated, and the dotenv family can never be registered: `.env` itself plus any entry ending in `.env` or starting with `.env.` (such as `.prod.env` or `.env.local`) is denied, because annotate copies file contents into the data dir (the same reason `.env` is excluded from the built-in set). The value is read from `config.json` once per process. Predicates stay pure in `packages/core/annotatable.ts`, which is browser-safe and cannot read config; the node-side resolver that threads the normalized list into them is `packages/shared/markdown-extensions.ts` (vendored to Pi), and the annotate `/api/plan` payload ships the same list to the renderer so it can linkify links to sibling documents. Not applied to plan write (`ALLOWED_PLAN_EXTENSIONS` in `apps/pi-extension/tool-scope.ts`) or to Edit Mode source save (`SOURCE_SAVE_FILE_REGEX` in `packages/core/source-save.ts`), which keep their own narrower allowlists.
- `agentTerminalSide` (`"left"` / `"right"` / `"hidden"`, default `"left"`): which edge the **annotate-mode** Agent TUI docks against, or `"hidden"` to keep it out of the layout entirely (#1050). Type and guard live in `packages/core/agent-terminal.ts:63-83`, the config declaration in `packages/shared/config.ts:116`. Unrecognized values are silently ignored rather than warned about: `getServerConfig()` omits the key behind `isAgentTerminalSide` (`packages/shared/config.ts:374`) and `resolveAnnotateAgentTerminalSide` independently falls back to `"left"` (`packages/core/agent-terminal.ts:90-94`). `"hidden"` is a default, not a lock: the terminal can still be opened for the session from the sidebar rail, the Shift-Shift shortcut, or a message routed to the agent, none of which rewrite the preference, and an opened `"hidden"` terminal docks left (`packages/core/agent-terminal.ts:101-105`). Settings is the only way back from `"hidden"`. Two UI surfaces write the key (the terminal's own Display popover Position control and Settings → General → "Agent TUI Position"), and the Display popover's reset button restores `"left"`. The side only decides where the terminal docks when opened; it never auto-opens (`packages/editor/App.tsx:523`), it is not rendered below 1024px or in wide mode (`packages/editor/agentTerminalLayout.ts:14`, `:73`), and `"right"` visually displaces the annotations/AI right panel while preserving its state (`packages/editor/agentTerminalLayout.ts:53-57`).
- `agentTerminalDefaultAgent` (string agent id, e.g. `"claude"` or `"codex"`, default `""` meaning no recorded choice): which agent the annotate-mode Agent TUI preselects when the panel opens (#1050). Validation is `typeof === "string"` only, with no enum and no check against installed agents, so an unknown or currently unavailable id is inert rather than an error: `resolveAnnotateAgentId` uses the saved id only when it appears among the available agents and otherwise takes the first available one (`packages/ui/utils/annotateAgentTerminal.ts:45-54`). It is written only by the "save as default" checkbox in the terminal's agent picker (`packages/editor/components/AnnotateAgentTerminalPanel.tsx:257`); there is no Settings control for it. An empty string deletes the cookie and reads as unset, though the server allowlist will still write `""` into `config.json`, where it is then ignored.
- Precedence for both agent-terminal keys follows the settings registry (`packages/ui/config/settings.ts`) and its resolver (`packages/ui/config/configStore.ts:3-5`): **server config file > cookie > built-in default**. `config.json` is the durable, cross-browser store; the cookie (`plannotator-annotate-agent-terminal-side`, `plannotator-annotate-agent-terminal-default`) is the browser-local fallback. There is no one-time cookie-to-config migration: those two cookie names were deliberately kept unchanged so a pre-registry cookie stays readable, and its value only reaches `config.json` if the user changes the setting again. The sync runs one direction at startup, with `init()` stamping a valid config value back into the cookie (`packages/ui/config/configStore.ts:157-161`). Neither key has an env-var equivalent, and only the annotate servers allowlist them on `POST /api/config` (`packages/server/annotate.ts:726-727`, mirrored in `apps/pi-extension/server/serverAnnotate.ts:690-691`), so setting them has no effect on plan or review sessions.
- `agentSwitch` (OpenCode; `"disabled"`, an agent name, or `{ "switchTo": "custom", "customName": "<name>" }`; default unset): which agent the session switches to after a plan approval or review feedback (#1390). A settings-registry entry (`agentSwitch` in `packages/ui/config/settings.ts`, the `plannotator-agent-switch` / `plannotator-agent-custom` cookies), so precedence is **server config file > cookie > default**, because Glimpse's webview keeps no cookies between runs and a lost choice used to hand the session to `build`. Unset keeps the surface defaults in `packages/ui/utils/agentSwitch.ts` (plan approval switches to `build`, review feedback stays); resolving that default writes no cookie. One parser, `parseAgentSwitchConfig` in `packages/core/agent-switch.ts` (any trimmed name up to 128 characters with no control characters, as before; agent lists are discovered at run time): the UI codec, `getServerConfig` (a value that does not parse is not advertised) and `agentSwitchConfigToSave` (`packages/shared/config.ts`) use it. Allowlisted on `POST /api/config` by the plan, review and annotate servers in both runtimes; an invalid value answers `400` and saves nothing of that request. No env var.
- `pfmReminder` (`true` / `false`, default `false`) — when enabled, a Plannotator Flavored Markdown reminder is injected at plan-time describing the renderer's extensions (code-file links, callouts, tables, diagrams, task lists, question blocks, hex swatches, wiki-links). The text is one static constant (`PFM_REMINDER`, `packages/shared/pfm-reminder.ts`, vendored to Pi) with no per-request part, so it never breaks a prompt-cache prefix. Lets the planning agent enrich plans with PFM features without having to discover them. Composes cleanly with the compound-skill improvement hook. Supported across all three runtimes: Claude Code (`improve-context` PreToolUse hook in `apps/hook/server/index.ts`), OpenCode (`experimental.chat.system.transform` in `apps/opencode-plugin/index.ts`), and Pi (`before_agent_start` in `apps/pi-extension/index.ts`).
- `inboxNotifications` (`{ enabled?, dismissed?, allowedOrigin? }`, default: on, not dismissed, no origin) — the Plannotator Inbox's browser notifications (see "Notifications" under "Plannotator Inbox"). Written by the Inbox page (its one-time ask and Settings) through `POST /api/inbox/settings` `{ notifications: { enabled?, dismissed?, allowed_origin? } }`, never localStorage, because the browser's permission is per origin and the Inbox's port can change; `allowedOrigin` is the page origin where the person last turned them on, so a page on a new port asks again. No env-var equivalent. `inboxTool` (the Inbox tool switch) is in the `PLANNOTATOR_INBOX_TOOL` row.
- `inboxReminder` (a boolean for every host, or one per host: `{ "inboxReminder": { "claude-code": false } }`; default: on wherever the session has the Inbox tool): the Plannotator Inbox's one-line reminder at session start, `INBOX_REMINDER_TEXT` in `packages/shared/inbox/connection.ts` ("Plannotator Inbox is on: when you finish long work, or need a decision the person isn't here to give, send it with plannotator_inbox send_message and keep going. Their reply comes back here. Run `plannotator inbox --help` for how it works."; OpenCode 1, and an OpenCode 2 host without `session.prompt` (no wake), get `INBOX_REMINDER_TEXT_NO_WAKE`, which names `wait_for_reply` instead; `inboxReminderText(toolName, { wakes })` builds either with a host's own tool name). Only ever in a session that has `plannotator_inbox` and only once the Inbox has run on this computer (`inbox/inbox.json` exists at session start: on Pi and OpenCode the tool already needs it; the Claude Code mod registers the tool before the first run but gives no reminder then), so the tool switch (`PLANNOTATOR_INBOX_TOOL` / `inboxTool`) turns it off too; there is no env var of its own (`resolveInboxReminder(config, env, host)` = `resolveInboxTool(...) && (configuredInboxReminder(config, host) ?? true)` in `packages/shared/config.ts`; the mod's mirror `resolveInboxReminderEnabled` in `apps/hook/hooks/mod/enabled.ts`, kept equal by `enabled.test.ts`). Read once per session start with the tool, never mid-session. Fixed text in a cache-safe place per host: the Claude Code mod adds a `plannotatorInbox` block in `prompt.context` (the context of the conversation's first message, once per conversation, after the system prompt and tools, never invalidated), naming the tool by the full name `$.tool.register` returned (`mcp__<server>__plannotator_inbox`) so tool search finds the deferred tool, and never in a `-p` session or when the register call failed; Pi returns one hidden custom message (`customType: "plannotator-inbox-reminder"`, `display: false`) from `before_agent_start` on the session's first prompt, not again after `/reload` or `/resume` (`entriesCarryReminder` reads the branch), again only after a compaction that summarized it away, never `systemPrompt`, and the "Ask this session" bridge never reads it as a take-over; OpenCode 2 composes it into the system part (`addInboxReminder` in `server.ts`, a `context` hook: only on a request that offers `plannotator_inbox`, never for a subagent or a title request, the same bytes on every request; gated on the Inbox connection, since OpenCode 2 applies a tool transform lazily) and OpenCode 1 appends it to the end of the LAST system part in `experimental.chat.system.transform`, so the text before it stays byte for byte and the part count never changes (#1114: 1.18 sends one part, and single-system-message chat templates such as Qwen3's break on two), only for an agent that has the tool (`openCode1AgentHasInbox`: not a subagent, not an agent whose `tools` switch `plannotator_inbox` off, wildcards included); an agent lookup that fails reuses the session's last answer (none yet: no line), so the prompt never flips between requests. No env-var equivalent; set it in the Inbox's Settings → Agents (the reminder switch per agent) or in config.json.
- `inboxAgentNotes` (`{ offered?, asked? }`): the Inbox window's note dialog, asked once PER AGENT. `asked` lists the agents it was asked about (Add, Not now, Don't add a note, the band's Settings link, a yes in Settings → Agents' note switch, or `plannotator inbox --notes` for each note it added), and always every agent that has the note (a record in `inbox/agent-notes.json`, or a found agent whose file holds the section: `noteHolderIds`, saved the first time one is missing), so removing a note never brings the question back; an agent not in it is asked when it becomes a candidate. `offered` is true once anything was answered (kept so an older Inbox reading the same file never shows its card). A config from 0.28.18 or older (`offered` alone) is turned, at its first read, into the agents that can take a note at that moment plus every agent that has the note (`notesAsked` in `packages/server/inbox-agent-notes.ts`), so nobody who answered then is asked again while an agent found since is. Which notes exist is kept in `inbox/agent-notes.json`. See "The note in each agent's instructions" under "Plannotator Inbox". No env-var equivalent.
- `inboxTextSize` (12, 13, 14 or 15; default 14): the Plannotator Inbox window's text size, the body size its whole type ramp scales from (see "Text size" under the window's Settings in "Plannotator Inbox"). Written by the Inbox's Settings → General → Appearance through `POST /api/inbox/settings` `{ text_size }`; anything else is refused with `422`, and an unreadable value reads as 14. No env-var equivalent.
- `inboxSound` (`{ enabled?, volume?, dialogDueFor?, dialogShownFor? }`, default: on, volume 60) — the Plannotator Inbox's question sound (see "The question sound" under "Plannotator Inbox"). `enabled` and `volume` (a whole number from 10 to 100) are written by the Inbox's Settings row and its one-time dialog through `POST /api/inbox/settings` `{ sound: { enabled?, volume? } }`; anything else is refused with `422`. The two dialog marks are the server's own: `dialogDueFor` is set at the first start of a release version that finds someone who used an earlier Inbox, and stays until a page claims it; the compare-and-set on `POST /api/inbox/sound/dialog` turns it into `dialogShownFor`, which a fresh install gets at its first start instead. Once `dialogShownFor` is set the dialog never shows again. Kept in config.json for the same reason as `inboxNotifications`. No env-var equivalent.
- `inboxTailscaleAllow` (array of Tailscale logins, default none): logins the tailnet-published Inbox lets in besides the machine's owner, for a shared tailnet where you sign in as another login on another device, or a tagged machine, which has no owner (publishing is refused there until this names someone). Entries are trimmed and compared case-insensitively; non-strings and entries with whitespace are dropped (`resolveInboxTailscaleAllow`). Read at each publish, so a change applies at the next publish (the switch off and on, or the next start). No env var or flag (deferred). What a login let in can do: everything the window does, and a reply, and above all a New message, becomes a turn in a live agent session on this machine. So any allowed login, or anyone holding the owner's unlocked, signed-in phone, can drive agents that run commands here. Let in only logins you would let sit at this computer. `inboxTailscale` (the switch) is in the `PLANNOTATOR_INBOX_TAILSCALE` row.

**Legacy:** `SSH_TTY` and `SSH_CONNECTION` are still detected when `PLANNOTATOR_REMOTE` is unset. Set `PLANNOTATOR_REMOTE=1` / `true` to force remote mode or `0` / `false` to force local mode.

**Devcontainer/SSH usage:**
```bash
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_PORT=9999
```

**Compressed app page for network sessions (#1617):** remote-mode and `--tailscale` sessions serve the single-file app HTML compressed, negotiated on `Accept-Encoding` (brotli q5, else gzip 6), with `Vary: Accept-Encoding`. Browsers advertise `br` only to HTTPS and localhost origins, so direct plain-http remote mode is served gzip and `--tailscale` (HTTPS) brotli; each server prewarms that likely encoding at start and compresses the other lazily, cached per process (bounded to 4 bodies, which persist for the life of long-lived Pi/OpenCode hosts). Plain local sessions serve the page exactly as before, because on loopback compression only added latency. One shared helper, `packages/shared/app-html.ts` (vendored to Pi), serves every app-HTML route in both runtimes; API responses are never compressed. The single-file builds also drop KaTeX's `woff`/`ttf` fallbacks (`build/katex-woff2-only.ts`); every supported browser loads `woff2`.

**Tailnet sessions (`--tailscale`):** `plannotator review --tailscale` (also `annotate` and `annotate-last`/`last`; other subcommands reject the flag with a clear error; Bun CLI only, not mirrored to Pi) publishes the session over the user's tailnet instead of remote mode: the server stays **loopback-bound** and the CLI orchestrates `tailscale serve --bg --https=<port> http://127.0.0.1:<port>`, so devices on the tailnet reach the session over HTTPS while nothing listens beyond localhost and nothing is ever public (serve, never funnel). The advertised HTTPS URL prints on stderr with a terminal QR code (TTY only), and a publishing failure exits `1` — or `2` under a strict annotate gate (`--require-approval` / `--result-file`), where `1` is reserved for "the reviewer did not approve" and a publish failure is a startup failure like any other — with an actionable message instead of leaving the loopback server hanging (CLI missing, daemon down or logged out, unparsable `serve status` output — which fails closed, or no serve URL matching the session port). A pre-existing serve mapping on the chosen port — background or foreground session, which Tailscale prefers — aborts rather than being stolen, and mappings on other ports are never touched. Mappings the process creates are cleaned up on normal exit and on SIGINT/SIGTERM/SIGHUP (all routed through `process.exit` so exit handlers run; the SIGHUP route is installed by `enableTailscaleServe` only once a mapping exists — an unconditional SIGHUP listener would override the ignored disposition `nohup` depends on, so plain non-tailscale sessions keep no SIGHUP listener and `nohup plannotator review &` survives terminal close); a failed teardown retries once and then warns with the exact manual command, and a hard kill (SIGKILL) or reboot can leave the mapping — `tailscale serve --bg` state persists — so remove it with `tailscale serve --https=<port> off`. Combined with `PLANNOTATOR_REMOTE`/SSH detection, `--tailscale` wins and forces local mode with a stderr notice — the wide `0.0.0.0` bind would only broaden exposure (`urlHost` is also suppressed for the run; the advertised URL comes from serve). `tailscale serve` forwards the browser's own Host header (the MagicDNS name), so the CLI adds the serve hostname to the server's Host allowlist once serve reports it (see "Host allowlist" under Server API). The annotate agent terminal is **off by default** in `--tailscale` sessions, exactly like remote mode, because the session is reachable across the tailnet and the PTY token is not an auth boundary; enable it with `PLANNOTATOR_AGENT_TERMINAL_REMOTE=1`. Open-in (`/api/open-in`, `/api/open-in/apps`) is off outright in `--tailscale` sessions, as in remote mode, with no override: a launch would open an app on this machine for whichever tailnet device sent it. Orchestration lives in `packages/server/tailscale-serve.ts` on shared parsers in `packages/shared/tailscale.ts`. The Plannotator Inbox has its own `plannotator inbox --tailscale` (owner-only, persistent, a separate listener; see "Over your tailnet" under "Plannotator Inbox"), which this per-session flag never handles (`index.ts` leaves `--tailscale` to the `inbox` subcommand).

**The crash window (both `--tailscale` forms).** A `--bg` serve mapping outlives its process. After a SIGKILL, an OOM kill or a reboot it keeps pointing at a loopback port that nothing holds any more, and any local server that later binds that port is published to the tailnet until the mapping is removed. `review` / `annotate` sessions have no record to recover from: remove it with `tailscale serve --https=<port> off`. The Inbox records its mapping in `inbox.json` before making it, and every Inbox start (and `uninstall --purge`) removes a recorded mapping whose proxy port is not its own, so the window closes at the next start; until then it is open. A loopback-only proxy target that no other process can take (a unix socket) is the follow-up that closes it.

## Plan Review Flow

```
Claude calls ExitPlanMode
        ↓
PermissionRequest hook fires
        ↓
Bun server reads plan from stdin JSON (tool_input.plan)
        ↓
Server starts on random port, opens browser
        ↓
User reviews plan, optionally adds annotations
        ↓
Approve → stdout: {"hookSpecificOutput":{"decision":{"behavior":"allow"}}}
Deny    → stdout: {"hookSpecificOutput":{"decision":{"behavior":"deny","message":"..."}}}
```

### Plan review header decision control (#1057)

Approved design: "plan-review-decision-control" (owner approval 2026-10-21, design record not in this repo; built as the proposal shows). Plan review's header uses the same `DecisionControl` annotate and code review use, from the pure `buildDecisionSpec({ app: 'plan', plan: { answers, directEdits, answersOnly, agentName, approveTarget } })` (`packages/ui/utils/decisionSpec.ts`), with no ghost Close (a plan review ends with a decision). It replaced the old pair (an outlined Send Feedback beside a green Approve, OpenCode's `ApproveDropdown`), the "Add Feedback First" dialog (the empty Send Feedback path is now **Request changes…** in the caret) and the Claude Code "Feedback Won't Be Sent" dialog with its faded Approve and hover note (#1457).

- **States.** Nothing to send: **Approve** (OpenCode: `Approve → <agent>`, the agent switch target, cut at 24 characters), caret: "Approve with a note…" (only where notes on approval are delivered) and "Request changes…". Something to send: **Send Feedback**, or **Send answers** when the only feedback is question answers (`isAnswersOnlyFeedback`); caret: "Send with a note…" ("Send answers with a note…"), "Approve with notes" (only where delivered; `→ <agent>` on OpenCode), and always "Approve, discard N annotations…" (the noun follows the feedback: answers, annotations, direct edits) with one confirm, "Discard & approve". Where notes would be lost, that row's subtitle and confirm name the agent ("Claude Code can't take notes on approval").
- **Which hosts take notes on approval is a server advert, not the agent's name.** Both plan servers advertise `approvalNotesSupported` on `/api/plan` (Bun `ServerOptions.approvalNotesSupported`, Pi `startPlanReviewServer`'s option; absent or false reads as false in the tab, so an older server offers no approve-with-notes row). Set true by: the Claude Code mod's `claude-mod-plan` (`planHostResult` composes approved-with-notes), the OpenCode CLI bridge (`opencode-plan`) and the embedded OpenCode plan server (the `submit_plan` executor), and Pi's `startPlanReviewBrowserSession` (`deliverPlanDecision`; the event API's result carries `feedback`). Left false: the classic Claude Code PermissionRequest hook (its allow carries no message), Gemini CLI (a `systemMessage` is shown to the person, not the model), Codex, Copilot CLI, Mistral Vibe, and archive.
- **Transports are unchanged.** Primary and Mod+Enter are one `submitPrimaryDecision` (`submitPrimaryDecisionRef`): Approve posts `/api/approve` (with `permissionMode` for Claude Code, `agentSwitch`, `planSave`, the notes integrations, `serverSession`, `planRevision`), Send Feedback / Send answers post `/api/deny` (`answersOnly: true` only for answers alone). Routing is pure in `packages/editor/planDecision.ts` (`resolvePlanDecisionAction`): a note becomes a `GLOBAL_COMMENT` and is posted one render later (annotate's #1436 mechanism, `queueNoteDecision`), on `/api/deny` for Request changes / Send with a note and on `/api/approve` for Approve with a note; "Approve with notes" posts the approval with the session's feedback (what plan Approve always sent); the confirmed discard posts a bare approval (`handleApprove({ discardFeedback: true })`, no `feedback`). Every approval goes through `requestPlanApprove`, so the unsaved-file-edit warning and OpenCode's "Agent Not Found" check run on every approve path, and that dialog's "Approve Anyway" runs the captured continuation (a confirmed discard stays bare). A note on Send answers makes the deny mixed (the note is a comment), so it carries the denied prompt, as any mix does. Unlike annotate's L3 retry, a queued plan note decision is never left armed: after any refusal (409 `plan_revised`), cancelled warning (Agent Not Found, unsaved file edits) or failed POST it is dropped, the note stays as an ordinary general comment, and the primary means what its label says (Send Feedback posts the deny); the reviewer decides again from scratch. A plan revision waits while the decision note is open (`[data-decision-note-input]` and the compact `[data-decision-note-composer]` are in `PLAN_REVISION_COMPOSER_SELECTOR`, `packages/editor/hooks/usePlanRevisions.ts`). When the only feedback is saved file changes (a host that grants source save), the approve-away row reads "Approve without telling the agent…" and its confirm says the changes are already on disk (`plan.savedFilesOnly`); plan review's own servers grant no source save, so this does not arise there today.
- **Menu rows that are not decisions** go through `DecisionControl`'s `menuFooter` (`packages/ui/components/PlanDecisionMenuExtras.tsx`): OpenCode's agent picker as an "After approval, switch to" radio section (`role="menuitemradio"`, the arrow keys reach it; a pick writes the `agentSwitch` setting and keeps the menu open; shown in both states), and for Claude Code one read-only line, "After approval, Claude Code runs in <mode>", with **Change** (closes the menu, opens Settings). Settings' Permission Mode row now reports a change (`onPermissionModeChange`), so the mode Approve posts and the line show follow it within the session (before, a mid-session Settings change applied only to the next session).
- **Compact/touch rows** come from the same spec (primary row, then one row per caret item; composers open `DecisionNoteDialog`, the discard row its confirm), as annotate's do. The agent picker and permission line are desktop only (Settings has both).
- **No new keyboard shortcuts.** Tests: `packages/ui/utils/decisionSpec.test.ts` (the plan arm and the invariant sweeps), `packages/editor/planDecision.test.ts`, the DOM test `packages/editor/App.planDecisionControl.test.tsx` (each host and state, and the bodies), `packages/server/plan-approval-notes.test.ts` and its Pi mirror, the advert in `apps/hook/server/claude-mod-plan.test.ts` and `apps/opencode-plugin/plan-review-lifecycle.test.ts`.

### Pi plan review does not block

On Pi, `plannotator_submit_plan` returns as soon as the review server is up
("submitted for review … end your turn and wait", `terminate: true`) instead of
holding the tool call until the reviewer decides, so the session stays usable
during review and "Ask this session" works there. The decision is delivered
later by `deliverPlanDecision` (`apps/pi-extension/index.ts`) as a
`pi.sendUserMessage(..., { deliverAs: "followUp" })`, the same delivery review
and annotate feedback use: approval switches to the executing phase first
(tools, model, `plannotator-execute` entry) and sends the approved /
approved-with-notes prompt, which starts the execution turn and its framing;
deny and answers-only send `composePlanDeniedMessage`; external execution mode
hands off and records a non-triggering `plannotator-handoff` message. Nothing
is implemented before approval because the phase stays `planning` while the
review is open, so the planning write gate still holds. The open review is
closed (and its decision dropped) when plan mode is left, when a `/tree` path is
not planning, and on `session_shutdown`; a plan decision is never re-targeted to
a replacement session. The Esc-aborts-the-review behavior of the old blocking
tool is gone: leaving plan mode is how to abandon a review. Closing it first
calls the plan server's in-process `closeKeepingDraft()` (never reachable over
HTTP, where a plan review stays unclosable): open tabs get the `session-closed`
event with `by: "session"` (the tab shows "Review Closed", not "Closed by the
Agent", which stays for `by: "agent"` host closes), and a late approve/deny
answers `409`. The saved draft survives the close, but the server stops right
after, so the last unsaved keystrokes (the draft autosave's debounce window)
may be lost. The same close runs when planning ended while a review was still
starting. Reviews opened through the `plannotator:request` event API
(`plannotator-events.ts`) deliberately do NOT close on `session_shutdown`: the
README promises `review-status` lets a caller recover across session restarts,
so a decision made in that tab after `/reload` is recorded for `review-status`
and never emitted (the replaced runtime's bus is gone). That status file is
written atomically (temp file + rename), and one that cannot be parsed is left
untouched (logged, the write skipped) rather than restarted from `{}`.
Decision listeners run on a microtask (`publishDecision` in `serverPlan.ts`),
because a replaced runtime's `pi.events.emit` throws Pi's stale-ctx error
synchronously and an escape inside the HTTP handler ends the Pi process
(#1864). In `plannotator-events.ts` the review-result emit, `request.respond`
and the status writes are each wrapped in try/catch; `index.ts`'s
`handoffApprovedPlan` emit is not wrapped itself: it runs either inside the
submit tool call (auto-approve, a live session) or behind
`deliverPlanDecision`'s liveness check inside a caught promise chain.

**Revisions while a review is open update the same tab**: a resubmission while a review is pending calls the Pi plan
server's `updatePlan`, which saves a new history version (slug from the revised
heading, `previousPlan` from that slug's prior version) and bumps a revision
counter. `/api/plan` carries `planRevision`; the plan editor polls
`/api/plan/revision` every 2s only when that field is present
(`packages/editor/hooks/usePlanRevisions.ts`) and loads the revision in place
through `applyEditedDocument` (annotations re-anchor by text, the diff base
re-seeds through `usePlanDiff`'s docKey). It waits while Edit Mode is open or
holds direct edits, or a linked document is open. Approve/deny bodies echo
`planRevision`, and the server answers `409 { code: "plan_revised" }` to a stale
one, so a reviewer cannot approve text the agent replaced; the tab then loads
the revision and the reviewer decides again. Both plan servers implement it (`updatePlan` on the
server result, `/api/plan/revision`, the 409) but advertise `planRevision` only
when the caller passes `planRevisions: true`; today only Pi's
`plannotator_submit_plan` and the Claude Code mod's `claude-mod-plan` do, so
classic Claude Code, OpenCode and the Pi event-API `plan-review` action keep a
tab that never polls and sends unchanged bodies.
A decision claims the review right after the revision check (before the note
integrations are awaited), so `updatePlan` refuses from then on; a Pi
resubmission that hits that refusal tells the agent to wait for the decision
instead of opening a second review. The tab also holds a revision while a
comment composer or annotation popover is open.

**Execution works from the approved text, not the file.** The Pi plan
server's approve decision carries `plan`, the exact text on screen when the
reviewer approved. `deliverPlanDecision` appends it to the approval message
under "## Approved plan", records it on the `plannotator-execute` entry
(`approvedPlan`), and executes from it: the checklist, the per-turn framing
and resume (`resyncPhaseFromSession`) read the snapshot instead of re-reading
the plan file, and checkmarks are written back to the file only while its
checklist still matches the approved one. If the file differs from the
approved text at approval, the message says so and tells the agent not to
execute the unreviewed edits (to keep them, the user returns to plan mode and
the agent resubmits). Auto-approved plans (no UI) keep the file as their
source.

### Pi: the `plannotator` tool

The extension registers the shared tool contract
(`packages/shared/plannotator-tool.ts`, vendored as
`generated/plannotator-tool.ts`) with `pi.registerTool`: name, description,
validation (`parsePlannotatorToolInput`), argument mapping and result text all
come from it, and `parameters` is `PLANNOTATOR_TOOL_INPUT_SCHEMA` itself
(plain JSON Schema, which Pi validates without a TypeBox Kind since 0.79.1,
the peer floor; `plannotator-tool.test.ts` runs the installed Pi's
`validateToolArguments` against it). `executionMode: "sequential"` (#1622: an
"edit, then open" batch opens the edited file).

**Registration and activation are decided once per session.** The tool is
OFF by default on Pi and registered only when the agent tool switch turns it on
(`PLANNOTATOR_AGENT_TOOL=1` / `{ "agentTool": true }`, `resolveAgentTool(...,
host)` read once when the extension instance loads; Pi builds a new instance
per session and per `/reload`). Inside Oh My Pi (`detectPiHost(pi)` in
`pi-host.ts` answers `oh-my-pi`) the host is `oh-my-pi` and the tool is ON by
default, because OMP lists an extension tool as one short `xd://plannotator`
line instead of sending its definition; `PLANNOTATOR_AGENT_TOOL=0` /
`{ "agentTool": false }` keep it out there. `setPiHost` records the host for
the extension's review servers, whose `serverConfig` then advertises
`agentToolHost: "oh-my-pi"`. `omp.test.ts` (opt-in, the real `omp`) proves the
default on, the one line and no tool-list entry. Off, nothing is registered and the slash
commands are unchanged. It is registered with
`defaultActive: false` (Pi 0.99+ then leaves it inactive; older Pi ignores the
key and activates every registered tool), and the first `session_start`
(`settleAgentToolActivation`) makes it active when `ctx.hasUI`, inactive in
print/JSON mode, before the session's first request, and never touches it
again. Plan mode's `setActiveTools` calls add and release only the tools they
own, so `plannotator` stays in the tool list (and the prompt prefix) through
planning, execution, completion, leaving plan mode, `/tree` and `/reload`:
`agent-tool-stability.test.ts` drives that whole lifecycle over a fake Pi that
models both activation rules and fails on any request without the tool or any
`setActiveTools` that flips it after the start; it also pins the registered
description/parameters to the shared constants, no `promptSnippet` /
`promptGuidelines` on any Plannotator tool, and no `systemPrompt` from
`before_agent_start`.

**The bundled knowledge skill is user-invoked only.** `vendor.sh` adds
`disable-model-invocation: true` to the vendored copy's frontmatter (the
source `apps/skills/core/plannotator` stays model-invocable for the installers
that ask, #1377), so an npm-only Pi install keeps the #842 promise of no
Plannotator skill in Pi's system prompt; `/skill:plannotator` still loads it,
and the model learns the tool from the tool's own description. A CLI install's
`~/.agents/skills` copy still wins when present (#1642) and carries the
installer's model-invocation choice.

**One launch path.** `/plannotator-review`, `/plannotator-annotate`,
`/plannotator-last` and the tool share `launchCodeReview` / `launchAnnotate` /
`launchLastMessage` in `apps/pi-extension/index.ts` (in-process server,
"Ask this session" bridge, decision as a `followUp` message). The commands
notify a launch error; the tool throws it, which Pi reports as an error
result. Tool differences: the annotate target is ONE argument, so the #1182
tolerant word split never runs on it (`tolerant: false`); an opened review
returns `plannotatorToolOpenedText` with `terminate: true`, so the turn ends
and the session is idle for Ask; a gated session the tool opened delivers a
bare Approve as a message (`deliverApproval`, the mod's rule). The tool's
`last` skips the assistant entry holding the calling tool call
(`isAssistantEntryForToolCall` in `assistant-message.ts`): Pi saves an
assistant message at message_end, before its tools run, so otherwise the
agent's own "opening it now" message would open, and would head the picker.
On one fixed port (remote mode or a single `PLANNOTATOR_PORT`, read from
`getServerPorts`) a second open is refused while any review is open
(`fixedPortBusyText` names it), because the new server would otherwise
self-preempt the open one silently. A list target opens ONE `annotate-bundle`
review through the same `launchAnnotate` the slash command uses: the list goes
to the shared `selectAnnotateTokenTarget` as pre-split tokens (paths with
spaces survive), only the `bundle` selection opens (a missing entry answers
`buildMissingAnnotateFilesMessage`; a folder, URL or bare name refuses, so the
tool never opens fewer files than named), `resolveAnnotateBundleFiles` checks
types and size, and the subject is `plannotatorBundleSubject` (`2 files:
spec.md, notes.md`) in the result, list, close and decision heading; feedback
names every file (`Files:` + `annotateBundleTargetText`). A session without
UI (print/JSON mode) never has the tool active (see above), and a call that
reaches it anyway is refused, since nothing could deliver the decision later.

**Sessions, list and close.** Every review the extension opens (tool,
commands, `plannotator_submit_plan`) is recorded in ONE process-wide registry
(`getProcessPiReviewRegistry` in `apps/pi-extension/plannotator-tool-host.ts`,
on `globalThis`) with a `pn-` id until its decision settles. Process-wide
because Pi builds a new extension instance on `/reload` and `/resume`, and a
per-instance map would forget the open reviews of a session that merely
reloaded. `list` and `close` see only entries whose owner is the calling ctx's
`sessionManager.getSessionId()`, so another session's reviews (including the
previous one after `/new`) are never in reach; the global `sessions/` registry
is never read. `unsent` and `decided` come from the server's
in-process `hostControl.status()`; `close` calls `hostControl.close()` (the
reviewer's Close marked `closedBy: "agent"`, draft kept, tab told), so it
works in remote mode too, where the HTTP endpoints are off. A review the agent
closed delivers nothing: its decision handler notifies "the agent closed …"
instead (user-facing notices name a last-message review "the agent's last
message"; agent-facing texts say "your last message"). Plan reviews are listed
as `Plan vN` (the history version, read from `updatePlan`'s no-op answer for
the same text, and from each revision) and never closed.
Review, annotate and last decisions (commands included) now start with
`plannotatorDecisionHeading` (`Plannotator: notes.md (pn-3f2a9c) — Feedback ·
2 comments.`); outcomes follow the mod: a code review that is not an approval
is `Changes requested` (` · N comments` when it carries annotations), and the
PR-platform status post, which the review server marks `platform: true`
(#1719, `classifyReviewOutcome` in `apps/pi-extension/review-outcome.ts`), is
`Review posted` (`PLANNOTATOR_OUTCOME_REVIEW_POSTED`, shared with OpenCode 2) and delivered verbatim, without the verification
suffix. Every review decision whose feedback has content is delivered,
zero annotations included (PR description, PR comment and editor notes ride
only in the feedback text); nothing is inferred from the annotation count.
Plan decisions are unchanged. Pi cannot take over an agent's
shell `plannotator` command: its `tool_call` event can only block a call, which
the model reads as an error, so the skill's "use the tool" line is what steers
it.

### Pi: session events and the checklist window

**`plannotator:session-opened` / `plannotator:session-closed` (#1589).** One
pair per Pi review, whatever opened it (`apps/pi-extension/session-events.ts`):
the `/plannotator-*` commands and the `plannotator` tool (`trackReview` in
`index.ts`, at the registry's add and its decision or failure), plan review
(the submit tool, closed by its decision, by `stopPendingPlanReview` or by its
server stopping), and `plannotator:request` code-review / annotate /
annotate-last / plan-review (`plannotator-events.ts`, which now starts the
session and waits on it itself so the URL is known before the decision).
Opened: `{ id, action, url, openedAt, piSessionId?, reviewId?, requestId? }`,
`id` the registry's `pn-` id (a fresh `pn-` id for `plannotator:request`
reviews, which are not in the registry; unique among the open reviews both
ways: `newSessionEventId` skips ids the registry or an announced review holds,
and the process registry skips ids an announced review holds,
`isSessionEventIdOpen`), `action` one of `plan-review`,
`code-review`, `annotate`, `annotate-last`. Closed: the same plus `outcome`
(`approved`, `submitted`, or `closed` with `closedBy` `reviewer` | `agent` |
`stopped` | `error`) and `closedAt` (`sessionEndOf` / `sessionEndOfError`).
The handle emits closed at most once; an event with no live bus is dropped. Archive emits neither. **Cache safety:** they go
on `pi.events` only, never a message, entry, system prompt or tool list.
**Stale runtimes (#1864):** every emit runs on a microtask inside try/catch;
it goes through the opener's `pi` when the opener's session was live at the
moment of the open or close, else (or when that throws) through the instance
that last claimed a process-wide slot (`claimSessionEventBus` at
`session_start`, released at `session_shutdown`, on `globalThis` under a
versioned key; a holder that throws, torn down without releasing it, is
forgotten quietly), else nowhere, silently. So a review that ends after `/reload`
reaches the replacement's bus and never throws out of a handler.
`session_shutdown` now calls `stopPendingPlanReview()` first, so a plan review
the session ends closes on its own bus. `plannotator:request` reviews use the
listener's own `sessionLive`, so after a replacement their close goes to the
live instance's bus or nowhere (never the dead one; `plannotator-events.test.ts`
pins that nothing is logged). Proofs: `apps/pi-extension/session-events.test.ts`
(over a fake Pi whose instances share one bus and whose replaced instance
throws Pi's stale-ctx error: every model request, the active tools with their
definitions, `before_agent_start`'s results and every message, is
byte-identical while reviews open, close and outlive `/reload`, and identical
again with a bus that throws; the pair per entry point and outcome) and the
session-event cases in `plannotator-events.test.ts`.

**The checklist widget scrolls (#1412).** Pi draws at most 10 lines of a
widget (`InteractiveMode.MAX_WIDGET_LINES`), so `updateWidget` sends
`checklistWindow(checklistItems)` (`apps/pi-extension/checklist-window.ts`):
all items when there are 10 or fewer, else 10 items ending on the first open
one (the first 10 until it is past them), and the last 10 once everything is
done. `setWidget` only; the status line keeps the full count.

### Claude Code mod: non-blocking plan review, annotate, review and last

Where Claude Code runs hooks modules ("Claude Mods": function hooks, CLI only,
2.1.287+), the plugin's `hooks/hooks.json` also loads `apps/hook/hooks/mod/register.ts`
(`"modules": ["./mod/register.ts"]`). No Plannotator session then holds a tool
call open: the mod starts the CLI detached, returns at once, and delivers the
reviewer's decision later as a plugin turn (`$.prompt.submit`, read by Claude
as a message from the `plannotator` plugin). The UX spec is an
owner-reviewed draft (design record, not in this repo); its open questions
are not answered yet, and the conservative choices below are the ones taken.

**On by default; opt out with `PLANNOTATOR_CLAUDE_MOD=0` or `{ "claudeCodeMod": false }`.**
The owner's call: every Claude Code that runs hooks modules (current Claude Code
loads them even with `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` unset) gets the
non-blocking flows, the `plannotator` tool and the Bash take-over of
agent-run `plannotator` commands (below). With the knob off `session.start` stops before doing
anything (no `$.command.register` or `$.tool.register`, no `$.env.set`, no
`$.store`, no process) and every other hook passes straight through with
`next(e)`, so the classic PermissionRequest hook and the `/plannotator-*`
skills run as they do without mods. See the env table row.

**Inert without mods.** Checked live: Claude Code 2.1.150 (no hooks modules)
validates and loads the plugin with the `modules` key, ignores it, and runs the
classic PermissionRequest command hook (the blocking review) exactly as before;
2.1.288 with modules on runs the mod and never reaches that command hook. The mod
also stands down by itself (every hook passes through) in `-p` / SDK sessions
(`isInteractive` false: a later plugin turn would have no session to land in)
and where `/bin/sh` is missing (Windows), leaving the classic hook and the
`/plannotator-*` skills in charge. A mods-capable Claude Code whose rollout
switch is off could not be reproduced locally; the engine only inserts modules
into the hook chain when they load, so it should behave like 2.1.150.

**Files.** `register.ts` holds every `$` call (`claude plugin validate` follows
`$` only through top-level functions and inline hooks) and builds a `Host` of
closures; `controller.ts` (`PlannotatorMod`) is the per-session state machine;
`launch.ts` (detached launcher, launch-directory layout, command table, copy),
`delivery.ts` (turn vs log, 12 KB inline limit), `plan.ts` (ExitPlanMode
decisions and deny copy), `turns.ts` and `bridge.ts` (Ask this session),
`shell-words.ts` (argument splitting), `tool.ts` (the `plannotator` tool contract, a copy of `packages/shared/plannotator-tool.ts`), `take-over.ts` (agent-run Bash `plannotator` commands answered through the tool), `inbox.ts` and `inbox-contract.ts` (the Plannotator Inbox connection, below; the contract a copy of `packages/shared/inbox/connection.ts`). The mod is self-contained: a plugin
installed from the marketplace is only `apps/hook/`, and a hooks module may
import only its own files.

**Detached launch.** `$.process.run` is one-shot (10 minutes at most) and a hook
has a 10 s budget of its own time, so the mod runs a tiny `/bin/sh` wrapper
(`LAUNCH_SCRIPT`) that starts `plannotator <subcommand> <args>` in the
background with stdin/stdout/stderr on files and returns in milliseconds. The
launch directory is `${PLANNOTATOR_DATA_DIR or ~/.plannotator}/claude-code-mod/<session id>/<launch id>/`:
`stdin`, `ready` (`PLANNOTATOR_READY_FILE`), `result.json`
(`PLANNOTATOR_HOST_RESULT_FILE`), `stdout`, `stderr`, `pid`, `exit` (written
after the CLI exits), `revision.json` + `.ack` (plan revisions),
`messages.json` (`PLANNOTATOR_HOST_MESSAGES_FILE`, `last`'s picker list),
`watcher.json` and `settled/by` (see "Two processes on one session" below) and
`feedback.md` (oversized feedback). Waiting inside a hook (for the ready file, a
revision ack) happens in a `$.process.run` shell loop (`waitForAny`), never a
`$.clock` wait, which would spend the hook's budget and let the engine run the
call on without the mod. Once a review is open, a 1 s `$.clock.every` timer
(the mod has no listener) reads `result.json`, notices an `exit` with no result
("the review server stopped … your draft is saved"), and every 15 s checks the
pid with `kill -0`. Open launches and a pending plan approval persist in
`$.store` and reattach on `session.start` for the same session id
(`--resume`, `--continue`, a restart; on 2.1.290 `--continue` keeps the session
id). The fork paths do NOT reattach: `--fork-session` and `/clear` start a new
session id, so the reviews stay with the old id and come back only when that
session is resumed (re-adopting them across a fork is a follow-up).
`session.start` does not fire for
`/clear` or an in-process resume (the process goes on under another session
id), so `session.end` disposes the instance (timer and bridges stop; nothing is
delivered into the next session) and the next hook that needs the mod makes a
new one for the current id, restoring that session's open reviews. The launch
directory is created owner-only (`umask 077`, `chmod 700`) before `stdin` is
written; once a decision is delivered its files are removed (`cleanupArgv`),
except `feedback.md`, which Claude reads afterwards. A launch whose server
crashed keeps its directory (its `stderr` explains why). Servers outlive Claude Code on purpose:
the wrapper ignores SIGHUP and starts the CLI under `nohup` (a closing terminal
otherwise took the server with it), so closing the terminal does not lose a
review; verified live, `claude --continue` reattached and delivered it.

*Two processes on one session.* `claude --continue` while the first process
still runs gives two Claude Code processes the same session id, and both
reattach the same launches. One of them watches each launch: `watcher.json` in
the launch directory is a lease (`{ owner, at, touchedAt }`, the owner a random
id per mod instance) renewed every 5 s. The process the person works in wins
it: restoring a launch, a prompt typed in that process (origin `composer`), a
slash command, Claude's `plannotator` tool and ExitPlanMode all touch that
process's launches and take the lease at once; a live holder keeps it against
an older or equal touch, and anyone takes it once it is 20 s old
(`LEASE_STALE_MS`: the holder exited, slept or hung). A disposed instance
(`session.end`) releases it at once. Only the watcher runs the bridge (so the
two never supersede each other) and delivers, re-reading the lease right
before it settles, so a decision follows the person within a tick. Plan
approvals live in `$.store` and every ExitPlanMode re-reads them, so an
approval received (or already used) by the other process is honored once;
ExitPlanMode and the tool also adopt this session's launches the other process
started, so a revision goes into the open review instead of opening a new one.
Delivery is claimed once per launch, whichever file settles it (`result.json`,
`exit` with an older CLI's stdout, or a dead `pid`): `claimArgv` makes the
launch's `settled/` directory (mkdir has exactly one winner) and writes the
claimant's id to `settled/by`, so a claimant whose process call timed out wins
again on the next tick, while every other process loses. A process that loses,
or finds a `settled/` claim naming someone else or the launch's `stdin` gone
(cleaned up after the other delivered), forgets the launch quietly, so its
status line no longer says "waiting for you". A per-launch in-flight flag keeps
the 1 s timer, which never waits for a slow check, from checking one launch
twice at once. Residual window: `$.prompt.submit` resolves only once Claude
is idle, so a claimed decision can wait for the whole of Claude's current turn,
and a process that quits or dies in that time takes the delivery with it
(nobody else delivers a claimed launch: the claimant may still be waiting to
deliver it, so a second delivery could never be ruled out). It is not lost
silently: the claimant keeps the launch's record in the store and renews its
lease while it waits, writes `settled/delivered` once `$.prompt.submit`
returns, and releases the lease at `session.end`. A restore of the session
(and any process that watched the launch and saw the claim) checks a claimed,
undelivered launch whose decision is still on disk: while its claimant's lease
is fresh it waits; once the lease is released or 60 s stale
(`UNDELIVERED_AFTER_MS`) it logs once, with a toast, "A decision for <subject>
arrived but wasn't delivered — it's saved in <dir>/result.json" (`stdout` for an
older CLI) and writes `settled/reported`, so it is said once.
`cleanupArgv` removes `stdin` first and keeps `settled/` while `feedback.md`
keeps the directory, so a claim made after cleanup started loses.
`persist` keeps this session's records it does not know (the other process
launched them) unless it settled them. After restore, off the session-start
path (5 s cap), the stored launch records older than a minute are pruned
(`pruneArgv`): any cleaned up (no `stdin`) or settled for good (`settled/`
marked delivered or reported, or with no decision on disk; a claimed,
undelivered decision stays for its session to report); for other
sessions, any whose server died without a decision (`kill -0` fails, no
`result.json`, no `exit`); and for other sessions older than 14 days
(`LAUNCH_EXPIRED_MS`, a session nobody resumed), any whose server is gone, decision
or not. A live server always keeps its record; this session's dead servers are
left to the timer, which reports them. The store is read again before the
write, so a record another process added meanwhile is kept.
The debug log (`PLANNOTATOR_MOD_DEBUG=1`) is appended (`debugAppendArgv`,
O_APPEND) with a per-process tag on every line, because rewriting the whole
file from each process's own buffer clobbered the other's lines and left NUL
bytes. Past 1 MiB it is rotated to `debug.log.1` under a lock
(`debug.log.rotating`, mkdir; one older than a minute is a dead writer's) with
the size checked again inside it, so two writers never rotate twice and move a
fresh log over the old one.

**Host result file (`PLANNOTATOR_HOST_RESULT_FILE`).** New CLI side channel
(`apps/hook/server/host-result.ts`), taken from the env at startup and scrubbed
like the bridge token: when a review, annotate, annotate-last or
`claude-mod-plan` session settles, the CLI writes ONE JSON record there
atomically (temp + rename): `{ v: 1, surface, decision, message, noop,
annotationCount?, platform?, withNotes?, approvedPlan?, permissionMode?,
documents?, target? }` (`documents`: a review of several files names each file with its
comment count, in review order).

**Decision targets.** Every decision a host delivers names its FULL target, as
the server that took the decision resolved it, never the words the agent typed
(a real report: a bare approval headed only `QUESTIONS.md` was acted on as an
earlier decision about a different `QUESTIONS.md`). The CLI writes `target`
(absolute file or folder path, URL, a bundle's files in order, the reviewed
directory, patch file or PR URL, the plan file; none for annotate-last) into
the host result record, the ready line (`ServerReadyMetadata.target`, set once
per process by `setServerReadyTarget`), the `--json` annotate record and the
`opencode-review` record (additive), and the `sessions/` registry
(`apps/hook/server/decision-target.ts`). Hosts put it on the line after the
heading (`plannotatorDecisionHeading(subject, id, outcome, target)` →
`Target: <path>` / `Targets:` + `- <path>` lines; `plannotatorTargetLines`), and
the tool's opened text carries the same line. The mod stores the target on its
`LaunchRecord` (from the ready line, else its own resolution of the words
against the session directory, for a CLI older than the field), names the
record's target when there is one, and logs a line when the two differ. Pi sets
it from its in-process resolution; the OpenCode bridge reads the ready line and
the JSON records, and uses the CLI's resolved path in its `File:` line too.
Same-named open reviews are told apart in headings, status and toasts by
`plannotatorDistinctSubjects` (shortest distinct path tail:
`releases-2026-10-04/QUESTIONS.md`). Plain CLI stdout ("The user approved.")
and the strict-gate record are unchanged. A code review's target is taken at DECISION time,
not at launch: both review servers put `target` on the decision (the active PR's URL after an
in-place `/api/pr-switch`, the workspace root, or the working tree the active diff reads), and the
CLI record, the `opencode-review` record and Pi use it (a static patch keeps the patch file the CLI
named); a decision about a different PR than the launch opened is headed with that PR
(`plannotatorDecisionSubject`). The mod's own fallback for an older CLI never guesses: only a URL or
PR URL, an absolute path, or a review with no words (the session directory) counts; a bare or
relative name, or review prose, gets no Target line rather than a confidently wrong one.
`message` is composed from the configured prompts exactly as other hosts do
(review: the CLI's own output; annotate: the file/message feedback and
approved-with-notes prompts OpenCode and Pi use; plan: `composePlanDeniedMessage`
/ the approved prompts), so the mod never re-implements prompts. Stdout is
unchanged for every caller. `noop` marks what never starts a turn: Done with
nothing to send, review LGTM, Close, a truly empty review submit (no feedback
text and no annotations), and a review posted straight to the PR platform
(`platform: true`, logged plus a `$.prompt.suggest` to address the comments).
A gated launch (`deliverApproval`: the tool's or a taken-over command's
`gate: true`, annotate or review) still delivers a `noop` approval; a review
LGTM record's `message` is the configured approved prompt for that (a CLI
before #1907 wrote `""`, and the turn is then the heading alone). `plannotator
review --gate` is accepted by the shared `parseReviewArgs` (`gate: true`) and
changes nothing in the CLI, whose approval is printed anyway.
**The platform post is marked explicitly, never inferred from zero
annotations:** the review editor puts only code comments in `annotations`, while
PR description comments, PR comment notes and VS Code editor comments ride only
in the feedback markdown, so a review made only of those has an empty
`annotations` and is ordinary feedback (delivered, `noop: false`,
`annotationCount: 0`, and given the request-changes suffix). The platform path's
status post sends `platform: true` in its `/api/feedback` body; both review
servers carry it onto the decision only when it is boolean `true`, and every
consumer decides on that flag: `reviewHostResult` (noop + `platform`),
`buildReviewOutput` (CLI stdout and `--json`, which Amp reads; the status line
gets no suffix), OpenCode's embedded `/plannotator-review`, the OpenCode CLI
bridge (`opencode-review` always emits `platform` as a boolean; a missing field
means an older CLI and falls back to the old `isPRMode` rule), Pi
(`classifyReviewOutcome`, `apps/pi-extension/review-outcome.ts`; the event API's
`code-review` result carries the same field). Client and server ship together
in each binary and package, so the flag is always present where it is needed.
The mod's `legacyResult` (an older CLI's stdout) never inferred the platform
post; there a status line arrives as a feedback turn, as before. The feedback
archive does not classify the platform post either: its decision comes from
`approved` and whether the body has content. Introduced in 0.28.0, where zero
annotations read as the platform post and the mod sent nothing (fixed 0.28.4;
the mod also guards records from those CLIs, see "Version skew").
An annotate Done with nothing to send still posts the legacy
zero-state sentence ("User reviewed the document and has no feedback.") as
`feedback`, because plain stdout, `--json` and the OpenCode/Pi consumers print
or deliver those bytes; the editor additionally marks that body
`nothingToSend: true`, which both annotate servers carry onto the decision only
alongside empty `annotations`/`codeAnnotations` (`isNothingToSendFeedbackBody`,
`packages/shared/annotate-decision.ts`), and `annotateHostResult` turns it into
a `noop` record. Every plugin host that turns a decision into an agent message
skips it the same way: Pi's
`classifyAnnotateOutcome` reads it as "Annotation closed (no feedback).", the
OpenCode embedded handlers (`commands.ts`) send no prompt (on OpenCode 1 the
command's own message still runs its one empty turn, the known OC1 limit; no
second turn is added), and the OpenCode CLI bridge (OpenCode 1 CLI runtime and
OpenCode 2 native commands) reads the additive `nothingToSend: true` the CLI
adds to its `--json` / `opencode-annotate-last` record in that case only, as do
the Amp plugin (`formatAnnotationFeedback`) and the Droid plugin
(`emitAnnotateDecision`), which also read `annotate --json`. Skill-run hosts
(the classic Claude Code skill, Codex, Gemini, Copilot, Vibe, Kiro) still hand
the model the plain-stdout sentence, which is the unchanged stdout contract. The
feedback archive still records a bare Done as `feedback` with the sentence.
Multi-message annotate-last merges SSE external (agent / WebMCP) comments into
the current message's entry (`mergeExternalsIntoMessageEntries`), so they reach
the exported feedback, the submit body and the nothing-to-send check. The mod's `legacyResult` recognizes the two zero-state
sentences printed by a CLI older than the result file (#1701). The submit
body's `annotations` carries every document's comments (folder sessions,
linked documents, every message in multi-message annotate-last;
`collectSubmittedAnnotations` in `packages/editor/feedbackDocuments.ts`), so
`annotationCount` matches the feedback text.

**Version skew.** The plugin installs from the repo's main branch and the
binary updates separately, so with the mod on by default it routinely runs
against an older CLI. Verified by running the real mod controller against the
released 0.27.25 and 0.27.10 binaries as processes:
- ExitPlanMode: an old CLI has no `claude-mod-plan` (0.27.11+ prints `Unknown
  command: claude-mod-plan`; older CLIs read the unknown subcommand as the
  classic hook and print `No plan content in hook event`), exit 1 within
  ~0.3 s. The mod recognizes either (`cliLacksModPlan` in `plan.ts`), lets the
  call through to Claude Code's own flow, where the plugin's classic
  PermissionRequest hook runs the familiar blocking review, logs ONE line
  telling the user to update the CLI, removes the launch directory, and sends
  every later ExitPlanMode straight to the classic flow without probing again.
  The flag lives on the mod instance, not in `$.store`, so a restart or
  `--resume` probes once more (and picks up a CLI updated in between). An old
  CLI that refuses only after the hook stopped waiting (15 s) is caught by the
  timer: same fallback, plus a plugin turn asking Claude to call ExitPlanMode
  again, since it was told a review was open. While the hook waits, the timer
  leaves the launch alone (`starting`), so only one of the two reports it. Any
  other startup failure also falls back, with the CLI's error logged. Plan
  review is therefore blocking, not broken.
- Review, annotate, last, the `plannotator` tool and taken-over Bash runs (the
  same launch as the tool): work. The old CLI writes
  the ready file (0.19.24+) and no result record; a decision that exits 0 is
  delivered from its stdout (`legacyResult` in `delivery.ts`), with the default
  review approval prompt read as an LGTM (logged, no turn) and the
  approved-with-notes prompt as "Approved with notes" (a user-customized
  approved prompt cannot be told apart and arrives as feedback). Close and an
  empty Done log only.
- Review platform flag (0.28.0 to 0.28.3 CLIs): those CLIs wrote `platform:
  true, noop: true` for ANY request-changes review with zero code annotations,
  so feedback made only of PR description, PR comment or editor comments would
  be logged and never delivered. The mod carries a narrow old-CLI guard
  (`misreadAsPlatformPost` in `delivery.ts`): a review record is treated as the
  real platform post only when its message is one of the editor's status lines
  (`isPlatformStatusLine`: `Pull request|Merge request approved|reviewed on …`
  or `Changes requested on …`, the shapes `statusMessage` in
  `packages/review-editor/App.tsx` builds); any other non-empty `platform`
  record is delivered as review feedback (without the request-changes suffix,
  which those CLIs never added to it). A fixed CLI sets `platform` only on the
  real status post, which always matches, so it never takes this path. If the
  editor's status-line wording changes, update the pattern and its test.
- `last`: the old CLI ignores `PLANNOTATOR_HOST_MESSAGES_FILE` and opens the
  newest message from stdin (no picker), though the command line still says
  "N messages, newest first".
- Ask this session: the old server answers `404` on `/api/ai/bridge/poll`, the
  mod's bridge stops, and Ask AI offers only its providers.
- A CLI before 0.19.24 writes no ready file: commands wait their full 45 s /
  15 s and say "Starting…", and decisions still arrive at exit.
- The tool's `list` and `close` (contract v2): a CLI without
  `/api/host/status` lists its reviews with `unsent: unknown`. `close` counts as
  closed ONLY a JSON answer with a numeric `unsentAnnotations`
  (`classifyHostCloseAnswer` in `controller.ts`): 0.24–0.28.3 answer a JSON
  `404` and 0.19.24–0.23.x (before the `/api/*` 404 guard, #748) their app page
  with `200 text/html`, and both read as "an older Plannotator", never as
  closed. A CURRENT CLI with host control turned off (remote mode) answers
  `404 { code: "host_control_disabled" }` instead, which the mod never TERMs:
  the close reports that the review runs in remote mode and should be closed
  from the tab. Only for an older CLI does the mod TERM the process
  (`STOP_SCRIPT`), and only if the launch's `result.json` / `exit` is still
  absent and the pid still names a `plannotator` process (`ps -o args=`);
  nothing answering on the port (a stale or reused pid after a reboot) is never
  signalled, and where `ps` cannot verify a pid (missing, as on Debian slim
  without procps, or without `-p`, as BusyBox's) the script signals nothing
  and the close says the review was left running. In every such case the close
  reports failure. After a TERM close, a decision record without `closedBy` (or an
  older CLI's exit 0) is the reviewer's and is delivered as usual. **Remaining
  window:** these CLIs publish a decision only after a 1.5 s post-decision
  sleep and nothing on their HTTP surface says a decision is pending, so a
  decision the reviewer makes in the ~1.5 s before the TERM is lost (and those
  CLIs had already deleted the draft on submit; the feedback archive record
  survives where it is on). A CLI with the endpoint has no such window: its
  close is refused with `409` once the reviewer decided.

**Commands.** `/plannotator-review`, `/plannotator-annotate` and
`/plannotator-last` keep their names (spec open question 7, conservative): when
the user's core skills hold the names (Claude Code refuses
`$.command.register` for a user skill's name), the mod's `command.run` hook
answers the skill's command itself, so the skill's blocking bang line never
runs; a name nobody holds is registered (`immediate: true`). Arguments are split
like the skill's shell line (`splitShellWords`: quotes and backslashes, no
expansion) and passed to the same CLI parsers (`review`, `annotate`; `last`
runs `annotate-last --stdin`, see the next paragraph). The command returns
"Opened <subject> in Plannotator · <url>" once the ready file appears (up to
45 s for review, 15 s otherwise), or the CLI's own startup error. Under the mod
the CLI's tolerant annotate handoff (several unresolvable words) is shown to
the user as that error, not handed to Claude.

**`last` and its message picker.** The classic path reads up to 25 recent
assistant messages from the transcript file and shows a picker (newest open by
default). The mod has no transcript file to hand over, so it builds the same
list from `$.session.messages()` (`recentAssistantTexts` in `launch.ts`: newest
first, at most 25, text-less rows skipped, consecutive assistant rows joined as
one response, the way the transcript path groups chunks by message id) and,
when there is more than one, writes `messages.json` `{ v: 1, messages:
[{ messageId, text }] }` and sets `PLANNOTATOR_HOST_MESSAGES_FILE` to it. stdin
still carries the newest text. `$.session.messages()` rows carry no id or
timestamp, so ids are derived from the text (`cc-` + 16 hex of its SHA-256, a
`-n` suffix for repeats), stable as newer messages arrive; there is no
timestamp. The CLI (`apps/hook/server/host-messages.ts`) honors the variable
only with `--stdin`, only for a `messages.json` under the data dir's
`claude-code-mod/`, takes it at startup and scrubs it from the env, and
validates fail-closed (v 1, 1..25 entries, string fields, unique ids, 2 MiB per
message, 8 MiB file); a malformed file is a startup error (exit 1). The mod
(`pickerFile`) budgets the SERIALIZED file, 256 KiB under that cap, because
JSON escaping inflates text (ESC becomes `\u001b`): older messages that do not
fit are left out, and when the newest alone does not fit no file is written
(stdin only). Why a
variable and not a flag: a CLI that predates it ignores the variable and opens
the stdin text exactly as before, while an unknown flag to `annotate-last` is
silently ignored (it would fall through to the transcript lookup) and a changed
`--stdin` payload would be shown as the message. Old mod + new CLI: no
variable, `--stdin` unchanged. With a picker the subject is "Claude's recent
messages" (status line, open text, the plugin turn's first line), since the
feedback may be about an older message; the feedback itself carries an excerpt
of each message it covers. What `$.session.messages()` returns is the engine's
live conversation: after `/rewind` that is the rewound conversation (inferred
from the API docs, not checked live), and after `/compact` only the
post-compaction messages, so the picker can be shorter there than on the
classic path, which falls back to the pre-compaction file.

**The `plannotator` tool (agent-initiated opens).** When the user tells Claude
"open this in plannotator", Claude used to run the CLI through Bash, which
blocks and gives Ask AI a separate AI. The mod registers a real tool instead:
`$.tool.register({ name: "plannotator", description, inputSchema })` at
`session.start`, right after the commands, and only when the mod is on (the
knob not turned off, an interactive session, `/bin/sh` present) and the agent tool
switch is on (on by default here; `PLANNOTATOR_AGENT_TOOL=0` / `{ "agentTool": false }` turn it off; `resolveAgentToolEnabled`
in `hooks/mod/enabled.ts`, read with the mod switch at the first `session.start`
of the process, never re-read); with either switch off, in `-p`/SDK runs and on
Windows nothing is registered and Claude keeps the CLI through the `plannotator`
skill. With only the agent tool off, the rest of the mod runs: the slash
commands, non-blocking ExitPlanMode, Ask this session, and the Bash take-over
below, which stays because it adds nothing to Claude's context (it changes only
what a `plannotator` command Claude already chose to run does). The engine names it `mcp__plannotator__plannotator`
(the register call returns the full name, which `register.ts` keeps) and serves
it through a loopback MCP server; the mod's `tool.call` hook answers every call
itself (`{ result }` / `{ deny }`), so no other hook or permission prompt runs
for it. Input: `{ action: "annotate" | "review" | "last", target?, gate?
(annotate and review), options?: { base? (review --base), markdown? (annotate
--markdown) } }`, validated strictly (unknown keys, a target or base that would
read as a flag, control characters, a field the action does not take; a `false`
default is tolerated). The call becomes the words the slash command would carry
(`plannotatorToolArgs`, one argument per element, never re-split) and goes
through the SAME launch as the commands (`PlannotatorMod.open`: detached CLI,
result file, bridge token, session tag, cleanup), so Ask this session works and
the decision arrives later as a plugin turn. The tool result returns at once
("Opened <subject> in Plannotator: <url> … End your turn now and wait"); a bad
call or a CLI startup error is an error result. A gated tool session
(`gate: true`) is the one delivery difference: a bare Approve is submitted as a
turn (`deliverApproval` on the launch record), because Claude was told to wait
for the sign-off; the slash command's bare gated approval still only logs. This
holds for code review too (#1907, gate only, the owner's call: an ungated
review's LGTM still only logs): `{ action: "review", gate: true }` delivers a
bare Approve as `Plannotator: <subject> (pn-…) — Approved.` plus the configured
approved prompt (the host record of a review LGTM is still `noop` but now
carries that prompt as its `message`, as an annotate approval does), and a
gated review posted straight to the PR platform is a turn too,
`Plannotator: <subject> (pn-…) — Review posted.` plus the status line (an
ungated one still only logs and suggests the follow-up). A review's
gate is the HOST's alone: `plannotatorToolArgs` never passes it to the CLI (the
review page always has Approve, and a CLI older than `review --gate` would
refuse the flag), so it works against any CLI. Done
and Close send nothing, as for the commands. A subagent may call the tool (its
decision lands in the main session as a plugin turn), except `action: "last"`,
which is refused there because it reads the main session's transcript. The contract (name, schema,
description, validation, argument mapping, result text) lives once in
`packages/shared/plannotator-tool.ts` for every host; the mod keeps a byte-for-byte
copy of its CONTRACT section in `hooks/mod/tool.ts` and `tool.test.ts` fails
when they differ (edit the shared file, then paste). The core `plannotator`
skill carries one host-neutral line: use a `plannotator` tool when the agent has
one. Plan review stays on ExitPlanMode. Checked live on 2.1.288: the tool is DEFERRED behind tool
search (no `alwaysLoad` is possible through `$.tool.register`), so Claude sees
only its name until it searches; with the updated skill it searched and called
the tool for "open notes.md in plannotator", while a profile still holding the
older installed skill text loaded that skill and ran the CLI instead.

**Contract v2: session ids, `list` and `close` (agent sessions, 0.29).** Every
review the mod opens has a session id, `pn-` + the six hex digits that end its
launch id (`sessionIdOf` in `controller.ts`; unique among the session's open
launches). The tool result's first line is `Session: pn-3f2a9c`, and every
decision turn's first line names it (`plannotatorDecisionHeading`:
`Plannotator: notes.md (pn-3f2a9c) — Feedback · 3 comments.`); slash-command
output is unchanged. `action: "list"` reports the reviews opened in THIS Claude
session, by the tool or by the user's `/plannotator-*` commands (the launch
store is already per session id; the global `sessions/` registry is never
read): id, kind, subject, url, age, state and `unsent: N` from the server's
`GET /api/host/status` (`unknown` for an older CLI). `unsent` counts only the
reviewer's own draft comments (`countUnsentDraftComments`: entries without a
`source`, so review-agent, WebMCP and linter findings are not counted, plus
code review's PR description and PR comment notes).
`action: "close"` takes `session: "pn-…"` or `"all"` and calls
`POST /api/host/close` (see "Host session control" under Server API): the
reviewer's Close, marked `closedBy: "agent"`, with the draft KEPT and the open
tab told over the external-annotation SSE (`session-closed`, which the editor
and review app show as "Closed by the Agent" with the unsent count). The result
reports how many unsent comments stay saved as a draft. The copy promises no
restore beyond each surface's own draft key (`agentClosedSubtitle`: annotate
drafts come back for the same unchanged document, code review drafts for the
same changes; path-keyed annotate drafts are #1710). Nothing is delivered for
that review afterwards (the launch is marked `closedByAgent` and settles with
one log line), except a decision record WITHOUT `closedBy`, which is the
reviewer's and is delivered. Plan reviews are listed but never closed (`close
all` skips them, a plan id is refused). An id this session did not open is "not
found". Against an older CLI the mod falls back to `TERM` under the checks
described in "Version skew" above (`stopArgv`), which ends the server without a
decision and never deletes a draft. The contract also
accepts `target` as a list for annotate (validated, duplicates dropped, a
one-item list is the plain call): a review of several files (a bundle, see
"Several files in one review" under the Annotate Flow). `plannotatorToolArgs`
passes the paths as the CLI's arguments, one each, in order (a bare list entry
such as `README` is passed as `./README`, so a missing one fails the whole list
instead of being read as prose), and the session is
named `plannotatorBundleSubject` ("3 files: spec.md, mock.html, notes.md"), in
the opened text, the session list and the decision heading. The tool
description says "Pass a list as `target` to review several files together, in
the order you want them read." Version skew: a CLI that predates bundles answers
several paths with its ambiguity error WITHOUT the bundle hint line
(`isOlderCliBundleRefusal`, which compares against `PLANNOTATOR_BUNDLE_HINT_LINE`,
a copy of `ANNOTATE_BUNDLE_HINT` pinned equal by `annotate-target.test.ts`); the
mod then answers `PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT` ("update Plannotator
to open several files at once") for the tool, and for `/plannotator-annotate`
when every word reads as a file path (`isSeveralFilePaths`). There is no
`reply` action: it was reserved for live comments and always errored, so it
was taken out of the schema; it comes back with the comment loop. (The design
record is not in this repo; what matters is written here.)

**Agent-run CLI commands are taken over (Bash).** Because the tool is deferred
and the skill also documents the CLI, Claude sometimes runs
`plannotator annotate x.html --gate --json` in Bash anyway; that blocked the
session and started a server with no bridge token, so Ask AI offered separate
SDK agents instead of "Ask this session". With the mod on, the `tool.call` hook
on the MAIN LOOP's `Bash` parses the command with the host-neutral
`plannotatorCommandToToolInput` (CONTRACT section of
`packages/shared/plannotator-tool.ts`, so it is in the mod's copy too) and, when
it returns a tool input, answers the call itself through the SAME `runTool` →
`open` launch the tool uses (`hooks/mod/take-over.ts`): the command never runs,
the Bash result is the Bash tool's own record `{ stdout: <the tool's opened
text>, stderr: "", interrupted: false }` (a startup error is a `deny`), and a
gated take-over delivers its bare approval as a turn exactly like a gated tool
call. A subagent's Bash command always runs as written: a subagent may work in
its own cwd or worktree, while the mod launches in the session's cwd, so its
`review` or `annotate notes.md` would open the wrong diff or file. Taken over: ONE simple command (no
`; & | < > ( )`, line break, `$`, backtick, unquoted glob/brace, comment, `~user`, unterminated
quote; quoting follows `splitShellWords`, nothing is expanded) whose program is
exactly `plannotator` (the binary on PATH; a path such as `./plannotator` or
`/tmp/dev/plannotator` is a dev build and runs for real), subcommand
`annotate` (one target, or several that all read as file paths, `looksLikeFilePath`: a separator, a leading `~` `.` `@`, or a file extension; they become `target: [...]`, a review of several files; plus `--gate`, `--markdown`), `review` (at most one target, `--base <ref>`, `--gate`),
or `annotate-last` / `last` (no arguments); `--json` is accepted and dropped
(the decision arrives as a message), and the result must pass
`parsePlannotatorToolInput`. Everything else runs as written: other
subcommands, every other flag (`--require-approval`, `--result-file`, `--hook`,
`--tailscale`, `--static`, `--app`, `--no-jina`, `--render-html`,
`--diff-type`, `--local`, `--patch-file`, `--stdin`, `--help`, ...), repeated
flags, several targets that are not all file paths (prose, which the CLI's
tolerant resolution reads) or several review targets, environment prefixes, and any compound command
(`cd x && plannotator ...`, pipes, redirects, substitutions), so scripted
strict gates keep the real CLI and its exit codes. With the mod off, in `-p`/SDK
runs and on Windows nothing is taken over. The CLI the mod launches runs in the
session's cwd (`$.process.run`'s default), the same as for the tool. Pi and
OpenCode do not take over shell runs: there an agent-run `plannotator` command
still runs the CLI (Pi registers the tool itself; see "Pi: the `plannotator`
tool").

**Plan review.** The `tool.call` hook on the main loop's ExitPlanMode resolves
the plan (the plan file when it is an absolute `.md` regular file within the
2 MB cap, else the inline `plan`: the #1667 rule), then:
1. no review open: starts `plannotator claude-mod-plan` (internal subcommand,
   `apps/hook/server/claude-mod-plan.ts`; stdin `{ plan, planFilePath,
   revisionFile }`; the plan server with `planRevisions: true`) and answers
   `{ deny }` with the waiting text (`waitingDenyText`). ExitPlanMode never runs,
   so plan mode stays on.
2. a review open: writes `revision.json` `{ seq, plan }`; the subcommand polls it
   every 500 ms, pushes it with `updatePlan` and acks; the deny text says
   "Plan vN replaced vN-1" (or, when a decision is already being recorded,
   to wait for it). Spec open question 2 resolved like Pi: revisions go into the
   same tab.
3. the plan's SHA-256 (trailing whitespace ignored) equals an approval's: the
   call passes (`next(e)`), and `classic.PermissionRequest` answers `allow`
   with `updatedInput.plan` = the approved text (#1670's "execute what was
   approved") and `setMode` to the reviewer's permission mode. Modules sit above
   the settings hooks in that chain, so the plugin's own PermissionRequest
   command hook never runs: no second review. A different plan opens a new
   review instead. **When a plugin seated above sends
   `classic.PermissionRequest` past the mod** (Claude Code's built-in guard
   `cc-plugin-sec-default` does on Team/Enterprise accounts, #2007; the
   transcript says "its classic.PermissionRequest hook was skipped"), the
   plugin's command hook IS reached. So while the approved call is in flight
   the mod also writes the approval (`{ v: 1, hash, plan, permissionMode?, at }`)
   to `<data dir>/claude-code-mod/<session>/plan-approvals/<tool use id>.json`
   (owner-only folder; plan.ts `PLAN_APPROVALS_DIR`, launch.ts
   `planApprovalPathOf`) and removes it when the call settles. The classic hook
   (`apps/hook/server/mod-plan-approval.ts`, `takeModPlanApproval`, before
   anything else in the Claude Code plan path) takes a record for this
   `session_id` whose hash matches the requested plan (the #1667 file rule,
   or the inline plan), at most 10 minutes old, never for a subagent, deletes
   it (answers once) and prints the same allow (`updatedInput.plan`, `setMode`)
   without starting a server. Without the guard the record is written and
   removed and nothing else changes. A CLI older than this ignores the record
   (the double approval remains until the binary is updated).
   `mod-plan-approval.test.ts` keeps the mod's copy of the names equal and
   runs the hook as a process.
Decisions: deny and answers-only submit the denied / answered prompt; approval
submits the approved (or approved-with-notes) prompt plus
`PLAN_APPROVAL_NEXT_STEP` ("Call ExitPlanMode once more …"), the two-hop
approval of spec open question 1 (the one-hop `$.tool.call` path is untested).
The claim the subcommand records (`currentPlan` after each accepted revision) is
what `approvedPlan` carries. If the plan server cannot start, the call falls
back to Claude Code's own flow (and the classic hook). A subagent's
ExitPlanMode keeps the classic flow. Not built: the edit guard (spec: deny
Edit/Write while a plan is in review after the user leaves plan mode), the
`AbovePrompt` band with Send now / Hold, the `/plannotator` sessions pane, the
`UserMessage` / `ToolUse` render hooks, and `tab-closed` detection; a decision
is always sent (`$.prompt.submit` waits for idle; draft text in the composer
is left alone).

**Delivery.** Each decision is one plugin turn, in arrival order, prefixed
`Plannotator: <subject> — <outcome>.`; a message over 12 KB is written in full
to the launch's `feedback.md` and Claude is told to Read it (the feedback
archive may be off, so the mod writes its own copy). Status line
(`$.ui.status`): `<subject> · waiting for you` / `N open · …`; toasts for a plan
waiting or replaced and for feedback received; `$.ui.log` for no-op decisions,
stopped servers and reattachment.

**Session tag.** `session.start` sets `PLANNOTATOR_SESSION_TAG=claude-code:<session id>`
with `$.env.set`, so every process the session starts (Bash calls, hooks, the
detached servers) inherits it; `registerCliSession` records it as
`hostSession` in the `sessions/` registry, and `plannotator inbox mcp` sends
as this session (the `plannotator_inbox` tool's author, so the reply wakes it).
The tag follows `/clear` and an in-process resume: `currentMod` sets it again
for the new id, at the latest on the next `turn.start`.

**Ask this session.** Every launched server gets a 32-byte hex token
(`PLANNOTATOR_SESSION_BRIDGE_TOKEN`, `_HOST=claude-code`, `_MODES=turn`). Once
the ready file names the port, the timer starts `createBridge` (`bridge.ts`, the
pull-bridge client over `$.http.fetch` to `http://127.0.0.1:<port>`, no Origin):
an `ask` is submitted as a real turn (`$.prompt.submit`), identified at
`turn.start` by its header and last line (Claude Code frames a plugin prompt as
"The plannotator plugin sent a message: …", seen live), streamed back from
`turn.step` text/tool chunks, and finished from `turn.complete`'s `answer`.
`busy` = a MAIN-LOOP turn is running (pushed on `turn.start` / `turn.complete`, not only
at the next poll; a subagent's `turn.start`, which every hook hears, is ignored by `onTurnStart`: its end is never counted, so counting it left the session busy for good after a background subagent started, and the Inbox wake never delivered); `interrupt` aborts the running turn (`$.turn.abort`);
cancel aborts our own turn, or, while it is still queued, confirms at once and
aborts its turn the moment it starts. Claude Code never raises a plugin's own hooks
for a prompt its code submitted (the debug log says "skipped: re-entry"), so the
mod's `prompt.submit` hook sees every OTHER prompt (the user's Enter, a
notification, another plugin); a turn whose text is exactly one of those is
never claimed, so a prompt the user typed can neither be streamed to
Plannotator nor aborted by a cancel, whatever it says. Another plugin's prompt
reaches `turn.start` inside the engine's "The <name> plugin sent a message:"
frame while `prompt.submit` saw it bare, so the match also strips that frame.
**Take-over** (`turns.ts`): a prompt typed or delivered while a turn runs fires
`prompt.submit` at Enter with that turn's `turnId`, and the engine folds it
into the turn's next model request. When that turn is our question's and the
origin is on an ALLOWLIST of messages the model must now answer (`composer`,
`bridge`, `slack-ping`, `channel`; never `peer` (owner's call: a peer
session's reply streaming into the panel is better than losing the reviewer's
answer), `task-notification`, `peer-send-message`, `scheduled-trigger`,
`observer*`, `coordinator`,
`projects-relay`, `auto-continuation`, `unclassified` or a kind added later),
streaming stops the moment the prompt reaches the mod's `prompt.submit` hook,
BEFORE `next(e)` runs the hooks beneath (a slow one cannot let the next step
through); the take-over is confirmed when `next(e)` resolves with the prompt,
and a prompt a hook beneath drops releases the hold. The step in flight was
requested before their prompt, so its output is held and released when the
question settles: at the turn's next `turn.step` (that request carries their
prompt) as `done` when the response before it ended the answer (`stop` chunk
`end_turn`, no tool call) and some answer text was shown, else as `taken_over`
(a thinking-only final response would otherwise settle an empty answer); or at `turn.complete` when no
step followed, as `done` with the turn's answer (their prompt then runs as a
turn of its own). The note reads "You typed into this session…" for
`composer` / `bridge` and the neutral "Another message entered this session…"
otherwise. From the take-over on, a cancel closes only the question and an
interrupt answers `ok: false`; Plannotator never aborts that turn. Plan review does not block the session
under the mod, so the status is never `blocked` and plan review gets real turns
too (verified live). Polls ask for 15 s (750 ms while our question streams, so
deltas flush), and stop for good on 401/403/404/405/503 (`404` = an older CLI
without the bridge), `closing`, or once the review settles. A loop that stops
because the server stopped answering (six failures in a row; `$.http.fetch`
gives up after 30 s, so a sleeping laptop or a paused server gets there in
about three minutes) is not the end: `run()` reports why it ended
(`BridgeEnd`), the controller clears the handle, and the timer starts a new
loop with the same token after 5 s, doubling to 60 s while the server stays
silent (`BRIDGE_RETRY_MS`), so Ask AI comes back once the server answers again.
A poll answered `superseded: true` (another client polled the server after us)
waits 10-15 s before polling again, instead of taking the server back at once
and starting a busy loop with the other client.

**The Plannotator Inbox (`plannotator_inbox` and the reply wake, `inbox.ts`).** Where `PLANNOTATOR_INBOX_TOOL` / `inboxTool` allows it at the first `session.start` (on by default here), `register.ts` reads the Inbox's tool list once (`discoverInboxTools`: `tools/list` on its `/mcp`; a stopped Inbox is described by the list it last answered with, kept in `$.store` as `inboxTools`; with neither, the list bundled with the mod, `INBOX_DEFAULT_TOOLS` in `inbox-default-tools.ts`, generated from a real Inbox by `bun run scripts/sync-mod-inbox-tools.ts` and pinned to one by `inbox-default-tools.test.ts`) and registers `plannotator_inbox` (`inboxAgentTool`), a SEPARATE tool, never actions on `plannotator`. So Claude Code has the tool before this computer ever ran the Inbox: the first call starts it. With no `inbox/inbox.json` the link stays silent: no HTTP request and no file (no lease, no claims folder) until a call starts the Inbox, and the wake polls from the next tick after. With the tool, `inbox/inbox.json` present at the first `session.start` (an Inbox has run here) and `inboxReminder` on (default), a `prompt.context` hook adds the `plannotatorInbox` block (`withInboxReminder`, the line naming the tool's registered full name) to the conversation's first message, once per conversation (see `inboxReminder` under Config-only settings). The session's `PlannotatorMod` owns an `InboxLink` (one per session id, so `/clear` and an in-process resume follow the new id: the old link is disposed at `session.end` and the next hook makes one for the new id). A call (`tool.call`, answered by the mod) re-reads the registry, checks health against its `serverSession`, starts a stopped Inbox with `plannotator inbox --background` (a one-shot that detaches the Inbox into its own session and waits for it; never a browser tab), and proxies to `/mcp` with `project_path` = `$.session.cwd()` (or the agent's optional `project_path`, resolved against it by `INBOX_PROJECT_DIR_SCRIPT` and refused before the Inbox is reached when it is not an existing folder) and `agent_session` = the host's real session id; `wait_for_reply` is held to 25 s through the tool (`$.http.fetch` gives up at 30 s). The wake: a 1 s `$.clock.every` tick long-polls `/api/inbox/bridge/poll` (20 s) with a 5 to 60 s backoff that never gives up; a reply waits in the mod (unless the person pressed Send now: see "Questions and Send"; the mod then puts it into the running turn with `$.session.append`) until the session has been idle for two ticks (a pending `$.prompt.submit` cannot be withdrawn, so a prompt the person typed, or a `/clear`, queued during a turn goes first), is checked once more with the Inbox (an agent may have read it meanwhile), claimed once across processes (`INBOX_CLAIM_SCRIPT`: mkdir of `claude-code-mod/<session>/inbox/claims/<reply id>`), submitted (`inboxWakeText`), and acknowledged (`delivered`, retried until the Inbox answers). A prompt typed into the reply's own turn takes it over as Claude Code folds it in; the mod never aborts it and never delivers the reply again. Two processes on one session: the session's inbox lease (`claude-code-mod/<session>/inbox/watcher.json`, the rules of the review watcher lease: the person's last process wins, 20 s stale) picks the one that polls and delivers, and the claim makes a lease race harmless; a claimant writes `alive` while its turn waits, and a reply whose claimant stopped for 60 s without `delivered` is reported once with a toast (the only toast the connection raises); one marked `delivered` whose acknowledgement was lost is acknowledged by the other process. Nothing touches the system prompt; the tool list is fixed per process. Version skew: an Inbox without the bridge route (404) just leaves the poll backing off; an action the running Inbox lost answers "update Plannotator"; a `plannotator` without the `inbox` subcommand answers that the binary has no Inbox.

**Tests.** Bun: `apps/hook/hooks/mod/*.test.ts` (controller flows over an
in-memory `Host`, delivery, shell words, and `bridge.test.ts` against the REAL
server half `createPullSessionBridge`), `apps/hook/server/host-result.test.ts`,
`apps/hook/server/claude-mod-plan.test.ts` (the subcommand as a process:
revision → tab → approval carries the revised text; answers-only),
`apps/hook/server/host-messages.test.ts` (`annotate-last --stdin` as a process:
the messages file yields the picker, a malformed one exits 1, plain `--stdin`
unchanged). Engine
harness: `apps/hook/tests/register.test.ts` via `scripts/test-claude-code-mod.sh`
(stages the plugin without the CLI, whose bun tests `claude plugin test` would
otherwise try to load; bun skips `apps/hook/tests/` through `pathIgnorePatterns`).
Typecheck: `apps/hook/hooks/mod/tsconfig.json` (no DOM, no Node; `globals.d.ts`
declares the few web APIs a hooks module has). `PLANNOTATOR_MOD_DEBUG=1` writes
`claude-code-mod/debug.log` in the data dir. The Inbox connection is proved against a REAL Inbox in `apps/hook/hooks/mod/inbox.test.ts`: `plannotator inbox --background` under a temp data dir (the compiled binary when `PLANNOTATOR_INBOX_TEST_BINARY` names one, as `.github/workflows/inbox-claude-code.yml` runs it; the CLI from source otherwise) and the mod's own code on a Host of real processes, HTTP and files (`testing/claude-session.ts`, which simulates the conversation the way `register.ts` feeds it): with no registry the tool comes from the bundled list, nothing polls or writes, and the first call starts the Inbox and lands its message, after which the wake polls; the tool carries what the Inbox's `/mcp` offers, `send_message` lands a thread, the window's Send arrives once as a turn with the stable header and the reply verbatim (delivered, then replied), a typed prompt goes first and takes the reply's turn over, `/clear` follows the new id, two processes deliver once, and a dead Inbox is started by the first call with no browser tab. `INBOX_PROOF_DIR=<dir>` keeps a transcript per proof. The engine harness (`apps/hook/tests/register.test.ts`) covers the wiring with the engine's own `$`.

### OpenCode 2: the `plannotator` tool

The OpenCode 2 plugin (`apps/opencode-plugin/server.ts`, `registerPlannotatorTool`)
registers the same `plannotator` tool the Claude Code mod does, through
`ctx.tool.transform` → `tools.add`, with the shared contract itself
(`PLANNOTATOR_TOOL_NAME` / `_DESCRIPTION` / `_INPUT_SCHEMA` and
`parsePlannotatorToolInput` from `packages/shared/plannotator-tool.ts`, never a
copy; `plannotator-tool.test.ts` checks the registered schema IS the shared
object). It is OFF by default on OpenCode 2; turned on (`PLANNOTATOR_AGENT_TOOL=1`
/ `{ "agentTool": true }`, `resolveAgentTool(loadConfig(), process.env,
"opencode")`, read once at plugin setup; a change applies when OpenCode
restarts) it is registered for every workflow (`manual` included), and not at
all where the decision could never come back: a tool draft without `add` (an
older V2 host, probed inside the callback like the native commands' draft) or
a session domain without `prompt`. OpenCode 1 gets no tool in 0.29 (design
decision; its `plugin.tool` route is feasible).

**Open (annotate, review, last).** Each call runs the SAME launch the native
slash commands use (`runNativeCommand` → `handleCliCommand`: a `plannotator`
CLI child, the pull-bridge token so "Ask this session" works, the ready file,
the decision delivered later to the calling session with `session.prompt`),
and the tool returns as soon as the ready file names the url (up to 45 s for
review, 15 s otherwise, then the "starting" text): `Session: pn-…` plus
`plannotatorToolOpenedText`. A refused argument or the CLI's startup error is
the result text (`Plannotator could not start: …`; results are always text,
since the promise adapter turns a rejected `execute` into a defect). The
annotate target is passed as ONE argument (`toolLaunchRequest` builds
`ParsedAnnotateArgs` instead of re-parsing a string, so `my notes.md` stays one
path); review words are quoted for `parseReviewArgs`' string form
(`quoteReviewWord`). A gated tool session delivers its bare approval
(`Plannotator: notes.md (pn-…) — Approved.`), like the mod; a slash command's
bare gated approval still sends nothing. A code review's bare Approve was
always delivered here (and on Pi), so a review's `gate` changes nothing on
OpenCode or Pi; it is accepted because the contract is shared. A list of files (two or more after the
contract drops duplicates) opens ONE bundle review through the same launch:
`handleCliCommand`'s `annotateBundle` passes each entry as its own CLI argument
in the agent's order (never re-split, and a single tool target is never read as
several words), the subject is `plannotatorBundleSubject` (`2 files: a.md,
b.html`) in the result, `list` and the decision heading, and the feedback is
framed under `Files: …` as the slash command's bundle is. An older CLI's
several-paths ambiguity error (`isOlderCliBundleRefusal`) makes the result
`PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT`. When a launch
answered "starting" and its CLI then fails before the page opens, the session
gets one message (`plannotatorLateFailureText`: `Plannotator: notes.md (pn-…) —
Did not open.` plus the CLI's error), delivered with `session.prompt`
(`queue`), so neither the agent nor the person waits for a decision that never
comes; OpenCode 2's plugin context has no toast surface, so that transcript
message is the visible signal. A command that merely ends without a ready file
sends nothing (a CLI older than 0.19.24 writes none and delivers its decision
at exit). Subagents work as on the mod: a subagent's (child) session resolves
to its root session (`resolveRootSession` walks `parentID`), which owns the
review, gets its decision and lists or closes it; only `last` is refused from a
subagent (`PLANNOTATOR_TOOL_SUBAGENT_LAST_TEXT`, the mod's wording), since it
reads the main session's messages. Ask this session for such a review asks the
root session. Not verified live: delivery to the root while it still waits on
the subagent relies on `queue` delivery. A tool launch posts its session-URL
notice into the CALLING session (a subagent's own session, never the root that
receives the decision) and only while the tool call is still open
(`createV2BridgeClient`'s `notice: { sessionID, open }`, closed the moment
`runPlannotatorTool` answers), so the notice is always promoted inside the
caller's running turn; the tool's answer already carries the URL, and a server
that comes up after a "starting" answer posts no notice (the URL is in `list`
and the log). Posting it into the root was a leak (0.28.5 smoke, live on
2.0.22): a background subagent's root, or the parent of an API-created child
session, is idle, so the pending steer sat there and was promoted ALONE as a
model turn when the root next woke (the queued decision promotes one row at a
time), and the model answered "Plannotator session ready: <url>". With the
notice always inside a running turn, tool launches always queue their decision
(`alwaysQueue`; co-promotion is also only attempted for a notice in the
decision's own session), since the slash commands' co-promoting steer (#1515)
would push a late decision into a running turn. No
shell take-over: nothing in the OpenCode 2 plugin API can answer a shell call.

**Session ids, list and close.** `OpenCodeLaunchRegistry` (one per plugin
instance) records every review a session opens: tool calls, its slash commands
(`runNativeCommand` with `launches`), and its `submit_plan` review (listed,
never closable). Every recorded launch's decision message starts with
`plannotatorDecisionHeading` (`withDecisionHeading` in `cli-bridge.ts`), slash
commands included, so `list` and the decision name the same id. Its outcome
uses the mod's words: `Feedback · N comments`, `Approved with notes · N
comments`, `Approved`, and for code review (local or PR) `Changes requested ·
N comments`. The count comes from the CLI's additive `annotationCount` on the
`annotate --json`, `opencode-annotate-last` and `opencode-review` records (an
older CLI omits it and the heading has no count). A PR-platform status post
reads `Review posted` (`PLANNOTATOR_OUTCOME_REVIEW_POSTED`, the same words as Pi) and is decided by the record's `platform` flag (#1719;
`isPlatformPost`, falling back to `isPRMode` only for a CLI without the flag),
never inferred from zero annotations, so description-only PR feedback is
`Changes requested`. `list` and
`close` see only the calling OpenCode session's launches (never the global
`sessions/` registry; another session's id is "not found"). `list` reads
`GET /api/host/status` with the launch's token for `unsent` and `decided`
(`readHostStatusAnswer`; `unknown` for an older CLI). `close` posts
`POST /api/host/close` and reads the answer with `classifyHostCloseAnswer`
(`packages/shared/host-control.ts`, the mod's rule): closed (draft kept, the
tab told, nothing delivered, since the CLI's record is then `dismissed`),
decided (the reviewer's decision is on its way), refused, turned off (left
running; the text says remote mode only when the ready file did, and otherwise
names a server started without a host token), or not answering (left
running). `close all` skips plan reviews silently; only an explicit plan id
gets the "not closable" line. A close that stopped an older CLI is logged as
the agent's close, not as a CLI failure (`isClosedByAgent`). Only a server that
answered as an older Plannotator without the endpoint (an uncoded JSON `404`
or its app page) is stopped instead: SIGTERM to the plugin's own child process
(`terminate` from `runPlannotatorCli`'s observer), which never deletes a
draft; a decision such a CLI is still publishing is lost, as on the mod.

Tests: `apps/opencode-plugin/plannotator-tool.test.ts` (registration against
older drafts and without `prompt`, refusals, and the real launch path against a
stub CLI that serves the real host-control guards: open → url and id → list →
decision heading in the right session, gated bare approval, close with the
token, turned-off close leaves the server up, older CLI stopped, startup
error, a slash command listed). Checked live on OpenCode 2.0.22 with a fake
model: the model's tool call opened annotate and review, `list` showed the
server's count, the reviewer's feedback and a gated approval arrived as new
turns headed with the id, `close all` closed a review holding 2 draft comments
with no turn delivered, and Ask AI showed "Ask this session". A list target
(`["notes.md", "mock.html"]`) opened one `annotate-bundle` session in that
order, `list` named it `2 files: notes.md, mock.html`, its feedback arrived
headed `— Feedback · 2 comments.` under `Files: notes.md, mock.html`, and
`close all` closed a second bundle.

### T3 Code: Ask this session through an optional Claude hook (opt-in, unreleased)

`packages/t3-code` (user notes in its README). T3 Code runs Claude through the
Agent SDK, which loads `~/.claude/settings.json` hooks, so a Claude Bash hook
connects ordinary `plannotator review` / `annotate` / `last` commands in a T3
conversation to that conversation: Ask this session becomes a T3 turn, and the
decision arrives as a T3 message. It uses T3's existing MCP API as a client
(no T3 change, no provider-side MCP server, no skill change). Nothing of it
runs for anyone who did not opt in.

- **Opt in / out:** `install.sh --with-t3` writes one `PreToolUse` `Bash` hook
  into `${CLAUDE_CONFIG_DIR:-~/.claude}/settings.json` (`t3-hook install`,
  `packages/t3-code/install-hook.ts`: other hooks and settings kept, a
  `.plannotator-t3.bak` backup before the first change); `--without-t3`
  removes only it. Both are remembered in `install-flags.json` (`with-t3`,
  `without-t3`; POSIX only, no PowerShell spelling) and skipped by
  `--minimal`; a failing step warns and never aborts the install. Without a
  flag the installer touches nothing T3. `plannotator t3 login --url <T3 MCP
  URL>` authorizes once (OAuth, PKCE); `plannotator t3 logout --url …` stops
  that endpoint's workers and deletes the saved grant. `t3` and `t3-hook` are
  in `HIDDEN_SUBCOMMANDS`.
- **The gate (per Bash call cost):** the hook runs on every Bash call of every
  Claude session that loads the settings file. The command is
  `case "$CLAUDE_CODE_ENTRYPOINT" in sdk*) PLANNOTATOR_DATA_DIR=… '<binary>' t3-hook;; esac`
  (`t3HookCommand`, `packages/shared/t3-hook-command.ts`): only an Agent SDK
  session (`sdk-ts`, …) starts the binary; an interactive `claude` (`cli`)
  is answered by the shell with no output (~3 ms instead of ~290 ms of CLI
  startup). The binary repeats the check as the first statement of
  `apps/hook/server/index.ts` and in `prepareT3Hook`. Inside an SDK session
  the hook routes only when a saved grant exists and T3 shows the exact
  running tool call (`toolu_…`, Bedrock/Vertex ids included) owned by one
  conversation in the same folder; otherwise, and on any error, it answers
  `{}` (the command runs as written) and logs to `t3-code/hook.log`. The
  whole lookup, connecting included, is bounded at 6.5 s, under Claude's
  10 s hook timeout.
  Limits: the gate opens for EVERY Agent SDK session, not only T3's:
  `claude -p` (`sdk-cli`), other SDK apps, and Plannotator's own Claude
  review-agent jobs (which load user settings). There an opted-in user pays
  the binary's start (~320 ms) per Bash call, and the hook then finds no T3
  owner and answers `{}`. A Claude whose cwd is below the thread's root (it
  `cd`'d into a subfolder) is not routed: the command runs as the ordinary,
  blocking CLI. Claude Code matches permission rules against the rewritten
  command (`plannotator t3-hook open …`), not what Claude typed (from the
  hooks contract; not checked live).
  The launch file under `t3-code/hooks/` is removed after one use, whether
  the open succeeds or fails.
- **Worker:** one detached `plannotator t3 serve` per thread (registry
  `t3-code/<endpoint>/threads/<thread>/daemon.json`, token-guarded loopback
  routes `/health`, `/review`, `/stop`) launches the review CLI with a pull
  bridge (`PLANNOTATOR_SESSION_BRIDGE_HOST=t3`), long-polls it, and delivers
  the host result record. It exits after 10 min with no open review, no
  pending delivery and no review request (`PLANNOTATOR_T3_WORKER_IDLE_MS`);
  the next command starts a new one (a request that meets one that just
  exited is retried once). The OAuth token is read per request and a refused
  MCP session is reopened, so a new login applies without a restart; only a
  delivery already attempted under the old grant is refused (T3's idempotency
  namespace changed). A review whose server died without a decision, a
  launch that never came up (no ready line within 60 s, or its CLI gone,
  e.g. the worker was killed while opening it), or a refused delivery stops
  being waited on, so no later worker inherits it. A settled review drops its
  bridge token from `launch.json` at once; its folder is pruned on worker
  start and idle exit after 24 h (7 days for failed or refused ones).
- **Decisions** (`packages/t3-code/decision.ts`) are worded exactly as the
  Claude Code mod words them (`decision.test.ts` compares against the mod's
  `deliveryFor`): `Changes requested · N comments`, LGTM / Done / Close only
  logged (a gated approval, annotate or review, is sent; `t3 review --gate`), over 12 KB written to the
  review's `feedback.md` and named in the message (T3 caps a message at
  120,000 characters). One deliberate difference: a review posted to the PR
  platform is sent as `Review posted` with its status line. `last` skips
  messages from runs still going (the run that called it).
- **UI:** the bridge advertises `interruptible: false` (pull poll body →
  `sessionBridge.interruptible` on `/api/ai/capabilities`; absent for every
  other host and older servers), and the Ask AI panels then offer no
  "Interrupt and ask now" and label Stop as "Stop listening".
- **Data:** `<data dir>/t3-code/` (grants, hook launches, review results,
  pending deliveries, `feedback.md`, logs; feedback and conversation text,
  nothing pruned). `isAllowedHostResultPath` accepts `result.json` under it.
  Uninstall stops running workers (dry run lists them), removes the hook for
  the installed binary and the `settings.json.plannotator-t3.bak` backup the
  hook install made; `--purge` deletes `t3-code/`.
- **Tests:** `bun test packages/t3-code` (unit); with
  `T3_TEST_EXECUTABLE=<compiled binary>` also the end-to-end proof against a
  scripted T3 MCP server (`connected-session.test.ts`, run on the compiled
  binary in `test.yml`); `scripts/install.test.ts` ("optional T3 hook"),
  `packages/server/uninstall.test.ts`, `packages/ai/session-bridge-pull.test.ts`.

### Codex Stop hook: which turn the plan belongs to

Codex has no `ExitPlanMode`, so plan review rides its experimental `Stop` hook:
the hook reads the session rollout and returns the plan **the turn that just
stopped** produced. Anchoring on a turn is what keeps an older, already-decided
`<proposed_plan>` from being reopened (#1169), and the turn is resolved in
`resolveCodexStopPlan` (`apps/hook/server/codex-session.ts`) in two tiers:

1. **The payload's own `turn_id`** when the Stop JSON carries the field.
2. **The rollout's own turn markers** when it does not: the id of the LAST
   id-carrying `turn_context` / `task_started` marker in the newest rollout
   segment. A turn still in flight owns the last markers by construction, and
   when Stop fires at turn end the last marker is that turn's own, so one rule
   covers both shapes. The scan then still anchors on that turn's **first**
   marker, so a mid-turn compaction (which re-emits `turn_context` with the same
   id) cannot hide a plan the turn produced before it.

Tier 2 exists because `StopCommandInput.turn_id` only landed in Codex
**rust-v0.117.0** (`rust-v0.116.0-alpha.12`), while the hooks engine itself
shipped in **rust-v0.114.0**: stable `rust-v0.114.0`, `v0.115.0` and `v0.116.0`
fire the Stop hook with no `turn_id` at all. Their rollouts do record the id on
every turn marker (`TurnContext::to_turn_context_item` writes
`turn_id: Some(sub_id)`), which is what the fallback reads. Using it writes one
unconditional line to **stderr** (`logCodexStopTurnIdFallback`; stdout is the
hook's JSON decision channel, and Codex only reads a Stop hook's stderr on
exit code 2, which this hook never uses).

Fail-closed cases are unchanged: a payload that carries `turn_id` as a blank
string — or as anything that is not a string — is truncated or foreign, not an
old Codex, and is refused **before the rollout is read**; a rollout with no
id-carrying turn marker at all skips too. Both skips stay silent unless
`PLANNOTATOR_DEBUG` is set.

The deny→resubmit guard follows the same two shapes. When `stop_hook_active` is
set, the plan is served only if it changed across the boundary the previous
blocking Stop left in the turn. Codex >= 0.117 records that boundary as a
`<hook_prompt>` **user** message (`build_hook_prompt_message`); `rust-v0.114.0`,
`v0.115.0` and `v0.116.0` record it as a **developer** message
(`DeveloperInstructions::new(continuation_prompt)`), so the rollout-fallback
path — and only that path, which keeps every `turn_id`-carrying Codex
byte-identical — also accepts the last developer message in the turn as the
boundary. Without it the guard is inert on exactly the versions the fallback
enables, and an unrevised denied plan is re-served on every Stop of the turn.

## Code Review Flow

```
User runs /plannotator-review command
        ↓
Claude Code: plannotator review subcommand runs
OpenCode: event handler intercepts command
        ↓
VCS provider captures local changes (Git, GitButler, JJ, or P4 where supported). When review runs from a
non-VCS parent that contains nested Git/JJ/GitButler repos, child diffs are combined with
folder-prefixed paths.
        ↓
Review server starts, opens browser with diff viewer
        ↓
User annotates code, provides feedback
        ↓
Send Feedback → feedback sent to agent session
Approve → approved prompt sent to agent session (with the note/annotations when approving with notes)
```

### Color-free VCS output (#1661)

Every git command the review servers parse goes through `prepareGitCommand`
(`packages/shared/review-core.ts`, both runtimes), which prepends
`GIT_COLOR_FREE_ARGS`: `--no-pager` plus `-c color.<key>=never` for `ui`,
`diff`, `status`, `branch`, `grep`, `showBranch` and `interactive`.
`color.ui=never` alone is not enough, because an explicit `color.diff = always`
in the user's config wins over it and colors a piped diff, which used to parse
to 0 files and 0 viewed-file identities. jj gets `JJ_COLOR_FREE_ARGS`
(`--color=never --no-pager`, `packages/shared/jj-core.ts`) in both runtimes'
`runJj`, `gh pr diff` gets `--color=never`, and agent jobs inherit the same git
settings as `GIT_CONFIG_*` variables (`gitColorFreeEnvironment`). As a backstop,
`parseDiffToFiles` strips ANSI codes from a patch whose `diff --git` headers are
colored (`stripPatchColor`, `packages/core/diff-files.ts`); a normal patch is
returned byte for byte. A new git/jj spawn that bypasses these runners must add
the same options. `packages/server/review-git-color-config.test.ts` runs both
servers against a sandboxed config that forces color on.

### Review directory targets

`plannotator review [DIRECTORY | PR_URL]` (and `/plannotator-review` on OpenCode
and Pi) accepts one local repository/worktree or multi-repo workspace directory.
The shared `parseReviewArgs` + `resolveReviewTarget` resolve it against the
invoking terminal/session cwd, validate it before discovery, and reject multiple
targets or a directory combined with `--patch-file`. Prose stays tolerated
(#1483, the annotate-target precedent): a sole word or any path-shaped word is a
directory candidate (path-shaped typos and files error), every other word is
ignored with a notice and the invoking cwd is reviewed. Hosts pass the resolved cwd
through existing VCS/workspace discovery and project detection; never use
`process.chdir()` in a plugin host. Explicit targets inside a repository normalize
to its detected VCS root. OpenCode uses the internal `opencode-review-directory`
command for these targets so an older CLI rejects them rather than silently
reviewing the caller's repo; ordinary reviews keep `opencode-review`.
Feedback still goes to the invoking agent
session, with `withReviewDirectory` naming the active directory at submission when feedback has content
(a bare approval stays bare). File operations, AI jobs and persistence continue
using the resulting `gitContext.cwd` / workspace root.

### Review header decision control (agent mode)

The agent-destination review header uses the same adaptive split control the annotate surfaces
adopted: a ghost-X Close plus `DecisionControl` (`packages/ui/components/DecisionControl.tsx`)
rendered from the pure `buildDecisionSpec` mapping — `Approve` with no annotations,
`Send Feedback` otherwise, with `Request changes…` / `Send with a note…` and the explicit
`Approve, discard n annotations…` confirm behind the caret. One `submitPrimaryDecision()`
callback serves the header primary, the global `Mod+Enter` handler, and the compact primary row.
Transport routing is pure in `packages/review-editor/reviewDecision.ts` and single-endpoint:
every decision POSTs `/api/feedback` with `approved` as the only fork; a change-request note
becomes a `scope:'general'` `CodeAnnotation` (sentinel `filePath ''`/0/0, riding the export's
`## General` section) with a one-render deferred submit — zero server change. Approve-carrying
menu items (`Approve with notes`, `Approve with a note…`) are capability-gated on the
server-sent `approvalNotesSupported` advert, which rides every diff payload (`/api/diff`,
`/api/diff/switch`, `/api/pr-diff-scope`, `/api/pr-switch`, both runtimes) and reads as false
when absent, so an old server renders no approve-carrying items. For the OpenCode CLI bridge
the advert additionally requires the plugin's own `supportsApprovalNotes: true` declaration on
the `opencode-review` stdin JSON (the binary and plugin version independently; an old plugin
omits it and the advert fails closed, so a new binary can never hand an old bridge a note it
would discard). A capable session's approvals post `buildReviewApprovalBody`: bare approve
sends `feedback: ''` (the old `'LGTM - no changes requested.'` placeholder is gone — a bare
approval now archives as `lgtm` with no sidecar), "Approve with a note…" sends the note as the
feedback, and "Approve with notes" sends the live annotations plus their export (a note, if
both are ever present, is folded in ahead of the export — never dropped). The four agent-facing
decision consumers (Claude Code CLI, OpenCode native + CLI bridge, Pi) emit approvals through
the shared `composeReviewApprovedMessage` (`packages/shared/prompts.ts`, vendored to Pi):
a bare approval is the plain approved prompt; an approval carrying feedback uses the
approved-with-notes framing (`prompts.review.approvedWithNotes`, default
`DEFAULT_REVIEW_APPROVED_WITH_NOTES_PROMPT` — "non-blocking guidance, do not revise or
reopen"), because the bare prompt plus a change-request-shaped export would read as a
contradiction. The legacy placeholder is filtered there so a stale built client cannot get
filler framed as guidance. The standalone dev server (`apps/review/server`) is the exception:
it emits the raw decision JSON with the feedback unfiltered and does not route through the
composer. Compact/touch rows are generated from the same spec, so a visible positive decision
exists in every state; composer rows open `DecisionNoteDialog`. Platform (PR) mode renders the
same ghost-X + `DecisionControl` shape from `buildDecisionSpec`'s platform arm, with **no
composer items ever**: every menu action opens the existing `ReviewSubmissionDialog` (per-target
state, retry, "leave PR open" toggle — whose general-comment textarea is the only note field on
that side), and the self-approval mute is preserved — muted primary/items with the "You can't
approve your own {PR/MR}" reason.

**Request changes is a real review event (#1611).** `PRReviewAction` (`packages/shared/pr-types.ts`)
is `'approve' | 'comment' | 'request_changes'`, carried end to end: `resolvePlatformDecisionAction`
returns `{ action, chooseEvent }`; `Post comments, then…` opens the dialog with a Comment /
Request changes choice (Comment selected) and the empty-state `Request changes…` preselects
Request changes, while the primary `Post Comments` keeps the plain comment flow with no choice.
`POST /api/pr-action` validates `action` with `parsePRReviewAction` in BOTH runtimes (anything
else is `400`, never a silent COMMENT), and `submitGhPRReview` maps it to `REQUEST_CHANGES` on the
single create-review call AND on the pending-review → `/events` submit path (#1600), with the
same `See inline comments.` placeholder COMMENT gets when the body is empty (GitHub requires a
body on both). GitLab has no request-changes review: `request_changes` posts exactly what
`comment` posts, the menu subtitles say so (`requestChangesSupported: false` on the spec's
platform input), and the dialog's Request changes option is disabled with that reason. GitHub
refuses REQUEST_CHANGES on your own PR like APPROVE, so with `requestChangesSupported: true` and
`selfAuthored` the empty-state `Request changes…` mutes with its own reason and a live
`Comment…` row (`note-with-feedback`, compact id `comment`) keeps the state from being a dead
end; `Post comments, then…` stays live with the dialog option disabled. The spec field is
optional and absent keeps the pre-#1611 copy for hosts. In a stacked multi-PR submission every
target posts the same event; the choice locks once any target may have been posted
(success/partial/blocked) so retries and the tab-scoped recovery (which stores `action`) keep
that event, while after a plain failure (nothing posted) it can still change. A refusal GitHub
answers anyway surfaces its own reason through the #1600 `githubErrorDetail` path.

**PR platforms are providers (#1583).** GitHub, GitLab and Bitbucket Cloud each implement one
`PRProvider` (`packages/shared/pr-provider.ts`: `checkAuth`, `getUser`, `fetchPR`, `fetchContext`,
`fetchFileContent`, `fetchFileBytes`, `submitReview`, plus optional `fetchViewedFiles` /
`markFilesViewed` / `fetchStack` / `fetchList`); the dispatch functions look the provider up by
`PRRef.platform`, and an absent optional method is the neutral answer (no viewed state, no stack,
empty PR list). What the UI shows comes from `getPRPlatformCapabilities` (`packages/shared/pr-types.ts`,
browser-safe): `requestChanges`, `selfReviewBlocked`, `fileLevelComments`, `viewedSync`, `artifacts`,
`reviewBodyRequired`, `agentCliAccess`, labels and the CLI. Pure helpers replace the old
`platform === "github" ? number : iid` ternaries: `getPRNumber`, `getDisplayRepo`, `getPRHeadFetchSpec`
(where a local checkout fetches the head: `refs/pull/N/head`, `refs/merge-requests/N/head`, or
Bitbucket's source branch, from the fork URL when `sourceRepo` is set) and `getPRCloneCommand`.
GitHub/GitLab outputs of all of these are pinned byte-for-byte (`pr-platforms.test.ts`, including the
draft target keys). Bitbucket specifics: REST API 2.0 over `fetch` (`packages/shared/pr-bitbucket.ts`,
vendored to Pi), credentials per the `PLANNOTATOR_BITBUCKET_*` rows above; the PR object's 12-char
hashes are resolved to full SHAs and the merge base comes from `/merge-base` (the PR diff is
three-dot); existing inline threads get a GitHub-shaped `diffHunk` cut from the PR diff (`bitbucketDiffHunk`), since Bitbucket comments carry none; a review posts each line comment as an inline comment
(`inline: { path, to | from, start_to | start_from }`), THEN the body as one general comment (the
Activity feed lists newest first, so this puts the summary above the inline comments, #1583), then
`POST /approve` or `POST /request-changes` (so `requestChangesSupported` is true, and an author may approve their own PR,
so nothing is muted); it follows GitLab's partial contract, with `retry.action` naming the failed
decision (`request_changes` included) and `retry.body` carrying the general comment when that is the
part that failed after inline comments landed (`buildPRActionRequest` resends exactly it). File-level comments fold into the body, there is no viewed sync
and no stack discovery, the PR Artifacts panel is hidden (`artifacts: false`), and agent review, Code Tour and
Guided Review prompts carry the diff inline when no local checkout is ready (`agentCliAccess: false`: no CLI a job may run can read the PR). The portable
guide format names only github/gitlab, so a Bitbucket guide omits `source.pr.platform`. Recorded
(anonymized) API responses and a fake API server live in `tests/test-fixtures/bitbucket/`;
`scripts/bitbucket-live-smoke.sh` runs the real flow against a throwaway repo.

Interaction-model changes worth knowing (F8 and siblings): the agent-mode `Approve` primary
follows the `FeedbackButton` responsive pattern and is **icon-only below the `lg` breakpoint**,
where the old `ApproveButton` showed a compact `OK` label — the `title` carries the accessible
name, and compact/touch rows keep full labels. Approving despite annotations is now two clicks
(caret → `Approve, discard n annotations…` → `Discard & approve`) instead of the old dimmed
one-click Approve with its warning dialog, and `Mod+Enter` never stacks with the removed
approve-warning dialog — an open confirm dialog owns `Mod+Enter` outright (the
`data-plannotator-confirm-dialog` sentinel guard in the app's keydown effect; without it one
keystroke over the discard confirm would post two contradictory decisions). Accepted edge: the
compact `DecisionNoteDialog` keeps its draft locally and discards it if the item behind it leaves
the live spec (the dialog closes), while the desktop popover composer keeps drafts keyed by item
id — an intentional asymmetry, not a bug.

The review sidebar carries the durable human producer for review-level comments:
**"+ General comment"** renders in the Annotations tab's General section header (even with zero
general comments) AND in the all-empty state, opening the shared `DecisionNoteField` in a small
anchored popover whose width clamps to the resizable panel (200-600px persisted) so it never
clips inside the sidebar's `overflow-x: hidden` scroll area. Composer state (open + draft) lives
in `ReviewSidebar`, shared by both placements: the draft survives a dismissal, a placement flip
(an external annotation arriving mid-sentence moves the button from the empty state to the
section header), and a tab switch; collapsing the sidebar discards it. The producer is
deliberately present in platform (PR) mode too — a session-level comment there rides the posted
review body through the pre-existing `scope:'general'` handling in `buildFileScopedBody` /
`ReviewSubmissionDialog`. Unlike the header composer's submit note (one-submit lifetime), a sidebar
general comment goes through `addCodeAnnotationsWithHistory` — undoable, draft-persisted,
deletable — and both producers share one shape factory, `createGeneralReviewComment` in
`reviewDecision.ts`: `scope:'general'`, sentinel `filePath ''`/0/0, `review-note-` UUID id, and
deliberately **no PR context**, so the comment passes every PR scope predicate and survives an
in-place PR switch. Creating one raises `totalAnnotationCount`, which is what flips the header
control to `Send Feedback` — the control is state-driven, not wired to the button. The
feedback archive records each annotation's `scope` (additive `scope?: string` in
`packages/shared/feedback-archive.ts`'s normalizer, vendored to Pi), so a review-level general
comment stays distinguishable from a line comment in `index.jsonl`.

### Since-main default review view

The default code-review diff is **`since-base`** — a composite of `merge-base(base, HEAD)` vs the working tree plus untracked files ("everything a PR would show if you committed and pushed now"). It can render as a three-section **git status** panel (Committed / Changes / Untracked) via `SectionsPanel`, with a `Tree | Git status | Commits` toggle (`PanelViewToggle`). The Commits segment (local git and jj sessions; not GitButler, P4, workspace or PR mode) is a linear `--first-parent` history rail (`CommitsPanel`): clicking a commit opens its own diff (`commit:<sha>`, vs its first parent) as the all-files view headed by the commit message rendered as markdown. In a jj session the same rail and contract run over the jj family (`listJjCommitHistory` / `getJjCommitDiffInfo` in `packages/shared/commit-history.ts`, vendored to Pi): the rail is `first_ancestors(@) ~ root()` (jj >= 0.33), dropping `@` when it is the usual blank working copy (empty, no description, exactly ONE parent: a blank merge `jj new A B` stays, since its first-parent diff is real), `isHead` marks `@` (badge `@`, not `HEAD`), `shortSha` carries the short CHANGE id while `sha` stays the full commit id, and the divider is the jj compare target (`resolveJjCommitRailBase`: the session base, except an Evolution-diff base, which is not a line base, falls back to the context's line base; labeled by its bookmark). A click opens `jj-commit:<commit id>` — a separate family because providers claim diff types by prefix and git owns `commit:` (a pure jj repo has no git work tree), always addressed as `commit_id(<id>)` so a hex-named bookmark cannot shadow it — diffed `--from <first parent> --to <id>` (never `jj diff -r`, which compares a merge against all its parents), with hunk expansion, image previews, the fingerprint and the analysis snapshot going through the same per-VCS tables as every other jj type (`resolveJjSideRevs`, `getJjSnapshotRevsets`). jj REWRITES a mutable revision on every edit (the working copy on every snapshot) while the old id keeps resolving as a hidden commit, so the jj-commit fingerprint is visibility-aware (`commit_id(X) & ::visible_heads()`: `visible` / `hidden` / `gone`) — an opened `@` goes "Diff out of date" on the next save — and both servers' `/api/diff/switch` pass jj types through `canonicalizeJjCommitDiffType` (`packages/shared/jj-core.ts`), which maps a hidden id to its change's single current version (`change_id(<change>)`; divergent or abandoned changes stay put). Refresh therefore lands on the new `@`, and the client adopts the returned commit-family `diffType` even on an in-place (`preserveFile`) refresh. The feedback export labels a jj revision by its short change id (`commitShortId` from the `commitInfo` sidecar); git keeps the 7-char sha. Client code asks one question for both families: `commitShaFromMode` / `isCommitDiffType` (`packages/review-editor/utils/`), server code `commitFamilyId` (`packages/shared/review-core.ts`). The Commits view is a self-contained detour: entering it memoizes the previously active diff, exiting to Tree restores that diff verbatim (exiting to Git status resets to `since-base` as always), the memo clears whenever any non-commit diff is applied, and a reload that serves a commit-family diff with a non-Commits panel view snaps once to the session default so the commit diff cannot outlive the visit. The toggle never writes the persisted `reviewPanelView`/`defaultDiffType` pair (no server writes from a toggle click), but it does record a cookie-only last-used memo (`reviewPanelViewLastUsed`, `sections` | `tree` — never `commits`; the Commits view is session-only). A review OPENS on caller-pinned flags (`plannotator review --base <ref>` / `--diff-type <id>`, session-only: `openStatePinned` on `/api/diff` disables the panel-pair self-heal and never persists anything) ?? session choice ?? last-used memo ?? persisted `reviewPanelView` ?? the registry default, which is **`tree`** (cookie-only, written only by Settings through `setReviewPanelView()`, which also syncs the memo so an explicit choice is never shadowed by a stale one — except the App self-heal, which passes `recordLastUsed: false` to repair the diff half of a conflicted pair without touching the memo). There is no first-run chooser: a profile with no `reviewPanelView` cookie opens on Tree, which renders every diff type, and the `Tree | Git status | Commits` toggle plus Settings → Git are the two ways to change it. The persisted pair is coupled: the Sections view only renders `since-base`, so choosing a classic diff default snaps the persisted view to Tree and vice-versa (enforced in the Settings Git tab and by the coupled setters in `packages/ui/config/reviewView.ts`); with `tree` as the default the pair is trivially consistent for a reviewer who has chosen neither, so the App self-heal only ever fires for a profile whose `reviewPanelView` cookie already reads `sections` — chosen in Settings, or seeded by a build whose registry default was still `sections`.

**Staging display invariant:** `useGitAdd`'s `stagedFiles` is the EFFECTIVE staged set (sections-sidecar snapshot + session stage/unstage overrides) and is the only source any surface may render staging state from. The sidecar entry's `staged` flag is a snapshot — ORing it back in makes files unstaged mid-session render as staged (and inverts the next toggle).

`since-base` is only offered when the base ref actually resolves — on a repo whose trunk isn't discoverable (`trunk`, no `origin/HEAD`) `getGitContext` omits it and the default falls through to `uncommitted`, so committed branch work is never silently hidden. The since-base patch/sections/fingerprint/file-content paths all degrade to `HEAD` together when merge-base fails for a resolvable-but-unrelated base. There is no first-run review-setup dialog (`ReviewSetupDialog` was removed, as `DiffTypeSetupDialog` was before it): the panel view simply defaults to Tree and the panel toggle / Settings → Git change it. The one-time dialog chain is guide intro → look-and-feel → Edit Mode → token hover cards → the terminal-tools announcement; none of the dialogs stack. The token hover announcement is last and additionally skips a session where hover cards cannot run at all (no live workspace), WITHOUT consuming its cookie, and never shows to a reviewer whose trigger is already non-default (which after the boolean-to-trigger migration is exactly the early adopter who turned cards off). Analysis layers no longer add a startup dialog: Semantic Changes retains its enabled default, while Call Flow remains disabled until the user explicitly enables it in Settings, which is also consent for its managed runtime installation.

### First-run terminal-tools announcement

A one-time panel announcing Plannotator's two terminal clients, **Plannotator
TUI** (`plannotator/plannotator-tui`) and **Herdr Annotate**
(`plannotator/herdr-annotate`). One cookie covers every surface —
`plannotator-announce-tui-herdr-seen`, value `'1'`, read and written by
`needsTerminalToolsAnnouncement()` / `markTerminalToolsAnnouncementSeen()` in
`packages/ui/utils/terminalToolsAnnouncement.ts` — so dismissing it in plan
review retires it in annotate and code review too, and vice versa. It is a
plain storage key rather than a settings-registry entry for the same reason
`lookAndFeelAnnouncement.ts` is: `configStore.ensureLoaded` seeds every
registry default into a cookie on first access, so a registry-backed flag could
never tell "never seen" from "seeded default".

The component is `packages/ui/components/TerminalToolsAnnouncementDialog.tsx`
(shared shell: portal, `z-[100]`, hand-rolled Escape + Tab wrap + focus
restore, `data-terminal-tools-announcement-dialog`). It is video first: the
real demo footage fills the top of the panel edge to edge, and the text under
it is one headline and one sentence, then one action row (star the two repos,
"Watch on X", "Got it"). There is no mock terminal, no install commands, no
feature list; the repo pages carry all of that. Two deliberate departures from
its siblings: the backdrop dismisses (the panel collects no decision, so there
is nothing to lose by closing it impatiently), and its keydown listener is
registered on the CAPTURE phase and swallows `Mod+Enter`, so a keystroke aimed
at the announcement cannot approve a plan or post a review behind it.

**Media is hosted, not bundled.** The two demos (`tui-herdr-full-demo` and
`tui-herdr-lite-demo`, mp4 + webm + poster jpg each, ~23MB together) live in
`apps/marketing/public/assets/` and are served from
`https://plannotator.ai/assets/` once the marketing deploy syncs them, the same
precedent as `GuideIntroDialog`'s hero image (the Edit Mode recording is small
enough to inline; these are not). The `<video>` is `muted playsInline loop`
with `preload="auto"`, mp4 first in source order, and `autoPlay` unless
`prefers-reduced-motion` matches, in which case the poster waits behind a
play button. A `Full | Lite` segmented switch (`role="tablist"`) swaps the
footage and the "Watch on X" link together; the panel is keyed per demo so
playback and load-failure state reset with it. If neither source can load
(offline), the frame keeps its place and shows a "Watch on X" link over it.
The panel's width follows the viewport HEIGHT as well as its width
(`min(1120px, 100%, (100dvh - 14rem) * 1280/806)`) so the video never
scrolls out of view on a short window. No CSP is involved: the app HTML ships
no `Content-Security-Policy`, and the servers only set one on sandboxed
artifact responses.

**Ordering: LAST in each app's chain, never first.** Code review gates it
through `terminalToolsAnnouncementCanShow` on guide intro, look-and-feel, Edit
Mode and token hover cards; the plan editor gates it on the
look-and-feel chooser, goal setup and permission-mode setup. The destination
spotlight and the auto-viewed toast were extended to defer behind it too, so
nothing stacks. Last rather than first because none of those dialogs consumes
this cookie: a session busy asking setup questions defers the announcement to
the next load instead of burning it, and that also puts it in front of the right
reader — someone opening Plannotator for the first time is still learning this
app, while the people who should hear that it now runs in a terminal are the
ones who already answered every setup question and see it on their next load.

Suppressed, never consumed, on: archive browsing and read-only shared plans
(which is also what the share portal serves, via `isSharedSession`), the
compact touch shell, and while the initial payload is still loading. The
guides.show portable viewer never mounts either App, so it is unaffected by
construction. `@plannotator/ui` exposes no first-run-suppression seam on
`configurePlannotatorUI`; a host that wants the announcement off installs its
own `storageBackend` (the documented escape hatch) and pre-seeds the key.

### First-run "Ask this session" announcement

A one-time panel for 0.28.0's integrated sessions: Ask AI answered by the agent session that opened
Plannotator, and reviews that no longer hold that session. Same shape as the terminal-tools
announcement above: `packages/ui/components/AskSessionAnnouncementDialog.tsx` (portal, `z-[100]`,
Escape / Tab wrap / focus restore, backdrop dismiss, capture-phase keydown that swallows
`Mod+Enter`, `data-ask-session-announcement-dialog`) and `packages/ui/utils/askSessionAnnouncement.ts`
(one plain cookie, `plannotator-announce-ask-session-seen` = `'1'`, shared by every surface; not a
settings-registry entry, for the same seeding reason).

**Who sees it:** only a plan review, annotate or code review session that is actually connected
right now: `/api/ai/capabilities` lists the session-bridge provider for `claude-code`, `pi` or
`opencode` and its status is not `gone` (`connectedAskSessionAgent`), and Ask AI is reachable on
the surface (the plan editor's `canUseAI` and not taken over by the annotate agent terminal; code
review's AI button). Everything else defers WITHOUT writing the cookie, so the reader sees it in a
session where it is true: no bridge (remote, `--tailscale`, Windows, the mod off, `-p`, Pi's
event-API path, OpenCode 1, an older CLI), a gone session, other origins, `PLANNOTATOR_AI=disabled`,
archive / shared / no-server sessions, the compact touch shell and the initial load. The headline
names the connected host and the footer always says "This session is connected"; there is no
setup variant. OpenCode's copy says "code review and annotate no longer hold the session" because
its plan review still does.

**Timing:** `useFirstRunAnnouncementWindow` (`packages/ui/hooks/`) lets it open only before the
reader's first pointer press, key press or focus into a text field, within 4 s of the initial load,
and never while a text field (a comment composer) or an iframe has focus. Work inside the raw-HTML
and live-app iframes never reaches the parent's listeners, so a window `blur` after the first
second (the viewer's own startup may focus its iframe) also closes the window. Capabilities can answer late (model
discovery), and a dialog that opened then would take focus mid-comment and be dismissed unread by
the next Space or Enter; instead it misses the load, cookie unwritten. Once open it stays until
dismissed.

**Ordering:** after the terminal-tools announcement and never on the same load
(`askSessionAnnouncementPendingThisLoad` is false while that cookie is unset), so a fresh browser
sees terminal tools first and this one on the next load; behind every chain dialog in both apps
(the permission-mode setup included). Code review's destination spotlight, auto-viewed toast and
history-shortcut guard defer behind it like they do behind terminal tools.

**Media:** real footage, hosted like the terminal-tools demos:
`apps/marketing/public/assets/ask-this-session-demo.{mp4,webm}` + `ask-this-session-poster.jpg`
(1280x800, ~35 s). Recorded from a real Claude Code 2.1.289 session (real plugin and mod, real
compiled CLI, real review app) whose model calls went to a scripted local stand-in for the
Messages API, so the question, the Read tool call and the streamed answer are real traffic with
scripted model text. Offline it says the video could not load; reduced motion waits on the poster.

### Agent tool switch: Settings row and first-run offer

The `plannotator` agent tool (off by default on Pi and OpenCode 2, on for the Claude Code mod and in Oh My Pi)
has a switch in Settings → General on plan review, annotate and code review, and a one-time
offer on Pi and OpenCode 2. Both read `parseAgentToolSetting(serverConfig)`
(`packages/ui/utils/agentToolSetting.ts`): present only when the server reports
`agentToolHost` and `agentToolEnabled` (the integration that launched the server has the tool),
so OpenCode 1, Codex, the classic hook and `@plannotator/ui` hosts (which pass neither
`agentToolSetting` nor `onAgentToolChange` to `Settings`) get nothing. An OpenCode bridge
alone is not enough: the plugin also reports that its host can register the tool (a
`tool.transform` domain) as `PLANNOTATOR_OPENCODE_TOOL_CAPABLE=1` on the CLI it launches and
`opencodeToolCapable` on its in-process plan server (`agentToolHostForServer` in
`packages/server/ai-runtime.ts`), so an OpenCode host without the domain, or an older plugin,
gets no switch and no offer. The row says when a change applies: the next Pi session, the next
time Claude Code / OpenCode / Oh My Pi starts (the mod and the OpenCode plugin decide once per
process; OMP may keep the extension loaded across its sessions), and what it costs per host
(`agentToolCostNote`: Pi and OpenCode about 800 tokens per request, Oh My Pi one short line).
Writes go through
`saveAgentToolSetting` (POST `/api/config` `{ agentTool }`, awaited, not the settings registry's
debounced best-effort write-back); the handlers answer 500 when the value did not reach
config.json (`agentToolSaveFailed`), and both surfaces show that. The row is locked with a note
when `agentToolEnv` is set. One `useAgentToolSetting` per App feeds both, so a change in one
shows in the other.

The offer (`AgentToolAnnouncementDialog`, `packages/ui/utils/agentToolAnnouncement.ts`, cookie
`plannotator-announce-agent-tool-seen`, a plain storage key for the registry-seeding reason)
follows the announcement shell (portal, `z-[100]`, Escape / Tab wrap / focus restore, backdrop
dismiss, capture-phase `Mod+Enter` swallow) but collects a decision. Approved design ("Loop";
design record, not in this repo): a theme-token SVG of the round trip over the question
"Do you use Plannotator as a skill?", two example requests, one line of why, the token cost,
and the buttons "No, I’ll just use slash commands" (initial focus) and "Yes, turn it on". The
copy is the approved design's; agree a change with the maintainer before editing it. The
dialog cannot close while a save is in flight, a failure shows the reason with "Try again",
success says when it starts and offers Done. Declining, Escape, the backdrop and a successful
save write the cookie; a failed
save does not. It shows only for a Pi / OpenCode 2 host (never Oh My Pi, where the tool is on by default) whose next-session value is off, never
chosen in config.json (`agentToolConfigured`), and not set by the env. Ordering: LAST in each
app's chain, after terminal tools (latched, `agentToolAnnouncementPendingThisLoad`) and after
"Ask this session" per load (`earlierAnnouncementMayShow`: that one was shown this load, or is
pending and its capabilities answer is outstanding or eligible), so never two announcements on
one load, while a reader who is never connected still gets the offer. Same deferrals as the
others (archive, shared, no server, compact, loading) and the same
`useFirstRunAnnouncementWindow`. Code review's destination spotlight, auto-viewed toast and
history-shortcut guard defer behind it.

### Review drafts and PR pushes (#1590)

Code-review drafts (`/api/draft`) are keyed by `contentHash(rawPatch)`, so a local review whose diff changes still starts without its old draft (unchanged, out of scope). **PR mode only** additionally stores the draft under a stable target key, `prDraftTargetKey(meta, scope)` = `pr-` + hash of platform + host + repo (`owner/repo` or GitLab `projectPath`, lower-cased) + PR number + diff scope (`layer` / `full-stack` are different patches). All of it lives in `packages/shared/review-draft.ts` (vendored to Pi); both review servers hold one `createReviewDraftSession()` and route `/api/draft`, `/api/feedback` and `/api/exit` through it (without a target key every call is the plain `draft.ts` call, including the historical always-`ok` save response).

- **Load** tries the patch key first and returns it unless the target copy is strictly newer by `draftGeneration`. The target copy is stamped server-side with the `patchKey` it was saved on plus `patchKeys` (every patch it was ever saved on); when served for a different patch the response carries `patchChanged: true`. Clients can forge none of these fields and never see the lists.
- **Delete** clears the patch key, the target key, and every remembered patch key, with or without a generation. A decision (`/api/feedback`, `/api/exit`) additionally clears every PR target the session saved to or restored from (an in-place `/api/pr-switch` or `/api/pr-diff-scope` moves the target, and a submit must not leave the earlier one behind); a client `DELETE` (clear-all, dismiss) touches only the target on screen.
- **Tombstones**: the target key's tombstone guards the whole logical draft — a save at or below it is rejected under BOTH keys (PR mode answers `409 { ok: false, found, draftGeneration }` instead of swallowing it), and a patch-key copy at or below it is not served.
- **In-place switches**: `/api/pr-switch` and `/api/pr-diff-scope` responses carry `draftState: { found, draftGeneration }` for the new keys. The client's `adoptDraftTarget` raises its generation to that floor (otherwise every save after switching onto a previously submitted target would be refused). When the target holds a draft, the hook loads it and AUTO-MERGES its items into the session through `onDraftTargetMerge` (skipping ids the session already holds or deleted this session; the app re-checks their anchors and shows a small non-blocking toast), then autosave saves the merge normally — no banner after a switch. The only wait: while that read is in flight, autosave skips writing under the new target (it would overwrite a draft it has not read). Each read is two attempts, each bounded by `TARGET_LOAD_TIMEOUT_MS` (5s), so a hung `GET /api/draft` fails instead of pausing autosave. If both attempts fail, the target counts as unreadable: autosave still never writes over it, and instead retries the read on each later save attempt, saving normally once a read succeeds. The next switch (or unmount) supersedes all of this, so nothing can stick. A per-switch counter makes a stale load from an earlier target a no-op. The page-load restore banner is unchanged.

Client side (`packages/review-editor`, `utils/codeAnnotationAnchor.ts`): in PR mode `withPRContext` records on each line comment `anchorText` (the anchored lines), `anchorContext` (two lines before and after on the same side plus the hunk header's function context, so a common line like `}` is not "still valid" by coincidence) and `anchorSnapshot` (the review snapshot id whose coordinates it uses). `reanchorCodeAnnotations` runs on restore (every in-scope line comment when `patchChanged`) and whenever the snapshot on screen changes: a comment whose text and context still match at the same side/lines is re-stamped; any other in-scope line comment, including one with no anchor fields, gets `outdated: true` and keeps its old line numbers (never dropped, never moved). File and general comments, and comments bound to another PR or scope, pass through. The app remembers the latest layer snapshot per PR, and `buildReviewSubmission` posts a line comment inline unless `canPostInline` refuses it: an outdated comment, or one stamped on a snapshot other than the one the page KNOWS for its PR. No evidence is not evidence of change: an unstamped comment, or one for a PR whose snapshot this page has not seen (after a reload only the PR on screen is known), posts inline. Refused comments go in the review body with the code they were written on; only a comment an anchor check marked outdated carries `OUTDATED_ANNOTATION_LABEL`. Restoring a draft whose patch changed does not restore Viewed marks on files still in the diff (`restorableViewedFiles`: the draft cannot tell which files the push touched), and every `/api/feedback` post, the platform path's status post included, carries `draftGeneration`. Outdated comments are not drawn on the diff (the review-state context filters them), show an "Outdated" chip and an Edit action in the sidebar, export under `OUTDATED_ANNOTATION_LABEL`, and a sidebar click opens their file without a scroll request.

### Image previews in code review (#1598)

A changed image whose patch chunk has no hunks (git's binary stub, our oversized stub, or a header-only GitHub/GitLab fallback chunk) renders as a Before/After preview (`packages/review-editor/components/ImageDiffPreview.tsx`) instead of the "Binary or oversized file" notice, in the single-file view and the all-files view, when the server advertises `imagePreviewSupported`. Added files show After only, deleted files Before only, identical bytes (pure rename, mode change) one pane plus "Contents unchanged"; panes stack under ~480px of width, in the compact shell, and for tall images. Cards fetch only once near the viewport (IntersectionObserver), abort on unmount, and keep a 64-entry object-URL LRU per snapshot; SVG is only ever shown through `<img src=blob:…>`. The notices stay the fallback: not an image → binary notice, an oversized stub over 10 MB → oversized notice. The all-files view takes the preview through a `renderImagePreview` render prop that only the review app's all-files panel sets, so the guide chain and the guides.show viewer keep the plain notice and never request images.

Freshness: the endpoint checks the snapshot id only, not a per-image VCS fingerprint (that probe per image would be expensive on a large PR). So for a working-tree side (uncommitted, unstaged, since-base, local-vs-remote, GitButler workspace) the After pane can show a file NEWER than the diff on screen if it changed after the snapshot; the "Diff out of date · Refresh" banner (the 5s `/api/diff/fresh` poll) covers that case, and a refresh re-binds every card to the new snapshot. Server reads run behind a 4-wide limiter that takes the request's abort signal (Bun `req.signal`, Pi the response `close`), so reads queued for cards the reviewer scrolled past are dropped before they run, and no platform API call starts for a request that is gone. The client cache holds at most 64 sides and 128 MB, never revokes an object URL a mounted `<img>` still uses, and ignores a response that arrives after the page moved to another snapshot.

Server side, every decision is in `packages/shared/review-image.ts` (vendored to Pi): eligibility via `findPatchFileEntry`, caps (`MAX_REVIEW_IMAGE_PREVIEW_BYTES` 10 MB, `MAX_REVIEW_IMAGE_PREVIEW_PIXELS` 50 MP, both in `packages/core/diff-paths.ts`), sniffing, header dimensions, error mapping and headers; both servers only say where the current mode reads a side, behind a 4-wide read limiter. Which object each side is comes from ONE table per VCS shared with hunk expansion: `resolveDiffSideSources` (git), `resolveJjSideRevs` (jj), `resolveGitButlerSideSources`; bytes come from `readDiffSideBytes` (`git cat-file --batch-check` then `cat-file blob <oid>`, never `show`; worktree reads refuse symlinks and require the realpath inside the repository toplevel) over the optional runtime methods `runGitBytes` / `readFileBytes` / `realPath` / `runJjBytes` (absent means unavailable). PR mode reads the local checkout at the fixed merge-base/head commits first and falls back to `fetchPRFileBytes` (GitHub contents API, then the blobs API for files over 1 MB after a size check; GitLab JSON files API), base64 in both cases so bytes survive the CLI's text stdout. Workspace mode delegates per child repo (`WorkspaceReviewSession.getFileBytes`). Off: static patch, P4, the guide chain and guides.show.

### File kinds: Code, Tests, Generated

Approved design record "review-file-kinds" (not in this repo). One pure classifier, `fileKind(path, generated?)` in `@plannotator/core/file-kind` (vendored to Pi), sorts every changed file into `code`, `test` or `generated`: **generated** is the host's generated set when it has one (the review server's `generatedFiles`, `.gitattributes` included), else the built-in name list; **test** is a test file name (`*.test.`, `*.spec.`, `*.cy.`, `*.e2e.`, `*.test-d.` or `*_test.` followed by a code extension (`CODE_EXT`: ts, tsx, js, py, go, rs, java, kt, rb, cs, ...), with a name before the marker; `*.stories.*`; `test_*.py`, `conftest.py`, `tests.py`; `*.snap`) or a folder above the file named `__tests__`, `__snapshots__`, `__fixtures__`, `__mocks__`, `test`, `tests`, `spec`, `e2e`, `fixtures`, `testdata` or `testFixtures` (case-insensitive), a Gradle source set `src/<name>Test`, or a .NET `*.Tests` / `*.UnitTests` project; **code** is everything else, docs and config included. `contest.ts`, `latest.ts`, `test.ts`, `testing-library.config.js`, `openapi.spec.yaml` and `load_test.md` stay code. `groupByFileKind` splits a list in that kind order, keeping each item's order. The three glyphs (angle brackets, a flask, a package) are `FileKindIcon` in `@plannotator/guide-viewer/FileKindIcon`, shared by the review app, the Inbox and guides.show.

- **Tree** (`FileTree`, `utils/fileKindTree.ts`): with "Group by kind" on (Tree controls popover, default on, cookie `plannotator-review-group-by-kind` = `off` when turned off; deliberately not a settings-registry entry, which the guides.show viewer bundles) and two or more kinds, the tree is one block per kind, each today's folder tree, under the status view's section header (`PanelSectionHeader` in `FileRowBits.tsx`, which `SectionsPanel` uses too) plus the icon, file count, viewed/total and +/-. A header folds its block in the tree only; Generated starts folded. Folder paths are scoped per block (`kind:path`), so the expansion hook and collapse-all keep working. j/k/Home/End follow the block order. A file that becomes active by any route (j/k, a click in all-files, the scroll highlight, an annotation or search jump) opens its folded block, as folded folders open for the active file; a new file list never does, so Generated stays folded when a diff loads. With hide-viewed on, a block whose rows are all hidden hides its header too. The all-files surface follows it too (`fileOrder: 'kind'`, `getFileKindOrder`); the Git status view keeps its sections and the Commits view its tree order. One kind, or the switch off: today's tree.
- **Flask**: test files get it in diff headers (`FileHeader` `isTest`, from `AllFilesCodeView` and the single-file panel) and on Git status rows. Tree rows inside a block get no icon.
- **Guided Reviews** (`GuideSectionCard`): within a chapter, files come together by kind (code, then a "Tests N" subhead, then "Generated N"), the author's order kept inside each kind; subheads show only with two or more kinds; diff cards follow the chip order; test cards stay open and generated cards start folded (`GuideFileCard` `kind`). Hosts may pass `generatedFiles` on the guide host (the review app does); the Inbox and guides.show use the name list. No change to the guide format, prompt or export. It costs the guides.show viewer about 1.3 KB gzip, inside its 400 KB budget.

### Markdown preview in code review

Approved design: owner-approved variant C (design record, not in this repo). A Markdown file (`.md`, `.mdx`, `.markdown`, config.json `markdownExtensions`) can be shown rendered instead of as a line diff.

**Controls.** One control per Markdown file (owner, 2026-10-12 controls amendment, variant "Menu"): a button in the file's header naming its view with a chevron ("Source ▾"), opening a menu **Source** (the line diff), **Changes** (the rendered diff) and **Read** (the whole document rendered, no diff marks), in that order, the same words everywhere. Added and deleted files, and a rename that changed nothing, offer Source and Read only (`markdownViewsFor` in `utils/markdownPreview.ts`; a wish for Changes there resolves to Read, `resolveMarkdownView`). The menu is Base UI's (`components/MarkdownViewMenu.tsx`: `role="menu"` with `menuitemradio` items and `aria-checked`, arrows, Home/End, type-ahead, Escape back to the button); its title says "Select text to comment" in a rendered view. In the compact touch shell the same button (drawn 36 px, a 44 px hit area from an `::after` box) opens the same items as a bottom sheet titled "Show <file> as". There is no global button and no switch inside the file. Defaults: every file starts in Source (approved); a view picked on any Markdown file becomes the starting view for every Markdown file not set by hand in this review, so those follow on screen, and it is remembered for the next review in the cookie `plannotator-markdown-view` (`source | changes | read`; cookie only, deliberately not a settings-registry entry, which is bundled into the guides.show viewer; the earlier `plannotator-markdown-preview-all=true` is read once as `changes`, rewritten under the new name and removed). A file set by hand keeps its view for the session. Navigation that needs a view (a search hit or a line comment needs Source, a rendered comment its own view, the "not in this view" action) sets that one file only and remembers nothing across reviews (`show`, vs a person's `choose`); like a pick, it pins that file for the session, so a later pick on another file does not move it (chosen over "navigation leaves no override" because yanking the file away from the search hit or comment the person just jumped to would be worse). While a file holds the edit session (All files; it is always in Source then, since Edit is refused on a rendered file), its view is locked: starting the session pins the view it shows (an override, as if set by hand), so a pick or `P` on another file, which moves every file not set by hand, cannot move it; a pick, `P` or navigation aimed at it is refused; its menu is disabled with "Finish editing first" in All files and in the single-file view (`markdownViewDisabledReason`), and `P` on it shows that as a toast (`onLocked`). A search hit in it scrolls in place (the session's file always shows its diff). The pin stays after the session ends (the file keeps Source until picked), and the swap effect re-runs when the session ends, so nothing held back stays half-applied (`lockReason` / `setEditingFile`; `AllFilesCodeView` reports the session's file through `markdownPreview.onEditingFileChange`). `P` reads its key target from `composedPath()[0]`, so typing `p` in the Pierre editor (a shadow root) never switches views. Key (`review-markdown-preview` scope in `packages/ui/shortcuts/code-review/`, so help and the docs page list it): `P` steps the open file (in All files, among the files intersecting the viewport, never the overscan: the Markdown file holding focus or under the pointer, else the top-most Markdown file, resolved when the key is pressed through `markdownPreview.registerViewTarget`) Source -> Changes -> Read -> Source, skipping Changes where the file has none, and counts as a pick; never while typing, off a diff, or on a code file. There is no `Shift+P`: a pick already moves every file not set by hand, so an "every file" key would only override files the person set on purpose. Files shown in Changes or Read show an eye in the file tree. The control is not drawn by `FileHeader` itself (`renderMarkdownView` slot): `DiffViewer` draws it, and in All files the panel passes `renderViewControl`, whose component reads review state from context, so a Changes <-> Read switch relabels it without republishing the CodeView item; read-only hosts (the guide chain, guides.show) carry none of it. State: `useMarkdownPreview` / `useMarkdownPreviewKeys` (`packages/review-editor/hooks/useMarkdownPreview.ts`), on review state as `markdownPreview`, absent (no UI anywhere) without the advert or with no full contents (static patch).

**What the rendered views show** (`components/MarkdownFilePreview.tsx`, lazily loaded). Changes is plan review's `PlanCleanDiffView` over `computePlanDiff(old, new)` with its review-only seams (`renderBlock`, `lineGutter`, `foldUnchanged`, `unchangedClassName`; see `packages/ui/HANDOFF.md`): added, removed and changed sections (classic stacked old over new), unchanged runs folded behind "N unchanged sections", source lines in a gutter. Read renders the new version whole (a deletion: the old one). Both render blocks through `BlockRenderer`; Mermaid and Graphviz fences render as code, never as diagrams (owner decision, performance wins: the single-file review build inlines every dynamic import, so even a lazy diagram import put ~6.7 MB of Mermaid/Graphviz runtimes into every review and ~600 ms before the file tree; `tests/entry-assets.test.ts` fails if the review app imports a diagram module or its bundle carries a diagram runtime; diagrams return only through true lazy loading, never by bundling), images through the per-revision route below (old side for removed sections, new side otherwise), links through the PR's resolver (a file of this review opens in the review; anything else is inert). In a PR review (`prMetadata`; `holdRemoteImages` overrides) a remote image is held behind a placeholder: any source a browser would fetch from another server, read the way a URL parser reads it (`isRemoteImageSource`: tabs and line breaks dropped, a backslash counts as a slash, so `https:host/a.png`, `https:/host/…`, `https:\\host\…`, `//host` and `\\host` all count; every `http(s):` source does, holding one too many being harmless), and a line above the document says how many with **Load remote images**; a click on that button or on any held placeholder loads them for that preview, so opening a stranger's file never tells a tracking pixel's server the reviewer's IP address. Repository images always load through the route. Local reviews load remote images as written. Added and deleted files show their one side whole (the header's status letter and the green or red rail say which); a rename with no change says so. Both sides must still agree with the patch on screen (`markdownPreviewSides`), else "changed after the diff was captured"; over 300 KB a side asks first (Preview anyway). A search hit, a line comment opened from the sidebar, or a line selection sends the file back to Source. In All files the card lives in the item's header slot (measured like an image preview) and the item's diff is swapped for a hunkless one while previewed (`markdownPreviewFileDiff`; the real one, including a full-content augmentation, waits in `fullDiffsRef`); hosts that pass no `markdownPreview` prop (the guide chain, guides.show) get none of it.

**Comments.** The PR description's experience: `useAnnotationHighlighter` in comment mode on the rendered text, select anything and the composer opens. The result is an ordinary file-scoped `CodeAnnotation` carrying `markdownPreview: { originalText, view, diffContext?, startMeta?, endMeta? }` (`packages/ui/types.ts`), so it is listed in the sidebar under its file (with a "rendered" tag and the quote), shown in the file's comment banner in Source, drafted, undoable, and counted. In the other view it is found by its text (stored positions only apply in the view it was made in); when the text is not there (a comment on removed text, seen in Read) the preview says how many comments are not in this view, with "Show in Changes" / "Show in Read". The export prints it under its file as "Comment on the rendered Markdown" with the quote and, in the rendered diff, "(in added / removed / changed text)" (`markdownPreviewQuote`). In a PR review it always goes into the review body with the quote, never inline and never as a file-level thread (`buildFileScopedBody`). Line comments are not drawn in the preview (the header says so). The feedback archive records the quote as `originalText`.

**Capability.** Every diff payload carries `markdownPreviewSupported` beside `imagePreviewSupported` (`/api/diff`, `/api/diff/switch`, `/api/pr-diff-scope`, `/api/pr-switch`, both runtimes): true wherever `/api/file-content` can read a full file, i.e. every session except a static patch. Absent (an older server) reads as false, and the client then shows no preview UI.

**Images.** A previewed Markdown file's images load through `GET /api/review-markdown-image?doc=&side=old|new&src=&snapshot=` (`packages/shared/review-markdown-image.ts`, vendored to Pi; `handleReviewMarkdownImageRequest`), read at THAT side's revision, never from the working tree by default, so a deleted file, a PR or a committed diff shows the images it had. The rules, in order: the session must be one `/api/review-image` serves (`available` = `imagePreviewSupported`); `doc` must be a file in the current patch whose path at that side is Markdown (`.md`, `.mdx`, `.markdown`, or config.json `markdownExtensions`) and that side must exist (`404 not-in-diff` / `absent`); `src` (the source exactly as written; the client never trims it, and the route drops leading and trailing ASCII whitespace from it and from every reference alike, as a browser's URL parser does) must be a plain path — no scheme, `//`, backslash or control character, at most 2048 chars, `?query`/`#fragment` dropped, `%xx` decoded — naming an image by extension (`400 bad-request`, `415 not-image`), checked before anything is read; it resolves against the doc's folder at that side (a renamed doc's old side uses its old folder; a leading `/` is the repository root, GitHub's README rule; in a multi-repo workspace that is the workspace root), and one that climbs above the root is `403 outside-repo`; the doc's text at that side (read up to 2 MB, `413` past it) must reference `src` as an image — a markdown image (`![a](src)`, `<src>`, with a title), a reference-style image's definition, or an `<img src>` value (decoded), never one inside a fenced code block or an inline code span (`stripMarkdownCode`) — else `403 not-referenced`, so the route reads only what the file shows. In jj sessions every read names its path as a literal (`jjRootFileFileset`: `root-file:"…"`, `\` and `"` escaped, control characters as `\xHH`), never a bare path after `--`, which jj parses as a fileset expression (`a|b.png` would read `a` and `b.png`); this covers `/api/review-image`, this route and full-file contents, in both runtimes (`packages/server/jj-fileset-literal.test.ts`, real jj). The image itself goes through the same per-side reader as `/api/review-image` (one `readReviewSide` per runtime now serves both routes, behind the same 4-wide limiter) and is answered by the same tail, `reviewImageBytesResponse` in `review-image.ts`: the 10 MB / 50 MP caps, the LFS-pointer refusal, the sniffed `Content-Type`, the sandbox CSP, `nosniff`, CORP and `ETag`/304. Tests: `packages/shared/review-markdown-image.test.ts` (the decision table over a fake reader) and `packages/server/review-markdown-image.test.ts` (both runtimes against a real repo).

### Durable viewed-file progress (#1136)

Viewed marks are independent of annotation drafts and survive feedback submission,
server restarts, and reopening a review. `packages/shared/review-progress.ts` owns
fingerprinting, storage and request validation, mirrored into Pi by `vendor.sh`.
`GET/POST /api/review-progress?snapshot=<snapshotId>` loads or updates progress;
writes carry the server-issued scope key and displayed per-file fingerprints and
reject stale snapshots. The review UI restores automatically through
`useReviewProgress`; explicit viewed/unviewed mutations (including auto-view and
stage-to-view) save immediately, and pending saves flush before switches/decisions.

Storage is `${dataDir}/review-progress/{scopeHash}/{pathHash}.json`: atomic per-file
records prevent independent tabs/processes from overwriting unrelated marks.
Local Git scopes include canonical worktree root, branch and comparison selection
(base ref only for base-relative modes), never HEAD except when detached. PRs use
their URL and layer/full-stack scope. Workspace/non-Git reviews and piped patches
keep the existing draft behavior. Local Git carries a generation-time
`fileIdentities` sidecar: `--raw --patch --no-abbrev` supplies object IDs, paths and
modes without changing rendered patch bytes or existing annotation draft keys.
Bounded worktree hashes are checked against the displayed index line; no live
files are read at click time. This also covers mode-only changes and pure renames.
Files without reliable identities (including oversized untracked files) cannot
restore as viewed. Platform text patches use per-file patch hashes when full IDs
are absent; opaque binary/metadata-only patches without IDs cannot restore.
A mismatch is unviewed regardless of the auto-mark setting. Explicit unchecks
override platform seeds; in-session auto-view suppression survives content refresh.
Progress loading has explicit loading/ready/unsupported/error states: unsuccessful
loads preserve current marks and retain the legacy draft fallback, and a later
mutation or flush retries errors. Requests and the entire pre-decision/switch flush
each have a five-second limit, so stalled persistence cannot block review actions
indefinitely; a timeout warns and unsaved edits remain pending for a later retry.
Legacy draft viewed fields are ignored only on
progress-enabled surfaces (and deferred while capability detection is pending).
Purge uninstall removes `review-progress`; ordinary uninstall preserves it.
Opt-out: `PLANNOTATOR_REVIEW_PROGRESS=0` or `{ "reviewProgress": false }` (see the
environment table); the server then captures no progress snapshot and the client
falls back to draft-based viewed tracking.

**Guided Review ticks mark files viewed (#1786).** Ticking a guide section
"Reviewed" (live job or `saved:{id}` guide) marks its files viewed through the
same path as the per-file Viewed checkbox (`handleGuideMarkFilesViewed` in
`packages/review-editor/App.tsx`: durable progress, auto-view suppression lifted,
`/api/pr-viewed` in PR mode). A file the guide splits across chapters is marked
only once EVERY chapter showing it is ticked; refs not in the diff on screen are
skipped; un-ticking unmarks nothing (`filesViewedByTickingSection`,
`packages/review-editor/utils/guideReviewedViewed.ts`). Not gated on the
auto-mark setting (it is an explicit gesture). Auto-mark on scroll still does
not run inside the guide. The guide chain and the guides.show viewer are
unchanged: the host wraps `onToggleReviewed` in `GuideScreen`.

### GitButler review invariants

GitButler is a distinct VCS provider, ordered after JJ and before Git in both Bun and Pi. It is selected only while symbolic `HEAD` is `refs/heads/gitbutler/workspace` (or legacy `gitbutler/integration`) and the repository has GitButler's local target-ref configuration; a leftover database or an ordinary branch with the reserved name is not detection. An active workspace requires `but >= 0.21.0` on `PATH`, and a missing/incompatible CLI is an explicit error rather than a fallback to ordinary Git staging against the synthetic workspace commit. `--gitbutler` forces this provider; `--git` remains the escape hatch.

The default `gitbutler:workspace` view is GitButler's reported merge base versus the working tree plus untracked files, so it includes every applied committed change and assigned/unassigned worktree change. Multi-branch stack views are committed-only merge-base→stack-tip Git diffs; branch views are committed-only first-parent segment diffs. Client IDs encode branch-name anchors, never GitButler's transient CLI IDs. Do not concatenate independent GitButler hunks: their bases can differ. Assigned worktree hunks stay in Workspace until GitButler exposes an authoritative combined stack diff.

GitButler assignment is not the Git index, so the provider never opts into stage/unstage. Git-status sections, commit history, remote-base discovery/fetch, and the first-run Git setup remain `vcsType: "git"` only. File expansion uses the exact object range for committed views and merge-base/working-tree pair for Workspace; fingerprints cover the visible Git content plus canonical stack/branch topology. Nested multi-repo mode maps only `workspace-current` to GitButler; staged/unstaged/last modes are unavailable when a GitButler child is present.

### Code-review Ask AI context

Ask AI's "changes under review" context for **code review** is generated by the shared agent-review prompt machine (`buildAgentReviewUserMessage` / `buildAgentReviewUserMessageForTarget` in `packages/server/agent-review-message.ts`) — the same machine the launchable review jobs use — and is **delivered on the user's messages, not the system prompt**. The review server computes it for the current view (`buildCurrentAiReviewContext` in `packages/server/review.ts`, mirrored in `apps/pi-extension/server/serverReview.ts`) and ships it as `aiReviewContext` in the diff payloads (`/api/diff` and the switch/PR endpoints). The client (`packages/review-editor`) latches it onto each question via `buildReviewContextPreamble` (`packages/ui/utils/aiPrompt.ts`): the full block on the first message and whenever the view changes, a short reminder otherwise (never re-pasting a large diff). This keeps the agent looking at exactly the on-screen changeset across every mode (uncommitted/untracked, branch, merge-base, stacked-PR full-stack, hide-whitespace, PR worktrees, workspace, GitButler, jj). The code-review system prompt (`buildCodeReviewPrompt` in `packages/ai/context.ts`) is intentionally role-only.

## Ask AI Provider Defaults

Ask AI providers are detected independently from installed/authenticated local CLIs, then the UI picks a default from the detected Plannotator origin. The mapping lives in `packages/core/agents.ts` (re-exported via the `packages/shared/agents.ts` shim) and is applied by `packages/ui/utils/aiProvider.ts`:

| Origin | Preferred Ask AI provider |
|--------|---------------------------|
| `claude-code` | `claude-agent-sdk` |
| `amp` | no dedicated provider; fallback to saved/server default |
| `droid` | no dedicated provider; fallback to saved/server default |
| `codex` | `codex-sdk` |
| `opencode` | `opencode-sdk` |
| `pi` | `pi-sdk` |
| `copilot-cli` | no dedicated provider; fallback to saved/server default |
| `gemini-cli` | no dedicated provider; fallback to saved/server default |
| `mistral-vibe` | no dedicated provider; fallback to saved/server default |

Automatic resolution is session-only and never writes a preference. Explicit per-origin choices are persisted in cookies, so a user can override the automatic match for one agent without changing the default for another.

**New chat (#1981).** Plan review, annotate and code review show a small **New chat** row above the Ask AI messages once there are any (`NewChatButton`, `packages/ui/components/ai/`; the optional `onNewChat` prop on `DocumentAIChatPanel` and the review `AITab`, absent for hosts, so their panel is unchanged; no keyboard shortcut). It calls `useAIChat().newChat()`: the thread and its Plannotator AI session id are cleared, so the next question starts a fresh session (a separate AI gets the full document or "changes under review" context again). Unlike `resetThread` (a document switch), `newChat` never stops anything: while a question is in flight (streaming, creating its session, or waiting on a busy "Ask this session"), or while a busy answer still offers "Ask when it finishes" / "Interrupt and ask now" (`hasPendingBusyChoice`), it returns false and the button is unavailable (`aria-disabled`, still focusable, the reason as its `aria-describedby` description), so no turn is aborted and no pending ask is dropped. It keeps the provider/model choice and the per-page record of the draft list the agent session already received (`deliveredDraftsRef`), because with "Ask this session" a new chat reaches the SAME host session, which still remembers earlier questions; there the button reads **Clear chat** and says so. Earlier chats are not kept to reopen.

**"Ask this session" (session bridge).** A host can let Ask AI be answered by the agent session that opened Plannotator instead of a separate SDK agent. The host implements the small `SessionBridge` interface (`packages/ai/session-bridge.ts`, vendored to Pi: `host`, `status()` = `ready | busy | blocked | gone`, `modes { turn, transient }`, `ask(req, sink, signal)`, optional `interrupt()`) and passes it as `sessionBridge` to the server (`startReviewServer` / `startAnnotateServer` / plan `ServerOptions` on Bun; review, annotate and plan review on Pi), which then registers `SessionBridgeProvider` under id `session-bridge` as the ONLY Ask AI provider, behind the unchanged `/api/ai/*` endpoints: with a bridge (in-process or pull) the SDK providers go into a separate catalog-only registry (`catalogRegistry` on `createAIEndpoints`, set by `createAIRuntime` / `createPiAIRuntime`), so `/api/ai/capabilities` lists only the bridge under `providers` and makes it `defaultProvider`, and `/api/ai/session` answers `503` for any other provider id whatever the client saved. The catalog-only providers exist so the agent-job launchers (Review Agents, Code Tour, Guided Review) keep their discovered Claude / Codex model lists: `?activate=<id>` naming one runs its discovery and reports it under `catalogProviders`, which only `useModelCatalogs` reads; Ask AI never reads that field. Without a bridge (no mod, OpenCode 1, remote mode, `--tailscale`) the SDK providers register exactly as before. `/api/ai/capabilities` adds `label` ("Ask this session · Pi") and live `sessionBridge { host, status, modes }` for it, `models: []` (no model picker). The provider, not the host, enforces one question at a time across threads (`ask_in_flight`), sends no system prompt (the question carries the `SESSION_ASK_HEADER` line plus the surface), and never interrupts implicitly: a busy session answers `agent_busy`, and the client re-asks with `/api/ai/query` `busyPolicy: "wait"` ("Ask when it finishes", streams `status: waiting` until idle) or `"interrupt"` ("Interrupt and ask now", host `interrupt()` then ask). `session_gone` / `session_blocked` offer no other AI (there is none): the answer shows a plain note that the session that opened Plannotator is gone, or waiting on this decision, and Ask AI cannot reach it. Abort cancels only our question; the runtime `detach()`es the bridge before teardown so a decision/exit never stops a turn already running. **Take-over (every host):** once another message enters the turn answering our question (the person typing into the session, another extension's steer; never a background task's notification, an engine notice, a compaction, or on Claude Code a peer session's message), the rest of that turn answers THAT message, so the host stops streaming at once, keeps what it already sent, and settles with the bridge error code `taken_over` (`SessionBridgeErrorCode`; the provider maps it to `session_taken_over` with `SESSION_ASK_TAKEN_OVER_TEXT`, the neutral "Another message entered this session while it was answering, so the rest of the reply went to that message."; the Claude Code mod sends `SESSION_ASK_TAKEN_OVER_BY_PERSON_TEXT`, "You typed into this session…", when it knows the person typed it). When the answer had already finished before the other message entered (the turn's last model response stopped with no tool call: Claude `end_turn`, Pi `stop`, OpenCode `finish: "stop"` with no `session.tool.input.started` in that step, since some OpenAI-compatible providers report "stop" on a tool-calling step; and some answer text was shown), it settles `done` instead: a follow-up such as Plannotator's own decision never turns a complete answer into a cut one. From then on neither a Stop nor "Interrupt and ask now" stops that turn: Stop only closes the question, and `interrupt()` refuses (`SESSION_ASK_TAKEN_OVER_INTERRUPT_TEXT`) while the taken-over run lasts. The client (`useAIChat`) treats `session_taken_over` as a note, not an error: the partial answer stays and `SessionAskNote` renders the text under it (`response.notice`). Per host: Claude Code mod, `prompt.submit` with the question turn's `turnId` from an allowlisted origin (see "Claude Code mod"); Pi, a `user` message, or a custom message other than ours delivered right after a `turn_start` (a steer or follow-up), in the run answering our question; a non-triggering display-only custom message (e.g. `plannotator-handoff`) is appended at `turn_end`, outside that window, and takes nothing over; the run stays protected until `agent_settled` (idle on Pi without it), so an error retry of the person's run is covered; OpenCode 2, a `session.inbox.delivered` for another row whose kind, read from `session.inbox.enqueued` (`item.type`), is `user` (synthetic, compaction, move and unseen rows never take over), after ours was delivered AND the model began answering (`session.step.started` or any answer output), so a command's session-URL notice promoted in the same batch as the question is not a take-over. **Older servers:** the pull server advertises the codes it knows as `features` on every poll answer (`SESSION_BRIDGE_POLL_FEATURES`, today `["taken_over"]`). A pull host (the mod's `bridge.ts`, `runPullSessionBridgeClient`) talking to a server without `taken_over` settles a take-over as `done` with the partial answer plus the note as its last paragraph (`takenOverFallback`), because an older server reads the unknown code as `failed` and its UI would replace the partial answer with the error. Client (`resolveAIProviderSelection`): a bridge in the list is the selection in every status, ahead of any saved pick; without one the order is unchanged. The saved provider cookies are never rewritten for this, so a pick still applies to sessions without a bridge; with a bridge the Ask AI bars and Settings → AI show only its label (no provider or model picker). Code review sends the diff's identity (`buildSessionReviewIdentity`), never the patch. **Draft annotations (#1748):** the session is the agent the feedback is FOR, so the reviewer's unsubmitted annotations never reach it as feedback. `/api/ai/query` ignores `contextUpdate` (the feedback export a separate AI still gets on every question after the first) for a bridge session; the plan/annotate editor instead sends `draftAnnotations`, a plain one-line-per-draft list (`formatDraftAnnotationsForAsk` in `packages/ui/utils/parser.ts`: `Draft 2 (line 14): comment on "…" — …`, no export title, no "pieces of feedback", no "Feedback on" headings, no skill injection), which `useAIChat` sends only when it differs from what the agent session last RECEIVED (`draftAnnotationsToSend`; recorded once the stream shows delivery, so a busy or gone ask resends it; kept per page, not per Ask AI session, because a new thread or a document switch is a new Ask AI session on the same agent session), and `''` once when every draft was removed. A string in the list that reads like the end marker (any case or spacing) is neutralized, so a draft or page text cannot close the frame early. `formatSessionAskText` frames it between the surface and the question with `SESSION_ASK_DRAFTS_LABEL` ("…Do not act on them; the reviewer will send them when ready…") and `SESSION_ASK_DRAFTS_END` (or `SESSION_ASK_DRAFTS_CLEARED`), in turn and transient mode alike; the system prompt is untouched. The annotate agent terminal's Ask prompt uses the same list and frame (`buildTerminalAskPrompt`, deduplicated per terminal session). Code review sends no annotations to Ask AI at all. **Pi** (`apps/pi-extension/pi-session-bridge.ts`): review, annotate, last and plan review (plan review no longer blocks the session, see "Pi plan review does not block" below), off in remote mode; the question is a `pi.sendMessage({ customType: "plannotator-ask", display: true, details: { askId } }, { triggerTurn: true })` turn read back from `message_start` / `message_update` text deltas / `tool_execution_start` / `agent_end`; listeners register once at load because `pi.on` returns no unsubscribe before Pi 1.0. **OpenCode 2** (`apps/opencode-plugin/opencode-session-bridge.ts`): review, annotate and last ask a real turn — `ctx.session.prompt({ id, text, delivery: "steer", metadata: { source: "plannotator-ask" } })` under a message id generated in OpenCode's own ascending `msg_` format, streamed back from `ctx.event.subscribe()` (`session.inbox.delivered` with our id starts the answer, then `session.text.delta` / `text.ended` / `tool.input.started`, ended by `session.execution.succeeded|failed|interrupted`), with `session.wait` + `session.context` as the fallback when the event stream is missing (upstream #44788). Delivery is "steer", not "queue", on purpose: every V2 command leaves its session-URL notice as a pending steer row, and a queued question would wake the session with that notice promoted alone as its own model turn (seen live on 2.0.22). Busy comes from the execution events cross-checked by a single outstanding `session.wait` probe; abort and "Interrupt and ask now" use `session.interrupt` (whole execution), only on a turn that is ours or on the reviewer's explicit choice. Plan review answers from context only ("Quick answer from this session · OpenCode", `modes { turn: false, transient: true }`): `submit_plan` is a pending tool call, so a real turn cannot run until the decision (a prompt sent then waits for the tool result, verified live), and `markPlanReviewPending` makes EVERY bridge on that session report `blocked` so nothing can interrupt the review. The quick answer is `session.generate` (no transcript write; verified live on 2.0.22 with OpenAI during a pending `submit_plan`, and `@opencode/ai`'s `normalizeToolHistory` fills the unfinished call with an error result for every provider); it still offers the model its tools, so the question carries `SESSION_ASK_TRANSIENT_NOTE` and an empty answer (a tool call) is reported as a failure. The embedded plan server takes the bridge in-process; review/annotate/last and the CLI plan fallback run the `plannotator` CLI as a child and use the pull bridge below. **OpenCode 1** has no bridge (a second adapter over V1's different message/event model, not a small lift). **Claude Code** answers through its mod over the pull bridge below (review, annotate, last and plan review, all real turns; see "Claude Code mod"); without the mod Claude Code has no bridge.

**Pull bridge (host-neutral, `packages/ai/session-bridge-pull.ts` server half, vendored to Pi; `session-bridge-pull-client.ts` host half).** For a host that runs the Plannotator server as a SEPARATE process and must not open a listener of its own (the OpenCode plugin's CLI child and the Claude Code mod). The host generates a per-launch secret and starts the server with `PLANNOTATOR_SESSION_BRIDGE_TOKEN` (>= 32 chars), `PLANNOTATOR_SESSION_BRIDGE_HOST` (`opencode` / `claude-code` / `pi`) and optional `PLANNOTATOR_SESSION_BRIDGE_MODES` (`turn,transient`; default `turn`). The Bun CLI takes that config at its very first line (`takeEnvPullSessionBridgeConfig`, cached once per process; `createAIRuntime` reads the cache) and deletes the three variables, so nothing it spawns (git/gh before the server starts, agent jobs, terminals, the auto-update wrapper) inherits the token; `--tailscale` discards it outright (`discardEnvPullSessionBridgeConfig`). The runtime registers the same `SessionBridgeProvider` over it; it is off in remote mode and under `--tailscale` (and an in-process bridge wins). Pi's `createPiAIRuntime` accepts the same config as its `pullSessionBridge` option (no env takeover: Pi itself always bridges in-process). The host learns the port (OpenCode: `PLANNOTATOR_READY_FILE`) and then talks to two endpoints on `http://127.0.0.1:<port>`, both `POST` + JSON with `Authorization: Bearer <token>`: `/api/ai/bridge/poll` `{ status?, modes?, waitMs? }` long-polls (clamped to 25s; answers early when there is work) and returns `{ commands, closing?, superseded? }`, commands being `{ type: "ask", askId, text, mode }`, `{ type: "cancel", askId }` and `{ type: "interrupt", interruptId }`; `/api/ai/bridge/event` takes one event or `{ events: [...] }` — `started`, `delta`, `tool`, `done`, `error` (per question, `code` one of `busy|blocked|gone|aborted|failed|taken_over`; anything else reads as `failed`); every poll answer also carries `features` (optional protocol features the server knows, `SESSION_BRIDGE_POLL_FEATURES`), `status`, and `interrupted { interruptId, ok, message? }` — and answers `409 { code: "ask_not_active" }` for a question that is no longer running, which tells the host to stop it. Commands are re-sent every ~5s until acknowledged (any event for that question; `interrupted` for an interrupt), so hosts dedupe by id. Guards, in order: a loopback Host with the server's own port (the runtime's `authorizeSessionBridgeRequest`, `403 session_bridge_forbidden_host`), no `Origin` header (`403`, a browser is never the host), the bearer token (`401`); without a pull bridge both paths answer `404`, which an older-binary-aware host treats as "no bridge". Liveness: until the host's first request the bridge reports `ready` (a question waits for the first poll); no first request within 30s, or 30s with no open poll after that, is `gone`, and a running question then fails `session_gone`. The newest poll supersedes an open one. A reviewer's Stop drops a question the host never confirmed, else queues `cancel` and frees the slot when the host confirms (or after 15s); `detach()` (decision / shutdown) drops only unconfirmed questions, and `dispose()` answers the open poll `closing`. Both runtimes route the two paths through `createAIEndpoints` (`pullBridge` dep), and Bun lifts the idle timeout for the poll (`isLongLivedAIEndpointPath`). Tests: `packages/ai/session-bridge-pull.test.ts` (fake host over the real client: streaming, early question, busy wait / interrupt, abort before and after pickup, host disappears, never connects, transient, bad token / Origin / rebinding Host, supersede, dispose, detach), `packages/server/ai-runtime.sessionBridge.test.ts` (env takeover, scrub, remote-off), `apps/opencode-plugin/session-bridge-cli.test.ts` (plugin ↔ CLI child end to end).

**Model lists come from the installed tools, not hand lists.** Claude's list is the SDK's `supportedModels()` against the installed `claude` (a throwaway process with no prompt, `settingSources: []` so no user hooks run, no MCP servers, 10s cap, ~0.5s measured); Codex's is the app-server `model/list`. Both run lazily behind the provider initializer (`?activate=` or the first session), never at startup; a success is kept for the process, a failure may be retried after 60s (`createBestEffortOnce`), and the capabilities answer marks each such provider's list `modelsSource: 'fallback' | 'discovered'` so the client forgets a fallback answer and retries on its next load. The same discovery captures the tool version once (`claude --version` run alongside it; codex from the app-server initialize `userAgent`, via `cliVersionFrom`), kept even when discovery fails, and the answer carries it as an optional `toolVersion`; every Claude/Codex model picker (Agents tab launchers, Guided Review, Ask AI bars, Settings) shows a muted `ModelSourceHint` line ("From your installed Codex 0.155.1", or the built-in-list variant on `fallback`) only when `toolVersion` is present, so a host that omits it gets no hint. Both runtimes share `createDeferredModelDiscovery`: an `?activate=` probe waits for discovery, and so does a session for every provider except Claude, whose sessions resolve the model against the current list while discovery finishes in the background, so the first Ask AI answer does not wait on it — except when that list is still the fallback and lacks the requested pick (e.g. `opus[1m]`), where the session waits for discovery rather than silently running a different model once. One shape, `CatalogModel` in `packages/core/model-catalog.ts` (id, label, efforts + default effort, fast mode, `resolvedId`), serves Ask AI AND the review / Code Tour / Guided Review launchers: `useModelCatalogs` (`packages/ui/hooks/`) fetches the same `/api/ai/capabilities?activate=` answer for the ONE engine a launcher is set to, and `useAgentSettings` resolves saved picks against it at read time (the cookie is never rewritten). ONE resolver, `resolveModelChoice`, is used by the launchers, Ask AI's client (`aiProvider.ts`) and the AI session endpoint: exact id → the alias whose `resolvedId` covers it → the same family's alias (`claude-opus-5` → `opus`) → the surface default (Claude `opus` for review, `sonnet` for tour/guide; Codex `''` = the model the Codex list marks default, except Guided Review, which prefers `gpt-6-luna` when offered: `PREFERRED_GUIDE_CODEX_MODEL`) → the catalog default; it never moves a pick onto a `[1m]` id unless the pick was one. Efforts clamp to the model's own levels, launches wait until the catalog settles, and a loading row shows meanwhile. The Claude catalog drops the SDK's `default` pointer row and adds a bare latest alias per family offered, and always offers `opus` / `sonnet` / `haiku` (some CLIs, e.g. Claude Code 2.1.141, name Opus only through the `default` row, whose description then supplies the version); alias labels carry the version parsed from the row's `resolvedModel` (`claudeModelVersion`: "Opus 5.5 (latest)"), since the SDK's `displayName` has none. Codex fast mode is dropped when resolution replaces a saved model with a different one; changing Fast or reasoning then re-keys the section to the model shown. Codex fast support is read from `serviceTiers` (a `priority`/`fast` tier) as well as the deprecated `additionalSpeedTiers`. The only static lists are the small `CLAUDE_FALLBACK_MODELS` / `CODEX_FALLBACK_MODELS`, used when discovery fails.

> **Codex transport note:** the `codex-sdk` provider id is a stable identifier only — it no longer uses `@openai/codex-sdk` / `codex exec`. It drives a long-lived `codex app-server` process over JSON-RPC (`packages/ai/providers/codex-app-server.ts`), which respects the user's/enterprise-managed approval policy and supports interactive Allow/Deny approvals. The id stays `codex-sdk` to preserve saved cookie preferences, the `agents.ts` mapping, and the UI reasoning-effort gate.

> **OpenCode transport note:** the `opencode-sdk` provider spawns its own `opencode serve` per process on an OS-assigned port (`port: 0`) and never attaches to a server it did not spawn (an attached server can't be cleaned up by us, and opencode's per-directory instances accumulate in it without eviction). The spawned server is closed on dispose and on process exit. Model discovery is deferred behind the provider initializer (`?activate=` from the model picker, or the first opencode session) exactly like Codex — nothing spawns at server boot, so the picker lists opencode with an empty model list until first activation. Regression-pinned by `packages/ai/providers/opencode-sdk.test.ts`.

## Annotate Flow

```
User runs /plannotator-annotate <file.md | file.html | https://... | folder/>
        ↓
Claude Code: plannotator annotate subcommand runs
OpenCode/Pi: event handler intercepts command
        ↓
Input type detected:
  .md/.mdx/.txt → file read from disk
  plain-text config/data formats (.yaml .yml .json .jsonc .json5 .toml .ini .cfg .conf .properties .csv .tsv .log .xml .env.example)
             → read from disk, rendered as plain text exactly like .txt (.env itself is
               deliberately excluded — it commonly holds secrets and annotate history
               copies file contents; source-code extensions stay with code review)
             All single-file annotate reads and /api/doc document serves are capped at
             2MB (`MAX_ANNOTATABLE_FILE_BYTES` in `packages/core/annotatable.ts`) —
             larger files get a clear "File too large to annotate (max 2MB)" error.
             Extra extensions listed in `markdownExtensions` (config-only setting,
             e.g. `.livemd`) join this set and render as markdown, frontmatter stripped.
  .mmd/.mermaid → file read, rendered as ONE Mermaid diagram in the full
             diagram viewer (see "Diagram files" below) — not as text
  .dot/.gv   → same, through the Graphviz engine
  .html/.htm → file read, rendered as raw HTML by default (or converted to markdown with --markdown)
  https://   → fetched via Jina Reader (default) or fetch+Turndown (--no-jina)
  http://localhost:* (also 127.x and [::1])
             → LIVE app annotation by default when a quick probe returns HTML:
               the running app is mirrored through a loopback reverse proxy and
               annotated in place (see "Live app annotation" below). --static
               forces the classic conversion pipeline; --app forces live mode
               and fails loudly when it cannot apply.
  folder/    → file browser opened, files converted on demand
  a.md b.html c.md (several existing file paths)
             → ONE review of all of them, in that order (mode
               "annotate-bundle"; see "Several files in one review" below)
        ↓
Annotate server starts (reuses plan editor HTML with mode:"annotate")
        ↓
User annotates content, provides feedback
        ↓
Send Feedback → annotations sent to agent session
Done / Approve (gate) → positive decision recorded (see the decision control below)
```

### Annotate header decision control

Every annotate surface's header decision is one adaptive split control, `DecisionControl`
(`packages/ui/components/DecisionControl.tsx`), rendered from the pure `buildDecisionSpec`
state→spec mapping (`packages/ui/utils/decisionSpec.ts`) beside a ghost-X Close: `Done` (or
`Approve` in gate mode) with nothing to send, `Send Feedback` otherwise, with the alternate
decisions and the in-place note composer behind the caret. One `submitPrimaryDecision()` callback
serves the header primary, the global `Mod+Enter` handler, and the compact primary row, so
keyboard and header can never disagree. Transport routing is pure in
`packages/editor/annotateDecision.ts`: `Done` and every note post `/api/feedback` (a note becomes
a `GLOBAL_COMMENT` at submit time with a one-render deferred submit — zero server change), so
`formatAnnotateOutcome` shapes and strict-gate exit codes are byte-identical to the old
keyboard-only zero submit; only gate-mode approvals reach `/api/approve`. The non-gated empty
menu carries a single composer, "Send a note…" (maintainer ruling: the old "Done with a note…" /
"Request changes…" pair differed only by framing on the same transport and was collapsed into
one item); the approval-framing sentence (`buildCompleteAnnotateFeedback`'s `approvalFraming`)
now serves only the non-gated discard path, and the only confirm left is the
explicit `Done/Approve, discard n annotations…` menu item (plus the pre-existing
close-with-content warning). Compact/touch rows are generated from the same spec, so a visible
positive decision exists in every state; composer rows open `DecisionNoteDialog`. The header flip
predicate is `hasFeedbackToSend`, so feedback already delivered through the agent terminal shows
the positive primary rather than a stale Send Feedback.

The approve-carrying gate items (`Approve with a note…`, `Approve with notes`) follow the
`approvalNotesSupported` advert on `/api/plan`, the same on markdown, raw-HTML and live-app
surfaces. The Bun CLI sets it with `supportsAnnotateApprovalNotes` = `--gate` and not `--hook`
(`apps/hook/server/annotate-output.ts`): `--json` carries the note as `feedback`, plaintext prints
the configured `approvedWithNotes` prompt instead of `The user approved.` (a bare approval keeps
that line byte for byte), and the Claude Code mod's plaintext `--gate` launches deliver it from the
result file as an approved-with-notes turn. `--hook` has no message on approval, so the items stay
hidden there. Pi and OpenCode advertise it from their own servers. Non-gated annotate has no
approve channel: its only composer is "Send a note…" (feedback).

### Annotate Options menu and Settings parity

Annotate renders the same document app as plan review, so its Options menu and
Settings dialog match plan review item for item; only rows that describe a PLAN
decision stay plan-only. Settings `mode="annotate"` shows General, Theme,
Display (width reads "Document Width"), Saving, Labels, Vim, Shortcuts, Files,
Obsidian, Bear and Octarine — gated on the optional `annotateParity` prop,
which `AppHeader` passes and a `@plannotator/ui` host that omits it does not
(hosts keep the pre-parity annotate tab set; see `packages/ui/HANDOFF.md`).
The notes-app enable switches are the SAME cookies plan review's approve reads
(`body.obsidian`/`bear`/`octarine`), so enabling one from annotate also makes
plan review save every approved plan there; the annotate description says so
explicitly. Plan-only, and hidden in annotate: the **Hooks**
tab (plan-time hooks; `/api/hooks/status` exists only on the plan server),
**Save Plans** (decision snapshots in `plans/` are written on approve/deny),
the three **Auto-save on Plan Arrival** switches (the arrival auto-save effect
is gated `!annotateMode`), **Permission Mode**, and OpenCode **Agent
Switching** (annotate decisions never send `agentSwitch`). The Archive sidebar
tab stays plan-only too (the annotate server has no `/api/archive/*`).

**Agent Instructions** (Options menu) is offered in every annotate session.
`buildAnnotateAgentInstructions(origin, surface)`
(`packages/ui/utils/annotateAgentInstructions.ts`) is the annotate twin of
`buildPlanAgentInstructions` (plan text is unchanged): same endpoint and
plan-mode validator, "document" not "plan", no deny/resubmit loop, and one
section per surface picked by `resolveAnnotateInstructionsSurface` — its own
read command (`.plan`; `.rawHtml` for raw HTML; `.targetUrl` for a live app;
`/api/doc?path=<p>&doc=1 | jq -r '.markdown // .rawHtml'` for a folder, so
HTML and data files print too) plus the targeting rules the validator actually
supports: `diagramAnchor` on POST for diagram files, `htmlAnchor` by PATCH
only (POST drops it), `pageUrl` by PATCH for live-app routes. Folder sessions
are stated plainly: an external comment cannot target a document; it lists in
the panel whichever document is open, is not highlighted inline, and rides the
submitted feedback. Not done yet: POST accepting `htmlAnchor`, and a `path`
field so a folder-session external comment targets one document.
`packages/server/annotate-agent-instructions.test.ts`
executes every curl/JSON example in the text against a real annotate server,
so an instruction that drifts from the server fails there.

Save to Obsidian / Bear / Octarine menu items are hidden (a `Mod+S` quick save
toasts instead) when the session has no document text (`notesSaveAvailable`: raw-HTML, live-app, a
folder with no file open) — the server skips an empty `plan`, so those items
were silent no-ops.

### Tolerant argument resolution

Slash-command hosts forward raw user words to `plannotator annotate` verbatim (on Claude Code through a bash-substitution prefix that runs before the model sees anything), so non-strict invocations resolve their arguments in three tiers. The shared logic lives in `packages/shared/annotate-target.ts` (vendored to Pi) and is wired into the CLI's annotate branch plus the OpenCode and Pi command parsers:

1. A single-token invocation runs the classic pipeline unchanged: a bare correct path behaves exactly as before, and a lone typo'd path still fails with `File not found` and exit `1`.
2. With several tokens, each token is probed; exactly one naming an existing file, URL, or folder proceeds with it (`annotate look at notes.md please` opens `notes.md`). **Bundle rule (0.29), checked first:** when EVERY token is an existing regular file named by its path (resolved from the cwd, `~` or an `@` prefix; `probeAnnotateBundlePath`, never a name found only by searching the project, never a URL or folder), they open as one review in the typed order with duplicates dropped (`selectAnnotateTokenTarget(..., { bundlePath })` → `{ kind: "bundle" }`; the same file twice is `single`, on every host); an existing file of an unsupported type or over the 2MB cap among them fails naming it (`resolveAnnotateBundleFiles`; a `.env` is named as refused). When every token READS as a file path (`looksLikeFilePath` from the tool contract: a separator, a leading `~` `.` `@`, or an extension) but some name nothing at all (nothing exists at the path, `annotatePathExists`, and nothing is found by search), the selection is `{ kind: "missing" }` and the host fails naming them (`buildMissingAnnotateFilesMessage`, exit 1, or 2 under a strict gate): an explicit list of files with a typo never narrows to the files that exist. An existing path is never missing, so a stray `.` or `..` beside a file still opens the file and an existing folder keeps the ambiguity error. Known edge: a dotted word such as `Node.js` or `v2.0` reads as a file path, so `annotate notes.md about Node.js` is prose (fast path) but `annotate notes.md Node.js` fails naming `Node.js` when no such file exists. Otherwise two or more resolving tokens (prose around them, a URL or folder among them, a searched name) error naming every candidate rather than guessing, and the error gains one hint line, `ANNOTATE_BUNDLE_HINT` ("To review several files together, pass only their paths: plannotator annotate a.md b.html"), on hosts that open bundles. A host that cannot open bundles passes no `bundlePath` and keeps the #1182 tiers exactly. Bare directory names only count as targets when they are the sole argument, so a stray word matching a directory (or `.`) cannot hijack the fast path; unrecognized dash-prefixed tokens disable the tolerance entirely so a typo'd flag (`--no-jna`) errors the way it always did instead of being silently skipped.
3. When nothing resolves, the CLI emits an agent-addressed handoff that echoes the words tried and asks the reading agent to re-run with a concrete target (content flags such as `--markdown` / `--no-jina` / `--render-html` are echoed for the re-run; transport flags are not). In plain mode the handoff goes to **stdout with exit `0`**, because a non-zero exit from a Claude Code bang-prefix skill aborts the prompt before the model sees any output; with `--json` / `--hook` it goes to stderr with exit `1` so machine-readable stdout stays reserved for decision records. OpenCode and Pi surface the same message as a host notification.

Strict invocations (`--require-approval` / `--result-file`) bypass all three tiers: `args[1]` is the target and a typo'd path stays a startup failure with exit `2`. With several arguments, a strict gate takes only the bundle rule: several existing file paths make one review (approve covers every file); anything else exits `2` ("File not found: <first>" when the first argument names nothing, else "A strict annotate gate takes one target, or only existing file paths…"), where extra words used to be silently ignored. The refusal is decided by probe and stat only: nothing is fetched, probed live, or reported as resolved first.

### Several files in one review (annotate bundles)

`plannotator annotate spec.md mock.html notes.md`, the `plannotator` tool's `target: [...]`, a taken-over Bash command with several file paths, and `/plannotator-annotate a.md b.md` on Pi and OpenCode (embedded and CLI-bridge) open ONE review of the listed files, in the given order, with ONE decision (owner decisions: no flag, no file-count limit, per-file decisions later).

- **Server mode `annotate-bundle`** in both runtimes (`packages/server/annotate.ts`, mirrored in `apps/pi-extension/server/serverAnnotate.ts`): options `bundleFiles: AnnotateBundleFile[]` (`{ path, renderAs }`, from `packages/shared/annotate-bundle.ts`, deliberately not in `@plannotator/core` so the published core export map is unchanged; two or more or the server throws) and `filePath` = the bundle root (`annotateBundleRoot`, the deepest directory holding every file, compared by path segment). `/api/plan` adds `bundle` (the list, in order) and `projectRoot` = the bundle root. `/api/doc` serves the files and what they link to under the single-file rule: reference roots are the cwd plus each file's own directory, and for a symlinked file also its target's whole directory, as a single-file session on that path would (`bundlePaths` on `getAnnotateReferenceRootPaths`), so a document beside a bundle file opens as a linked document exactly as from that file alone, and anything outside is `403`. The editor never walks the bundle root. Each text file's version history is saved when the review opens (the folder pipeline's per-file memo, run eagerly; raw HTML keeps none, as in folders), and `/api/doc` returns its version fields.
- **Edit Mode:** a bundle file is editable exactly when it would be opened alone (a single-file session): Edit Mode's source save writes back to it. The writable set is the REAL paths of the bundle's own files, captured when the review opens (`resolveBundleSourceSavePaths` in `packages/shared/source-save-node.ts`, vendored to Pi): an entry counts when its named and real paths are both a `SOURCE_SAVE_FILE_REGEX` type (`.md`, `.mdx`, `.txt`) and it is a regular file, so raw HTML, diagram sources and data files stay read-only, as alone. `/api/doc` grants `sourceSave` only to a document whose real path is in that set (`createBundleSourceSaveCapability`, scope `folder-file`, because the client addresses the save by `path` as in a folder session; a symlinked entry's capability names its target), and `POST /api/source/save` writes only when the request's `path` resolves to a member (`resolveBundleSourceSaveTarget`: the realpath, or for a deleted file its real parent plus its name, so a file removed mid-review can be recreated), with `saveSourceFileAtomic`'s `allowedFiles` re-checking the real path at write time. Everything else is `403 not-writable`: a document a bundle file links to (read-only, as a document linked from a single file is), a sibling, a new file, anything outside. The 2MB annotate cap and the hash conflict check (`409`) apply as for a single file. A bundle entry that is a symlink is writable at its target even outside every reference root (the user named that file), but the set is fixed at open: an entry swapped for a symlink to another file afterwards resolves outside it and is `403`, and a regular-file entry deleted mid-review is recreated in place by the next save (a symlinked entry whose target was deleted is not: its path no longer resolves to the target). Every session kind's `/api/source/save` (single file, folder, bundle; both runtimes) also refuses, in this order: a cross-origin request (`isSameOriginOrNoOrigin`, `403`; the VS Code panel's `Sec-Fetch-Site: same-origin` passes), a `serverSession` mismatch (`409 session_mismatch`), and any save once the review is decided, by feedback, approve, Close or the agent's close (`409 { ok: false, code: "not-writable", decided: true }`, `sourceSaveDecidedResponse` in `packages/core/source-save.ts`). Unlike draft saves, an agent close does not let source saves through: a draft is crash recovery the close keeps, while a source save writes a file the agent may already be editing, and the closed tab cannot start a save anyway. The editor needed no new gate: a bundle is a folder session, and `canEditMarkdown` already allows a folder file the server granted source save; saving, switching files with an unsaved buffer, re-anchoring comments after an edit, drafts and per-document copies follow the folder session.
- **Drafts:** the session draft is keyed by the ordered list (`bundle:\0<paths>`), and every file's comments are also saved under that file's path key (#1710's document copies), so they follow the file into a single-file, folder or other bundle session. Host status `documents` lists the files.
- **Decision record:** the host result record (`PLANNOTATOR_HOST_RESULT_FILE`) and the feedback archive gain `documents: [{ path, annotationCount }]` in bundle order (`annotateBundleDocumentCounts`, counted from each submitted annotation's `documentPath`). The archive record's surface is `annotate-bundle` with `target.documents` and no `filePath`. The agent message frames the feedback with `Files: <path>, <path>` (`annotateBundleTargetText`) on every host.
- **Editor** (`packages/editor/App.tsx`): a folder session (`annotateSource` stays `'folder'`) with `bundleFiles` state. The first file opens by itself; the header's `BundleSwitcher` (`packages/editor/components/BundleSwitcher.tsx`, "2 of 3 · mock.html ‹ ›", desktop; the compact shell names the position in its title and offers Previous/Next file in its Options menu) and the Files tab follow the given order: the tab shows the bundle as a synthetic, never-fetched file-browser section (`bundleDirState`, merged into `navigatorFileBrowser` beside any configured directories; the filesystem root is the empty dir path so `${dir}/${node}` stays absolute). A link from one bundle file to another opens it as that bundle file. A bundle file has no Close pill, no sidebar "Back to…" and no HTML header Back (the switcher moves between the files); a document a bundle file links to goes back to the last bundle file shown (`bundleBackPath`, the first file before any), never to the folder's empty "choose a file" state (`DocBadges`' `onBack` is optional for the `folder-file` variant). The export lists one section per file in bundle order under `BUNDLE_DOC_EXPORT_HEADING` ("File Feedback"; `resolveFeedbackSections({ bundleOrder })`, unlisted linked documents after), the All files panel follows the same order (`groupAnnotationsByDocument`'s `order`), and Ask AI's context carries `bundlePosition`, so the session-bridge surface line reads "annotating /…/mock.html, file 2 of 3".
- **Version skew:** an older CLI answers several paths with the ambiguity error lacking `ANNOTATE_BUNDLE_HINT`; the Claude Code mod and the OpenCode CLI bridge recognize that (`isOlderCliBundleRefusal`) and say to update Plannotator to open several files at once. An older host never sends a list.

Tests: the selection table in `packages/shared/annotate-target.test.ts`; `packages/server/annotate-bundle.scenarios.ts` (both runtimes; includes Edit Mode saves, the `403` outside the bundle, a symlinked entry, an entry swapped for a symlink after open, a deleted entry recreated, and the cross-origin, VS Code-proxy, `serverSession` and decided-session guards on source save); `apps/hook/server/annotate-bundle-cli.test.ts` (the CLI as a process: order, one decision, the host record's `documents`, strict gates, the hint); `packages/shared/annotate-bundle.test.ts`; the mod's `controller.test.ts` and `plannotator-tool*.test.ts`; OpenCode `commands.test.ts` and `cli-bridge.test.ts`; and the DOM test `packages/editor/App.bundle.test.tsx` (first file opens, switcher and file list in order, one section per file in bundle order; Edit Mode offered on each bundle file and a save reaching the file, against the real server run as a child process by `packages/editor/testing/annotateBundleServer.ts`, since `Bun.serve` refuses happy-dom's `Response`).

The bang prefix in the Claude Code skill is deliberate: #872 (commit `aac5aacb`, "restore `/plannotator-*` bash execution on Claude Code") put it back so the slash command never depends on the model choosing to run the binary. Argument-shape problems belong here in the CLI's resolution, not in the skill templates.

Hosts that run the CLI as a child must hand it the words as SEPARATE arguments, or none of this runs: one argument is one path to the CLI (`annotate ". notes.md"` is "File not found"). The OpenCode CLI bridge (OpenCode 2 native commands and the OpenCode 1 CLI runtime) does this with `annotateCliTargets` (`apps/opencode-plugin/cli-bridge.ts`) over the shared `annotateTargetWords` (`packages/shared/annotate-args.ts`: quotes group a path with spaces only when they open and close a word, so prose apostrophes stay in their words; an unterminated quote is prose, backslashes are kept, known flags are dropped). It keeps ONE argument, exactly as before, when the whole input names an existing target (an unquoted path with spaces), for a single word, and when a word starts with `-` (a typo'd or prose flag must never reach the CLI as a real one). The `plannotator` tool's single target is never re-split. `apps/opencode-plugin/annotate-words-cli.test.ts` runs the REAL CLI for this. An OpenCode 2 slash command that fails (a refused argument or the CLI's startup error) posts a transcript notice, `Plannotator /plannotator-annotate failed: <reason>` (`createCommandFailureNotifier` in `v2-client.ts`: `session.synthetic` with a description and `resume: false`, so no model turn; the context hook drops it from model requests like the session-URL notice, matching only a `text` that ends with the marker `commandFailureNoticeText` adds and the visible `description` lacks, so a copy of the line the person types or pastes is never dropped); the OpenCode 1 CLI runtime shows an error toast. Before this the failure only reached the log, which OpenCode 2 discards. Tool launches report failures as the tool result instead.

### Annotate drafts follow the file

Annotate drafts used to be keyed only by a hash of the document text, so an agent edit plus a reopen lost the reviewer's unsent comments. `packages/shared/annotate-draft.ts` (vendored to Pi; both servers route `/api/draft` and `/api/draft/document` through `createAnnotateDraftSession`) applies the #1590 pattern:

- **Single local file** (mode `annotate`, not a URL): the draft is also saved under `annotateFileDraftKey(<abs path>)`, reusing `review-draft.ts`'s dual-key logic with the content key as the "patch" key. Load prefers the content copy unless the path copy is strictly newer by `draftGeneration`; the path copy remembers every content key it was saved on (`patchKeys`, server-stamped, stripped from client bodies and from load responses); its tombstone guards both keys. Restored comments re-anchor by text and one whose text is gone shows the existing Unanchored chip and still exports, with no line label. Because block ids are positional, the highlighter's restore report lists under `moved` every comment whose stored `blockId` no longer holds its text (the block its highlight landed in, or `''` when the text is gone, which is also reported unanchored whether or not stored positions existed), and App writes that back (`applyRestoredAnchors`, `packages/editor/restoredAnchors.ts`), so export line labels name the lines the text is on now; an unchanged document reports nothing and exports byte-identically. Only rows that own a text highlight go through that restore (`annotationOwnsHighlight`, `packages/ui/utils/annotationOwnsHighlight.ts`: not diff-view comments with their `diff-block-N` ids, general comments, checkbox toggles or question answers); every re-apply caller (draft restore, `useLinkedDoc`'s back/re-open, per-document copies) filters with it, and the highlighter and `applyRestoredAnchors` skip the same rows, so a diff-view comment's `blockId` is never rewritten. Behavior change worth a release note: any restored comment the restore cannot paint now shows the Unanchored chip, not only one whose stored positions landed on other text, so comments with no stored positions (share-link imports, external/SSE comments, Edit Mode repaints) are chipped when their quote is not in the document. A save refused as stale (another session on the same file decided or saved ahead) answers `409 { ok: false, error, found, draftGeneration }`; `DraftTransport.save` may resolve `{ staleGeneration }` and the hook raises its counter above it and saves once more, so the reviewer's comments are not silently left unsaved.
- **Per-document copies:** every document a local-file or folder session holds comments on, other than the session's own root, is saved under that document's path key by the client hook `packages/editor/hooks/useDocumentDrafts.ts` (pure planning in `packages/editor/documentDrafts.ts`), and merged in the first time the document opens in a session (ids already held are skipped; a toast says how many came back). So a file's comments follow it between a folder session and a session on the file alone. These writes are generation-stamped by the server (one above whatever the key has seen), so a single-file session that later loads the copy resumes above it. A document is written only after its copy was read, and sent empty only when it was sent with content before. With per-document copies on, the session draft carries the ROOT document's comments even while another document is open (`composeSessionDraft` in `documentDrafts.ts`), plus every document the server keeps no copy for: one it refuses (`400`/`403`: outside the session's roots such as an Obsidian vault document, a symlink alias of the root, not a regular file) and a copy of the root opened through a self-link, so those stay crash-recoverable as before. Paths are canonicalized with `realpath` and must name an existing regular file (`canonicalDocumentPath`), so an alias shares its target's key.
- **Clearing:** a decision (`/api/feedback`, `/api/approve`, and the reviewer's Close `/api/exit`, which deleted the draft before this too) clears the session's keys and the path copy of every document the session wrote or restored from, then refuses session-draft saves (`409 { decided: true }`, even above the tombstone, so a second tab cannot put back comments that were just sent; never retried by the client) and document writes (`409`). A client DELETE (everything removed, banner dismissed) clears only the session draft's keys. The client-lease auto-dismiss keeps everything, as before. An agent close (`POST /api/host/close`, `closedBy: "agent"`) is the other exception: it KEEPS the session draft, its path copy and every document copy (`closeKeepingDraft`), so they come back when the file is reopened, even after an edit. Saves and document writes that arrive after it still land (the tab also flushes its pending debounced saves when the session-closed event arrives, `flushPendingSave` / `flushPendingWrite`), so a comment typed just before the close is kept; only the closed tab's DELETE is ignored. The closed-tab copy (`packages/ui/utils/agentClosed.ts`) says per case what brings the draft back: a local file or folder even after edits, a URL or agent message only unchanged, a live app by its address. The host status/close `unsentAnnotations` count is the session draft the session would restore plus every document copy it covered (`countUnsent`).
- **Scope:** URL, live-app and annotate-last sessions have no path key and no document copies. Drafts are crash recovery, not history, so `PLANNOTATOR_ANNOTATE_HISTORY` does not govern them. Known edges: two open sessions on the same file write the same path key and the last save wins; the key is the file's path only, so a raw-HTML session and a `--markdown` session on the same `.html` share one copy (raw-HTML pinpoints restored into the converted view, or the other way round, show as Unanchored); and the key follows the path's spelling after `realpath`, so a file reached through a hard link or a different mount is a different key.

Tests: `packages/server/annotate-draft.scenarios.ts` (run against both runtimes by `packages/server/annotate-draft.test.ts` and `apps/pi-extension/server/serverAnnotate-drafts.test.ts`), `packages/editor/documentDrafts.test.ts`, `packages/editor/restoredAnchors.test.ts`, and the DOM tests `packages/editor/App.documentDrafts.test.tsx`, `packages/editor/annotationDraftStaleRetry.test.tsx` (the 409 retry against real draft sessions), `packages/editor/App.restoreAcrossEdit.test.tsx` (line labels and chips after a restore across an edit), `packages/ui/components/Viewer.restoreMovedAnchors.test.tsx` and `packages/ui/hooks/useLinkedDoc.reapplyFilter.test.tsx`.

### Strict direct annotate results

Direct `plannotator annotate` invocations may add `--require-approval` and/or `--result-file <path>` only with `--gate --json`; both reject `--hook` and are not shared with OpenCode/Pi slash-command parsing. When neither strict option is present, single-target invocations keep the legacy plaintext, JSON, hook, and exit behavior unchanged, with one plaintext exception and three additive JSON fields. The plaintext exception: a gated approval that carries a note (**Approve with a note…** / **Approve with notes**, offered by every `--gate` session except `--hook`) prints the configured `approvedWithNotes` prompt, with its `File:` / `Folder:` / `URL:` / `Files:` context line (`annotateContextLine`), instead of `The user approved.`; a bare approval still prints that line byte for byte. First, a non-gated Done with nothing to send prints `{"decision":"annotated","feedback":"User reviewed the document and has no feedback.","nothingToSend":true,"annotationCount":0}` (`nothingToSend` appears only in that case and only on the non-strict `--json` record and the `opencode-annotate-last` record; decision values, the feedback text, plaintext, `--hook` output, the strict-gate record and every exit code are unchanged; the OpenCode CLI bridge, Amp and Droid read it; #1701). Second, `annotationCount` (the number of annotations the decision carried) rides every approved and annotated record of the non-strict `--json` output, `opencode-annotate-last`, and `opencode-review`; the OpenCode bridge names it in its decision heading, and the strict-gate record does not carry it. Third, `target` (the absolute file or folder path, URL, or a bundle's files, as the CLI resolved them) rides every non-strict `--json` record and `opencode-review` (the PR URL, patch file or directory), so the OpenCode bridge names the file the CLI actually opened (see "Decision targets"); plaintext, `--hook` and the strict-gate record do not carry it. Note for exact-string matchers: the non-strict `--json` DISMISSED record, which used to be exactly `{"decision":"dismissed"}`, now also carries `target` (`{"decision":"dismissed","target":"/abs/notes.md"}`); parse the JSON and read `decision` instead of comparing the line. Multi-token invocations go through the tolerant tiers described under "Tolerant argument resolution" above; several existing file paths open one review of all of them (strict gates included).

Strict decisions use one newline-terminated JSON record on stdout and, when requested, identical bytes in the result file. Exit codes follow the grep convention: approval exits `0`; with `--require-approval`, annotated and dismissed decisions are published before exiting `1` (negative human outcome); usage/startup/validation failures — bad flag combinations, strict flags outside `annotate --gate --json`, a missing `--result-file` parent, a pre-existing or dangling-symlink destination, and every annotate startup failure (missing path, unreachable URL, empty folder, ambiguous name, missing file, oversized file) — exit `2` (the gate itself was misconfigured or could not start). Those startup sites exit `1` as before for non-strict invocations, with one deliberate exception: the multi-token zero-resolve handoff is not a startup failure, so in plain non-strict mode it prints on stdout and exits `0` (under `--json`/`--hook` it stays stderr + exit `1`). Under a strict flag `1` is reserved for "the reviewer did not approve", so a typo'd path must never masquerade as a rejection. Post-decision publication failures (destination appears between validation and publish, hard links unavailable) also exit `2`: the result *file* was not published, so they present as environment errors — "the gate could not publish its result" — never as a reviewer outcome, and never as approval (still fail-closed, since only `0` means approved). The stdout decision record is written **before** result-file publication and is still emitted whenever the decision itself completed; only a stdout write failure leaves no record anywhere. Signal deaths keep `128+n`. Result paths resolve from the invocation working directory, require an existing parent and absent destination, and publish via a flushed/closed `0600` same-directory temporary file plus an atomic no-clobber hard link—never copy or overwrite fallback (the `0600` mode is a no-op on Windows, and the atomic link/rename is not followed by a parent-directory fsync, so publication is atomic but not crash-durable). Keep reviewed sources at stable project paths; unique result and diagnostic log files may use a narrow temporary directory. Explicit Close emits `dismissed`; missing results or process/browser failures are recovery cases, never approval.

### Abandoned strict gate sessions

Local direct structured gates (`--gate --json`, not `--hook`, not remote) advertise a client lease in `/api/plan` and serve `/api/annotate/client-lease` (SSE, `ANNOTATE_CLIENT_LEASE_STREAM_PATH`). Each open stream is one connected review surface; the server heartbeats every 5s and, once at least one client has connected, starts a 30s reconnect grace when the last one disconnects. A reconnect inside the grace continues the same review; expiry resolves the gate as the same `dismissed` decision an explicit Close produces, except that it keeps the saved annotation draft so an abandoned review can still be recovered. Approve, feedback, explicit exit, and server stop all cancel a pending expiry. Whichever producer settles the session first wins: every one of them (each connected surface and the expiry itself) goes through a single one-shot settlement, so a decision arriving after the session already resolved is rejected with `409` rather than deleting the draft and reporting success for an outcome the caller never received. Page lifecycle events are deliberately not used: `pagehide`/`beforeunload` also fire on reload and navigation, so they cannot distinguish abandonment from a reconnect. A session that never receives its first client never auto-dismisses, so browser-launch failures still need a caller-side timeout, and remote/shared sessions keep the capability off because tunnel disconnects would read as abandonment — as do `--tailscale`-published sessions, which force local mode but are reached through the serve proxy, whose disconnects would read the same way.

### Live app annotation (annotate-app)

Live local app annotation (spec: `adr/research/SPIKE-local-app-annotation-20260810.md`, section 7; phase 1 shipped it on the Bun path, phase 2 brought the Pi extension to parity). `plannotator annotate http://localhost:5173` probes the loopback URL (3s timeout, `accept: text/html`) and, when the probe returns an HTML page, starts server mode `"annotate-app"` instead of converting the page: a dedicated loopback reverse proxy mirrors the whole dev-server origin on its own `127.0.0.1` port, injects `<script src="/__plannotator__/bridge.js">` into every HTML response (streaming, exactly once per document), and passes WebSockets through so HMR keeps working. Every proxy DECISION — the injector state machine, loopback/Host/Origin predicates, CSP/X-Frame-Options policy, redirect rewrite, WS origin gate, bridge assembly, `liveAppDraftIdentity` — lives once in `packages/shared/live-proxy-core.ts`; `packages/server/live-proxy.ts` is the Bun transport over it and `packages/shared/live-proxy-node.ts` (vendored to Pi) is the `node:http` transport, whose WS passthrough replays the client's own handshake upstream over raw TCP and pipes the sockets byte-for-byte. The probe itself (timeout, `< 500` status gate, final-response redirect rule) and every user-facing live-mode message are shared too, in `packages/shared/live-probe.ts`. The editor renders the proxied app full-viewport in an unsandboxed iframe and drives the same pinpoint annotation experience the srcdoc surface provides. `--static` forces the classic conversion; `--app` forces live and errors loudly wherever it cannot apply: non-loopback, https, unreachable, non-HTML, off-origin-redirecting, and non-URL (file/folder) targets. "Loopback" means `localhost`, `::1`, or a LITERAL IPv4 address in 127.0.0.0/8 (`isLoopbackHostname` in `live-proxy-core.ts`, the single source of truth); DNS names like `127.0.0.1.evil.example` are not loopback. Live eligibility is judged on the probe's FINAL response after redirects: a target that 302s off its own loopback origin (auth portal, tunnel splash, another local port) falls back to the static pipeline instead of opening a dead live surface, while same-server redirects stay live-eligible.

The advertised `appUrl` is the proxy under its LOCALHOST spelling with the target URL's own path and query (`http://localhost:<B>/admin?tab=2`): localhost keeps the framed app same-site with the editor page and shares the dev app's host-only localhost cookies and storage, which a `127.0.0.1` spelling would not (Safari ITP would then block all cookies in the cross-site iframe). The proxy still BINDS the `127.0.0.1` literal; browsers that resolve localhost to `::1` first fall back to IPv4 on the refused loopback connect.

**Runtime coverage:** the feature ships on the Bun server + Claude Code CLI path AND on the Pi extension (`/plannotator-annotate http://localhost:5173` probes live-first through the shared `live-probe` module, recognizes `--app`/`--static` via `parseAnnotateArgs`'s `liveFlags` opt-in, and surfaces the probe-fallback notice through Pi's notifier; `apps/pi-extension/server/serverAnnotate.ts` serves the same `annotate-app` `/api/plan` payload over the vendored Node live proxy). The OpenCode slash-command parser is still untouched: its URL targets keep static conversion, and it deliberately does NOT opt into `liveFlags`, so a typo'd `--app` there stays a visible "File not found" instead of being silently swallowed. Pi has no `--tailscale`, so its hard-off matrix is remote-mode only (command-side notify + server throw + unconditional loopback bind).

**Session shape:** the surface opens with pinpoint **armed**, and it is comment-only; the full interaction contract it shares with raw-HTML sessions is documented once under "## Annotation System" below. Two things are specific to live mode: vim navigation is off outright (`vimModeEnabled={liveApp ? false : ...}`, `packages/editor/App.tsx:5484`), because its keyboard cursor writes into the app's own DOM, and the viewer's floating input-method switch is not offered. Text drag-selection commenting is NOT disabled: it stays live in both the armed and Interact states, exactly as on raw HTML. Links follow the same rule as every HTML surface: armed, a plain click (a tap on a phone) on one of the app's links navigates the app for real through the proxy, and Cmd/Ctrl-click (press-and-hold on a phone) pins the link for a comment (see "Links between local HTML documents" under Annotation System). Multi-page sessions are supported in one server session: annotations carry `pageUrl` (pathname + search, capped at 2048), restore filters to the current page, the export groups feedback under per-page headings while numbering stays global, and the bridge reports SPA navigations via a coalesced `page-change` message. Version history, durable submission records, URL sharing, portable HTML export, Obsidian/Bear save, and the annotate agent terminal are all off, exactly like URL sessions. Drafts, feedback, approve, gates, and the client lease work unchanged.

**Security posture:** the proxy binds `127.0.0.1` unconditionally and validates the `Host` header before touching upstream (DNS-rebinding blunting); `PLANNOTATOR_URL_HOST` is never applied to the proxy origin. WebSocket upgrades whose browser `Origin` header is present and does not name the proxy itself are refused before any upstream contact, so a hostile page's cross-site WS connect is never laundered into the origin-less shape dev servers trust as a non-browser client (Vite CVE-2025-24010 class); header-less non-browser clients pass. App CSP on HTML responses is dropped and replaced with a `frame-ancestors` policy listing exactly the editor origins (amending an arbitrary CSP for an injected script is unpredictable; dev servers rarely ship one; `<meta http-equiv>` CSP is a documented non-goal); `X-Frame-Options` is stripped only on those same HTML responses, so non-HTML responses keep whatever framing protection the app shipped. `/__plannotator__/bridge.js` embeds the per-session token, so its delivery refuses `Sec-Fetch-Site` values other than `same-origin`/`none` (defense in depth against off-origin `<script src>` token reads; header-less clients pass). Upstream redirect `Location`s are re-anchored onto the proxy by loopback-host-plus-port equivalence, never by string prefix. The injected bridge authenticates both message directions with a per-session token plus origin checks, and posts each outbound message once per listed editor origin (the browser delivers only the one matching the parent document, so an editor opened at `127.0.0.1` works too); the parent side keeps every existing size cap. Remote mode is a hard-off with three independent layers and no override env var: the CLI exits with a startup failure suggesting `--static` (on Pi, the command notifies with the same shared message), `startAnnotateServer` throws (both the Bun server and the Pi mirror), and neither transport's proxy bind ever follows `PLANNOTATOR_REMOTE` — both bind the `127.0.0.1` literal unconditionally, asserted at source level by their test suites. `--tailscale` sessions are hard-off the same way (CLI startup failure + server throw, keyed on `tailnetPublished`): the annotate server stays loopback-bound but is published across the tailnet through the serve proxy, and a live proxy would relay the user's authenticated dev app to every tailnet peer — the same reasoning that defaults the annotate agent terminal off for tailnet-published sessions. Release-note-worthy behavior change: under `PLANNOTATOR_REMOTE`, `plannotator annotate http://localhost:...` previously converted the page silently and now exits with that startup failure asking for `--static`.

**Live restore resilience:** a `find-and-mark` that resolves nothing in live mode keeps its record, seeded with unresolved placeholder targets from the durable anchor/text params, so the mutation-driven reconcile re-acquires the pin once a lazy route or data-dependent tree finishes rendering. Srcdoc restores keep the old fail-closed drop (a static document would never re-resolve).

**Known limitations (documented, not bugs):** hardcoded absolute origins in the app, origin-pinned CORS to secondary APIs, and OAuth `redirect_uri` flows land outside the proxy; frame-busting apps break the wrapper; content-encoded HTML that survives the encoding strip renders without the bridge; cross-page annotation clicks do not navigate; a redirect to a DIFFERENT loopback service (another port) is passed through un-rewritten and the iframe leaves the proxy, which is why the probe refuses such targets up front. Manual smoke loop: `scripts/live-annotate-smoke.sh` (not CI).

## Plannotator Inbox

One long-lived local server per machine. Agents leave messages, `:::question` blocks, files and guided reviews there for the person, and the person answers when they can. Nothing holds an agent session open on it. A reply wakes the session that asked, through the Claude Code, Pi or OpenCode connection, or reaches any other agent through `wait_for_reply`. The window's design of record and the owner's decisions are kept privately (not in this repo); this section carries what a build here needs from them. Not built: the Mac notification helper (only a spike so far). Where it is documented for users and agents: `plannotator --help` (`apps/hook/server/cli.ts`) and the agent guide `plannotator inbox --help` (`apps/hook/server/inbox-help.ts`, see "The command"), the `## plannotator inbox` section of the `plannotator` skill (`apps/skills/core/plannotator/SKILL.md`; deliberately short: the usage lines, when to use the Inbox, tool-or-MCP, and a pointer to read `plannotator inbox --help` first, so details live in the guide, not the skill), and the marketing reference page `apps/marketing/src/content/docs/reference/inbox.md` (`/docs/reference/inbox/`). A change to the command, the MCP tool list or the knob updates the guide and the reference page, and the skill only when its usage lines or its when-to-use rule change.

**The command** (`apps/hook/server/inbox-command.ts`, usage in `cli.ts`, the agent guide in `inbox-help.ts`).
- `plannotator inbox` starts the Inbox in the foreground and opens it in the browser, or opens the running one.
- `plannotator inbox --background` starts it detached (its own session, output in `inbox/inbox.log`), prints the URL and exits 0. It never opens a browser, so an on-demand start never pops a tab mid-work.
- `plannotator inbox --no-open` runs it here without a browser.
- `--tailscale` (with any of the three) also publishes it over the tailnet for this run (see "Over your tailnet"); with an Inbox already running, the command asks it to publish through the token-guarded `POST /api/inbox/control/tailscale`. Stdout stays the local URL alone; the tailnet URL (with a QR on a TTY) or the reason it is not published goes to stderr, and the exit code never depends on Tailscale. A restart to update of a run published only by the flag passes `--tailscale` on.
- `plannotator inbox mcp` is the stdio MCP entry (`apps/hook/server/inbox-mcp-shim.ts`), a thin JSON-RPC proxy:
  - It POSTs each stdin message to the Inbox's `/mcp` and writes every answer to stdout.
  - It re-reads `inbox/inbox.json` on every message and starts a stopped Inbox through the `--background` path (no tab).
  - When the agent leaves them out, it fills `project_path` (its working folder, or `PLANNOTATOR_CWD`) and `agent_session`.
  - The session is the agent host's own when the shim runs inside one (`inboxHostSessionFromEnv`): a well-formed `PLANNOTATOR_SESSION_TAG` (`<host>:<id>`, host `claude-code`, `pi` or `opencode`, id `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`; anything else is ignored), else Pi's own `PI_SESSION_ID` (Pi sets it on each bash tool call). The host session is adopted only when the agent named no `agent_host` or that same host; an agent that names another host gets the shim's own `ses_` id, so a reply to it never wakes the session. On `send_message` and `submit_guide` it then also fills `agent_host` and `agent_name` (`Claude Code`, `Pi`, `OpenCode`; the name only when the agent gave none), so the author is byte for byte what that host's `plannotator_inbox` tool writes. A script or command a Claude Code or Pi session runs therefore sends as that session: the same default thread, `asked_by: "me"` and `wait_for_reply` see the tool's threads, and the person's reply wakes the session through its connection (`pendingReplies` matches on `author.session`). An `agent_session` the agent passes always wins. A tag inherited by a long-lived process started from an agent's shell (tmux, nohup) keeps naming that session; pass `agent_session` explicitly to override.
  - Otherwise it is one `ses_` id per shim process, so an MCP client's identity ends with its MCP server process; a client that wants its threads across restarts passes `agent_session` itself. Replies to a session that ended are never handed to another session.
  - OpenCode exports no session variable to the commands it runs (OpenCode 2's `shell.create.before` hook carries no session id; OpenCode 1's `shell.env` does but OpenCode 1 has no wake), so there a command still gets a fresh id.
- Any other argument exits 1 with a usage line.
- Starts are serialized by `inbox/start.lock` (mkdir, stale after 30 s), so two agents that find the Inbox stopped at once start one. The detached child runs under its starter's lock (`PLANNOTATOR_INBOX_LOCK_HELD`, internal, scrubbed at start).
- The Inbox never registers in `sessions/` and never arms auto-update, so it never holds an update back.
- `plannotator inbox --help` (and `inbox mcp --help`) prints the **agent guide**, a markdown document an agent with no skill can read once to use the Inbox: what it is, when to use it, how to reach it, one section per MCP tool, thread routing, where replies go, the question syntax, connecting other agents, commands and flags, data and removal. `formatInboxHelp` in `apps/hook/server/inbox-help.ts` builds it from the code it describes: the tool list `INBOX_MCP_TOOLS` (its per-tool `TOOL_GUIDE` is typed by it, so a new tool does not compile without a section), `QUESTION_AUTHORING_GUIDE` verbatim, `INBOX_SECTIONS`, `INBOX_TOOL_NAME` / `INBOX_FILLED_ARGUMENTS` / `INBOX_TOOL_DEFAULTS`, the window's per-harness setup (`HARNESSES` / `harnessPanel`, `packages/inbox/harnesses.ts`, reached through the `@plannotator/inbox/harnesses` export) and the commands block `INBOX_COMMAND_USAGE` (`cli.ts`, also the `SUBCOMMAND_HELP.inbox` entry the skill freshness test reads). It names this CLI's absolute command (`selfCommand()`: the binary, or bun plus the entry script) and the resolved data dir. `index.ts` prints it for `helpSubcommand === "inbox"`; the top-level help points agents at it. `inbox-help.test.ts` keeps it true: every tool a real Inbox serves has its section and every argument it names is in that tool's served schema, the question guide is byte for byte, every harness is listed with its setup line, every flag and subcommand the parser in `inbox-command.ts` accepts appears, and the CLI as a process prints it (exit 0, empty stderr, no Inbox started). A new tool, tool argument, harness or flag updates the guide.

**Local only by default; each wider path is a switch.**
- It always binds `127.0.0.1` and ignores `PLANNOTATOR_REMOTE` and `PLANNOTATOR_PORT`, because it holds tokens and everything agents sent. To reach the window from your other devices, turn on "Over your tailnet" (below).
- Port: the last one (from the registry) comes first, so the browser's notification permission holds. When something else holds that port, the Inbox takes a random port and shows a one-time notice (stderr and the list model's `notice`). It never uses 19432, nor 8443 (Phones' tailnet port; the window's own tailnet mapping uses the Inbox's port, so the two never collide).
- "Over your tailnet" (off by default; `packages/server/inbox-tailscale.ts`, pure checks in `packages/shared/inbox/tailnet.ts`): `plannotator inbox --tailscale` (this run), `PLANNOTATOR_INBOX_TAILSCALE`, or config.json `inboxTailscale` (Settings' switch) publishes the window with `tailscale serve --bg --https=<the Inbox's port> http://127.0.0.1:<proxy port>`, serve and never funnel.
  - The socket decides, as for Phones: serve picks its handler by TLS SNI and passes the client's own Host through (`r.Out.Host = r.In.Host`, `ipn/ipnlocal/serve.go`), so a peer could claim `Host: 127.0.0.1:<port>`. The mapping therefore points at a second loopback listener that only serve is pointed at; the window's port is unchanged and never learns the tailnet name. That listener hands requests to the window's handler marked `via: "tailnet"`.
  - Owner only: every request on that listener must carry `Tailscale-User-Login` equal to the login that owns this machine (`tailscale status --json`: `Self.UserID` -> `User[id].LoginName`, read at each publish; `parseTailscaleSelfIdentity`) or one in config.json `inboxTailscaleAllow`, compared case-insensitively after RFC 2047 Q-decoding (`decodeTailscaleHeaderValue`; serve Q-encodes non-ASCII logins). Serve deletes incoming `Tailscale-User-*`, `Tailscale-Funnel-Request` and `Tailscale-Headers-Info` before setting its own, so a client cannot forge them through serve. A tagged peer gets no identity headers (`403 tailnet_identity_required`), another login `403 tailnet_identity_refused`, a funnel request (`Tailscale-Funnel-Request`) `403 tailnet_funnel_refused`. A tagged machine has no owner: publishing is refused, with the reason, until `inboxTailscaleAllow` names someone.
  - Also on that listener: Host must be the served MagicDNS name with the HTTPS port (`403 forbidden_host`), and `Sec-Fetch-Site: cross-site` / `same-site` is refused (`403 cross_site`) except a top-level GET navigation to `/` and GETs of `/api/html-assets/` (an attached page's sandboxed srcdoc frame is cross-site by construction): the identity is ambient, like a cookie, and every `*.ts.net` machine of the tailnet is same-site.
  - Through the tailnet (`via: "tailnet"`, whatever Host is claimed): `/mcp`, `/api/inbox/bridge/*`, `/api/inbox/control/*` and the device door answer `403 local_only`; so do pairing a phone, Phones' tailnet and Wi-Fi switches, "Open in" (`/api/inbox/open-in` and its app list: launching an app changes this computer), and turning the window's tailnet switch on (off is allowed). Read routes (the list, threads, settings, attachments and their new-tab page, guides, a message's images `GET /api/inbox/messages/:id/image`) answer the owner as on loopback, behind the listener's checks. Every non-GET request runs `isSameOriginOrNoOrigin` (the page's origin is `https://<MagicDNS name>:<port>`), then the `serverSession` guard. `/mcp` also refuses any non-loopback Host on the window's port, so `PLANNOTATOR_ALLOWED_HOSTS` cannot widen it.
  - Lifecycle: the mapping is recorded in `inbox.json` (`tailscale.https_port`, `proxy_port`) BEFORE it is made, so a crash always leaves a record. Every start first removes a recorded mapping whose proxy port is not this run's (a dead ephemeral port any later local server could bind; see "The crash window" under "Tailnet sessions"), switch on or off, then publishes when on. A take-down that fails keeps the record (never forgotten, retried at the next start and by `uninstall --purge`) and nothing is published over it that run. Taken down at every clean stop (quit, SIGINT/SIGTERM, the stop route, a restart to update before the new binary starts) and by `uninstall --purge` (`takeDownInboxTailscale`, by the ports `inbox.json` kept). While a mapping exists an `exit` handler and a SIGHUP route (the Inbox's clean stop, then exit 129) are installed, never otherwise; so while published, `nohup plannotator inbox --tailscale &` ends with the terminal (start it with `--background` instead). A mapping on the port that the Inbox did not make is never replaced or taken down: Settings says how to clear it. A take-down that fails keeps the switch on (`409 tailscale_unavailable`) and the ports in `inbox.json`.
  - A hand-made mapping onto the window's own port (`tailscale serve --https=<P> http://127.0.0.1:<P>`, the old workaround) hands the tailnet the whole Inbox, `/mcp` included, since serve passes a peer's Host through. The window's port therefore refuses (`403 local_only`) every request carrying `Tailscale-Headers-Info`, `Tailscale-User-Login` or a non-loopback `X-Forwarded-For` (#1867: a local reverse proxy like nginx/caddy/portless sending loopback addresses in X-Forwarded-For is allowed; serve always sets X-Forwarded-For with the peer's tailnet/remote IP). The first such request reads `serve status` and names the mapping (`tailscale.exposed: [{ https_port, target }]`, from `serveStatusRoutes` + `serveTargetIsLoopbackPort`, web handlers and TCP forwards); each publish reads it too. Stderr and Settings say plainly that it exposes the whole Inbox and its agent tools to the tailnet, and Settings offers "Replace it with the owner-only address" (`POST /api/inbox/settings` `{ tailscale: { on: true, replace_exposed: true } }`: removes each serve port whose route still lands on the window's port, then publishes). Without that request the switch never takes it over: publishing on its port is refused with the same words. A raw TCP forward carries no headers, so only the serve-status read catches it.
  - What a login let in can do: everything the window does, and a reply, and above all a New message, becomes a turn in a live agent session on this machine. So any allowed login, or anyone holding the owner's unlocked, signed-in phone, can drive agents that run commands here. Let in only logins you would let sit at this computer.
  - Never fatal: Tailscale missing, stopped or signed out leaves the Inbox running on loopback; the reason goes to Settings (`tailscale.error`), `inbox.json` and stderr.
  - The window page through the tailnet (#2032, `tailnetWindowPage` in `inbox.ts`): `/` is served through the shared `packages/shared/app-html.ts` helper (brotli q5 / gzip 6 on `Accept-Encoding`, `Vary: Accept-Encoding`, brotli prewarmed when the tailnet listener opens; 21.8 MB → 5.1 MB br, 5.8 MB gzip), with `Cache-Control: private, no-cache` and a weak ETag of the page (`304` on `If-None-Match`), after the listener's checks. The window's loopback port is unchanged (uncompressed, `no-store`), and the data routes stay `no-store`.
  - Settings' "Over your tailnet" block: the switch (saved to config.json and applied at once; locked while the env var decides; shows on with the error while publishing fails, so one click turns it off), the address, who may open it, "Keep it on at every start" for a run published by the flag, and the exposure warning with "Replace it with the owner-only address". Turning it off through the tailnet answers first and closes the listener a moment later. A page opened over the tailnet (`via: "tailnet"` on `GET /api/inbox/settings`) cannot turn it on.
  - Notifications are per origin, so the tailnet address is a separate permission; the one-time line says "moved" only for a port change under the same name (both loopback counts as the same), and a different name gets the plain ask.
- A paired phone reaches it only through the device door (see "Phones"), and only over a path the person switched on in Settings:
  - "Reach from my tailnet" (off by default): a second loopback listener that serves the device door and nothing else, published with `tailscale serve --bg --https=8443 http://127.0.0.1:<door port>`, serve and never funnel. The window's port is never published: `tailscale serve` passes the client's own Host header through, so only the socket can keep tailnet requests on the door. The switch is kept in `inbox.json` as `tailnet: { https_port: 8443, door_port }`; each start publishes again. The listener and the mapping go when the switch goes off and at every clean stop (quit, the stop route, and a restart to update, before it starts the new binary). A mapping a crash left (kill -9) is re-pointed by the next start before anything else, or taken down when it cannot publish; SIGHUP runs the clean stop while a mapping exists (installed only then, as `--tailscale` does, so `nohup` keeps its meaning otherwise); `uninstall --purge` takes a leftover down by `door_port`. A take-down that fails changes nothing (switching off answers `409 tailnet_unavailable`, `door_port` is kept). The window's port never adds the tailnet name to its Host allowlist. A mapping on 8443 that the Inbox did not make (its target is not this run's or the last run's door listener) is never overwritten or taken down: the switch stays off and Settings says so.
  - "Reach from this Wi-Fi" (off by default; `packages/server/inbox-lan.ts`, contract section 3): a TLS listener on every interface (`0.0.0.0`) that serves the same door-only handler as the tailnet's listener, on a port chosen free the first time and kept in `inbox.json` as `lan: { port, on }` (kept when switched off, so on again reuses it). It stays on all interfaces, not the Wi-Fi address alone: a socket bound to one address dies with a new DHCP lease, and `Bun.serve` cannot bind to an interface. The certificate is self-signed ECDSA P-256 (`CN=Plannotator Inbox`, never rotated), made with two `openssl` child processes the first time and kept in `inbox/tls/` (files 0600 in a 0700 folder); its SHA-256 (of the DER) rides the QR as `fp` and the phone pins it. A `_plannotator-inbox._tcp` Bonjour record (instance `computer.name`, TXT `v=1`, `fp=`) goes out through `dns-sd -R` (macOS) or `avahi-publish -s` (Linux) as a child process under `sh`, which ends the publisher when its stdin closes, so a kill -9 leaves no record; with neither, the listener still answers at the QR's address and Settings says phones will not list it. Pairing over the Wi-Fi is by the QR's secret only: the LAN listener's `pair` refuses six digits with `400 code_not_accepted_here` (a Bonjour record anyone on the Wi-Fi can publish must never become the pin), while the window's port and the tailnet's listener take both; the record's `fp` only lets a phone already paired by QR follow the computer to a new address. The QR's `lan` is the first private IPv4 address that is not loopback, link-local or Tailscale's, read when the offer is made. Off closes the listener and the record and keeps the port with `on: false`; a listener that cannot open at start shows the switch on with the reason, and off works; a clean stop closes both and keeps the switch, and the next start opens the same port with the same certificate. `openssl` missing answers `409 lan_unavailable` and the switch stays off.
  - The relay (R1; `packages/server/inbox-relay.ts`, `apps/relay`, contract section 4): not a listener. The Inbox makes an outbound mailbox at the first pairing and holds one WebSocket to it while a phone is paired; the relay holds only hashes, each phone's relay switch, its APNs token and envelopes it cannot open. Through it (R2) a phone reads and answers the Inbox from anywhere: store lines down, commands up, each sealed under keys made at pairing.

**Connecting the agents on this computer** (`packages/server/inbox-agents.ts`; approved design record "inbox-agent-awareness", not in this repo; decisions 1, 2, 3, 7).
- When: a person's `plannotator inbox` (with or without `--no-open`), never `--background`, the shim, a connection that starts a stopped Inbox, or the window's Restart (`spawnDetachedInbox` marks those `PLANNOTATOR_INBOX_DETACHED=1`, scrubbed at start; `PLANNOTATOR_INBOX_LOCK_HELD=1` alone counts as detached too, because an Inbox of 0.28.17 or older spawns its Restart into an updated binary, and every other detached start, with only that marker). Starting the Inbox: `inbox.connectAgents()` once it listens, off the request path, its lines on stderr when done. An Inbox already running (an agent started it): the command opens the window, then `POST /api/inbox/control/connect` (connection-route guards: loopback Host, no Origin, the registry token; an older Inbox answers 404 and nothing happens); the step then runs in that Inbox's process, with the environment (PATH, home) the agent started it with. `PLANNOTATOR_INBOX_CONNECT=0` in either environment skips it. One run at a time (`connectAgents` is single-flight); stdout is unchanged.
- What: every agent found (the install script's rules: its command on PATH, or its folder; Cursor also by `cursor` / `cursor-agent`, Kiro by `kiro-cli`, Codex by `$CODEX_HOME` holding config, a relative one resolved against the working folder as Codex does) with no record in `inbox/agents.json` gets a `plannotator-inbox` MCP server running `<selfCommand> inbox mcp`, through its own `mcp add` where it has one (Codex `codex mcp add … --`, Gemini `gemini mcp add -s user` (`$GEMINI_CLI_HOME` honored), Windsurf/Devin `devin mcp add -s user … --`, Amp, Pi 0.99+ without the extension `pi mcp add`), each only after its `--version` line has that CLI's own shape (`VERSION_SHAPES`: a program that merely shares the name, cln's `pi`, amp.rs, is never handed it; a build older than its `mcp add` is left to the person: Pi before 0.99, which would read the words as a chat prompt, Codex CLI before 0.35.0 and Gemini CLI before 0.1.19), else one key in a plain-JSON file (`mcpServers` in `~/.cursor/mcp.json`, `~/.kiro/settings/mcp.json`, the Claude desktop app's `claude_desktop_config.json`; created when missing). JSON edits are lossless (`packages/server/json-edit.ts`: only that member's text is inserted or cut, in the file's own style and dominant line ending, BOM kept; a file that is not strict JSON or has a duplicate key on the path is refused with the reason). Add then remove gives the file back byte for byte: the record keeps the add's exact text change (`undo: { before, after }` on the agent's record in `agents.json`), and removal puts `before` back while `after` is still in the file untouched, so an empty file stays empty, a final newline or its absence stays, and a container Plannotator made goes; a file Plannotator created (`created`) is deleted once only the empty containers are left; an entry the person edited is cut alone; written at a symlink's target, atomic, a no-op when nothing changes (agent-files.ts). Codex's config.toml is read with `Bun.TOML.parse` (every TOML form). Pi with Plannotator's extension (Pi's `settings.json` `packages`) and OpenCode with its plugin (the global `opencode.json(c)` `plugin`, or `plugins` strings or `{ package }`): `inboxTool.<host> = true` in config.json, unless config.json already decides it (false is recorded `off`) or `PLANNOTATOR_INBOX_TOOL` does (nothing written). Claude Code: nothing (said "already on" when the plugin is enabled). Left to the person (`manual`): Codex or Gemini found without its CLI, Pi before 0.99, a CLI whose version line is not its own, Cline (its `mcp add` is not verified), OpenCode without the plugin. Editors (VS Code, Zed, JetBrains, Goose) are never written. The agent CLIs run with no stdin in their own process group; the time limit kills the group, and the answer comes at exit even if a grandchild keeps the output open.
- Rules: an agent with a record is never added again by itself (turned off, removed outside Plannotator: `removed_outside_at`, checked read-only each run; foreign). An entry is ours when it runs exactly this CLI's command or the one its record says Plannotator wrote; for "already connected", also any `plannotator` binary or checkout running `inbox mcp` (`isPlannotatorInboxCommand`: the program's name is exactly `plannotator`, not `my-plannotator-proxy`). Anything else named `plannotator-inbox` is never replaced and is recorded `foreign`. A refused file or a failing or hung `mcp add` is tried again next run and said again only when its reason changes (`failures` in agents.json). Limits: 10 s per agent, 30 s in all (agents still going are `unfinished`). A test run (PLANNOTATOR_TEST_SANDBOX) whose home is not a scratch folder connects nothing (`agentHomeAllowed`).
- Said once: the first run "Connected Codex, Gemini CLI and Cursor to the Inbox (Claude Code was already on)." plus "Agents use it from their next session. PLANNOTATOR_INBOX_CONNECT=0 skips this step; plannotator uninstall removes what it added."; a later run "Connected Amp to the Inbox (new on this computer)."; failures and foreign entries name the file and reason (`formatConnectReport`); an agent only a person can connect (no CLI on PATH, Pi before 0.99, Cline) is named with its reason ("Pi needs connecting by hand: …"), once per reason (`manual_said` in `agents.json`, `manual_why` on the report); time limits are said as they are (`formatSeconds`: "1.5 s"). The run's report is kept in `agents.json` (`last_report`, `seen: false` when it has news) and served at `GET /api/inbox/agents` (local only; records with `~` paths). Uninstall removes only entries Plannotator recorded as `added` that still run the command it wrote; with no record at all (`agents.json` lost) nothing is removed, and an entry that runs exactly the binary being uninstalled is named in a warning with how to remove it, since the person may have added it by hand; one the person added (`found`) is left.
- Tests: `packages/server/inbox-agents.test.ts` (fake agent CLIs on a scratch PATH and HOME, `tests/helpers/fake-agents.ts`; the real CLIs are never run), `packages/server/inbox-connect-route.test.ts`, `apps/hook/server/inbox-connect-cli.test.ts` (the CLI as processes), the uninstall block in `packages/server/uninstall.test.ts`. The guard test also fails on a path from the real home to an agent's folder and on connecting agents with no agent environment (`agentHomeFindings`, `agentConnectFindings`).

**The note in each agent's instructions** (`packages/server/inbox-agent-notes.ts`; decision 5).
- Written only with the person's yes: the note dialog's Add, a Settings → Agents switch, or `plannotator inbox --notes <ids>` (the install prompt runs it with only the agents the person agreed to in chat; it starts nothing, refuses an agent not found on this computer, and marks the question answered only when a note is there now). Never by a start, the shim or a connection. `PLANNOTATOR_INBOX_NOTES=0` hides the offer, refuses new notes, and lists a note row only for a note already written, so it can be switched off; notes already written stay until switched off or uninstalled.
- Where: Claude Code `~/.claude/rules/plannotator-inbox.md` (a file Plannotator owns; `CLAUDE_CONFIG_DIR`), Codex `AGENTS.override.md` when it exists else `AGENTS.md` (`CODEX_HOME`; created only without an override), OpenCode `$OPENCODE_CONFIG_DIR` / `$XDG_CONFIG_HOME/opencode/AGENTS.md` ONLY when it exists (creating it would stop OpenCode 1 reading `~/.claude/CLAUDE.md`; state `unavailable` otherwise), Pi the first that exists of `AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md`, `CLAUDE.MD` in `PI_CODING_AGENT_DIR` (Pi reads only one; `AGENTS.md` created only when none does), Gemini CLI `~/.gemini/<context.fileName>` (default `GEMINI.md`). Copilot CLI and Mistral Vibe are not offered (their MCP connection is out of scope; Copilot's file is not verified). Kiro and Cursor have no file.
- Edits work on the file's own text: every byte outside the block stays, new lines take the file's dominant line ending (more CRLF than lone LF: CRLF), a UTF-8 BOM is kept, and a re-add that finds the block unchanged never rewrites the file. Records hold the RESOLVED path (a symlinked file, or a symlinked folder such as `~/.claude` -> dotfiles), so switching off and uninstall find the very file a note created. A file two agents share (Pi's `AGENTS.md` a link to Codex's) holds one section, recorded for both; turning one off keeps it while the other is on (`shared_with` on the status, said on the card and in Settings).
- The block: `INBOX_NOTE_START` (`<!-- plannotator-inbox:start v1 · added by Plannotator. Remove it in the Inbox's Settings or with \`plannotator uninstall\` -->`), the DESIGN.md §2.3 note, `<!-- plannotator-inbox:end -->`, appended at the END after one blank line. The file's last byte decides how the block ends, so removal gives the file back byte for byte with or without the record: a file that ended with a line break gets the block plus one; a file that ended without (`abc`) gets the two line breaks before the block and none after, so the block is its last bytes; whitespace-only text is kept, with the block after it (an empty file, or one ending in a line break, gets the block plus a line break; one like " " that does not end in a line break gets one line break first, so the start marker begins its own line, and none after the block). Exactly one start before exactly one end is ours; none appends; anything else is `damaged` and nothing is written. `inbox/agent-notes.json` keeps each block's SHA-256: a newer version is written only over an untouched block, a block the person edited (`edited`) is never overwritten, and switching it off removes it as they left it (plus the blank line the writer added). A file Plannotator created is deleted when the note was all it held; a file the person had never is. Line endings and mode kept, symlinks written at their target, atomic, no write when nothing changes (agent-files.ts).
- Switching a note off removes the block from the file its record names AND from every file that agent could read it in, when they differ (Codex: the note went into `AGENTS.md`, then `AGENTS.override.md` appeared). Until then the status reads the recorded file, so the switch shows on with a line naming where the note is (`noteStatus`).
- Plain `uninstall` and `--purge` remove every recorded note, then any of the known files that still holds the markers (`planInboxNoteRemoval`; Claude Code's own rules file is deleted when the note is all it holds, record or not); `--dry-run` lists them ("you edited it" when so), and a damaged section is named and left. `--purge` removes `inbox/agent-notes.json` with `inbox/`.
- `plannotator inbox --help` lists every note file on this computer and how `--notes` adds it ("A note in each agent's instructions").

**The agent-note dialog and Settings → Agents** (`packages/inbox/components/AgentNoteDialog.tsx`, `AgentsSettings.tsx`, pure helpers `packages/inbox/agents.ts`; read from `GET /api/inbox/agents`, local only). The approved design record "inbox-agent-note-dialog" (not in this repo; Checklist, with the band at the top) replaced the first-open card above the list and under "No agent has written yet", and amended decision 5: the note is asked once PER AGENT.
- Who: every note candidate (found, reaching the Inbox, no note yet, a file to put it in, not failed by the last run; `noteCandidates`) not in `notes_asked` (`noteQuestionRows`; Claude Code last). None with `PLANNOTATOR_INBOX_NOTES=0`. Nothing to ask: no dialog, even with unseen news; the terminal said it and Settings → Agents shows the state.
- When (`App.tsx`): decided ONCE per page load, after the first read of the agents settles (a run that opened the window has finished connecting, plus the read 2.5 s after load), once the list has loaded, never while an update dialog is open, a restart runs, a reply is being typed, or Settings is open. After the sound dialog and never on a load that showed it: it waits for the sound claim (when due) and stands down for the load when the sound dialog showed. The rows and the band are fixed when it opens. Through the tailnet the agents are not served, so never there. While it is open the notification ask line, the toast and E / Z stand down, as for the sound dialog.
- What: the sound dialog's `Modal` (no entrance motion; Escape and the backdrop are Not now; Tab stays inside; the primary has the first focus), `min(720px, 100vw - 32px)`, the body scrolls and the footer stays. Top band (role status), only with unseen news (`cardReport`): "Connected Codex and Gemini CLI to the Inbox." ("(new on this computer)" after the first run), "Pi needs connecting by hand: Settings → Agents" (from `manual_why`), and, kept from the card, a connect failure ("Couldn't connect Amp: …. Settings → Agents") and a foreign entry. Title "Tell your agents about the Inbox" ("Add the note to Codex?" for one agent), one sentence. One table: checkbox (none for one agent), mark, the name (`dir="auto"`, cut at the end, full in a tooltip while cut) over the path (one line, cut in the middle: the folders shrink, the file name's end shows; each folder its own `<bdi>`; whole in the DOM and in a tooltip while cut; wrapped after each `/` on a phone), a "New file" / "Adds to end" pill; Pi's one-file line, a shared file, a link target. Every row starts ticked (Claude Code too). The primary names who it adds to ("Add to Codex, Gemini CLI and Claude Code", "Add to N agents" for four or more); nothing ticked reads "Don't add a note" (Not now hidden) and is answered like Not now; never disabled, never an error. Show the note (the exact block, 150 px scrolling). Footer "Change it later in Settings → Agents.". Add: the results in the same rows (Added / Created / Not added with the reason and Try again inline; a request that fails reads as Not added with its error; an agent CLI's own message in parentheses is unwrapped so a line never ends "))", `tidyReason`), title "Added the note to …" or "The note was not added", no band, a polite live region, and focus on Done (also after a Try again that worked). Each checkbox is named by its whole row, so the path is read once. The band's Settings → Agents link answers Not now and opens Settings.
- The answer is `POST /api/inbox/agents/notes { add, asked, seen }`: `asked` the agents the dialog showed, `seen` the band showed the report. An agent whose add failed stays unasked (asked again); everything else shown is recorded in config.json `inboxAgentNotes.asked`. A body without `asked` (an older window) counts the current candidates plus `add`. Settings → Agents' note switch turned on (`POST /api/inbox/agents { note: true }`) records that agent as asked too.
- Settings → Agents: one group per agent found (and always Claude Code, Pi and OpenCode, whose Inbox tool switch, `tool`, stays in reach found or not) with Reaches the Inbox (the tool switch, or the `plannotator-inbox` entry: on adds it whatever the record says, off removes Plannotator's entry and records `off`), Reminder at session start (Claude Code, Pi, OpenCode; config.json `inboxReminder`; "Needs the tool" while the tool is off), Note in its instructions (path, state, Show, the edited / trap / damaged lines); `PLANNOTATOR_INBOX_TOOL` locks the tool and reminder switches with a line saying so; agents not found fold behind "Not found on this computer", the harness picker (editors included). Every change says "<Agent>'s next session". `POST /api/inbox/agents { agent, reach?, tool?, reminder?, note? }` (same-origin and `serverSession` guards, local only) answers the model with `error` when a switch was refused; a second click while that agent's change saves is ignored. Reading the model runs no agent CLI (no `--version` probe; that happens only before a write). A test that starts an Inbox without its own `agentEnvironment` gets an empty scratch one (no PATH, a home inside its data dir).
- Tests: `packages/server/inbox-agent-notes.test.ts`, `packages/server/inbox-agents-settings.test.ts` (asked once per agent, a failed add asked again, the 0.28.18 config read), `packages/inbox/agents.test.ts`, the DOM tests `packages/inbox/agentNoteDialog.test.tsx` and `agentsSettings.test.tsx`, `tests/e2e/inbox-agents.spec.ts` (compiled binary: `--background` connects nothing, a person's run connects; the sound dialog shows first and the note dialog not on that load; the next load asks about Codex, Gemini CLI and Claude Code; Add writes the ticked notes; never asked again; a later run connects Pi and Amp and the dialog asks about Pi alone; a run that connects only Cursor opens no dialog; a stress run with every note agent and long, non-Latin paths; screenshots in `/tmp/agent-note-dialog-built/`).

**Registry** `${dataDir}/inbox/inbox.json` (`packages/shared/inbox/registry.ts`).
- Shape: `{ v, pid, port, url, version, token, serverSession, startedAt, tailnet?, lan?, tailscale? }` (`tailnet: { https_port, door_port }` while "Reach from my tailnet" is on, `lan: { port, on }` once "Reach from this Wi-Fi" was switched on, `tailscale: { url, error, https_port?, proxy_port? }` while "Over your tailnet" is on, the ports naming the mapping this Inbox made), mode 0600, written atomically at every start and kept after exit. "Found" means the file exists. The token rotates every start.
- Running: `GET /api/inbox/health` on that port answers with this entry's `serverSession`.
- Stopped: a dead pid with no answer, a port answering for another Inbox, or a live pid with nothing listening (a reused pid).
- Busy: a live pid whose port takes the health request but does not answer in time. Callers wait for a busy Inbox (up to 20 s, then an error) and never replace it, because a second process would be a second writer on the store.
- Callers re-read the registry on every call.
- An Inbox whose data is gone exits: every 5 s (`INBOX_DATA_CHECK_MS`) it reads `inbox.json` (`probeInboxData`). It is a miss ONLY when the file or its folder does not exist (ENOENT, ENOTDIR) or the file names another `serverSession`; any other error (EACCES, EIO, ESTALE, a file that does not parse) is unknown and leaves the count alone, and the folder's device and inode are not looked at (a remount or a moved copy must not end it). Two misses in a row stop it cleanly, then it says why on stderr (plus the manual `tailscale serve --https=<port> off` when the tailnet take-down failed) and the process exits 0 (`onDataGone`). Nothing could reach it (agents find an Inbox through the file) and it has no store, so it must not run on headless (an e2e once removed its temp folder under a live `--tailscale` Inbox, which ran for two days at 100% CPU, cause unknown). It is a timer, so it cannot end an Inbox stuck in a synchronous loop. After it starts, the Inbox rewrites `inbox.json` only while the file names its own `serverSession` (`updateOwnInboxRegistry`, used by the tailnet and Wi-Fi saves; read then write, so a start overlapping a stop can still lose its entry, and then exits by the same check), so a stopping Inbox never rewrites its successor's entry and never makes a removed data folder again.
- The detached Inbox runs with `inbox/` as its working directory and `windowsHide`.
- The update control (`packages/server/inbox-updates.ts`; design record, not in this repo): health, the list model and the event stream's `status` carry `update: { available: true, state, version, current, action, releaseUrl, publishedAt? } | null` (`InboxUpdate` in `packages/core/inbox-types.ts`; `available` and `version` keep the older shape). `ready`: on the health tick (60 s, every 2 s while `update.lock` is held), a compiled Inbox stats the binary on disk and, only when the file's identity (device, inode, size, mtime) changed, runs it with `--version`; a different version is ready (the old restart-to-update signal). `updating`: `update.lock` is held. `failed`: `update-result.json` records a non-zero exit for an install the PERSON started (`pending.by: "person"`; a background auto-update failure stays out of the sidebar). `available`: a release build (X.Y.Z, so never `dev` or `0.0.0-dev`) runs the shared daily release check on start and on each tick (it answers from the 24h cache, so it asks GitHub at most once a day, 6 h after a failure, never while `PLANNOTATOR_UPDATE_CHECK` is off) and shows a newer stable release at once, before anything is downloaded (owner's answer 2), unless "Remind me tomorrow" snoozed that version (`update-state.json` `snooze: { version, until }`, 24 h, shared by every tab; a newer release clears it). `action`: `script` when the running binary is the install script's (`isManagedBinary`), else `copy`. The list model also carries `updated`: the version this run started on when it is newer than the one the Inbox ran before (`inboxVersion` in `update-state.json`), for the sidebar's quiet "What's new in X" link this run only. That start also keeps the version it found as `inboxPreviousVersion` (additive; kept across restarts on the same version, replaced at the next update, removed on a downgrade), so the What's new page of a release this Inbox already runs still lists the releases skipped since the version run before the update (the answer's additive `since`, which `skipped` counts from; a newer release counts from the running version, and `current` stays the running version). The daily check saves notes only for the `releases/latest` it fetched, so a version installed outside the Inbox (the install script run by hand) before a check saw it has none: `fetchReleaseNotesFor` (`packages/shared/update-check.ts`) then asks for that release by its tag (`releases/tags/vX`, `releaseTagApiUrl`, the same client rules: the `plannotator-update-check` user agent, nothing while `PLANNOTATOR_UPDATE_CHECK` is off, claimed in `update-state.json` `notesFetch[<version>]` before the request, then 6 h after a failure and 24 h after an answer with no "What's New" part, never a loop) and saves `update-notes/<version>.json`. A stored file with an empty "What's New" part (saved before the release body was edited) counts as missing and is fetched again under the same throttle. The Inbox runs it on its tick for `updated` and from `GET /api/inbox/whats-new`, only for a version it has reason to show (the one it runs, the newest known release, the binary on disk, an install in progress); the route waits up to 3 s (`WHATS_NEW_WAIT_MS`), then answers `503 { code: "notes_loading" }` with `Retry-After: 1` and the page asks again (up to 15 times). `updated` is null while its notes are neither saved nor fetchable (checks off, or a fetch in its back-off), so no link points at a page with nothing on it; the event stream's `status` carries `updated` too, so the link appears or goes once the fetch settles. Update now is `POST /api/inbox/update` (`startManualUpdate`: the same wrapper, lock, log, pinned tag and remembered flags as auto-update, without its 24 h window or its open-sessions gate; a second press while it runs is `409 update_locked`); the page that pressed it restarts the Inbox itself once `ready` arrives. A tailnet page reaches none of the update routes.
- Plain `uninstall` and `--purge` both remove the `plannotator-inbox` MCP entries the connect step added (see "Connecting the agents on this computer"; `removeInboxAgentConnections` in `packages/server/uninstall.ts`): with the binary gone, an entry would fail to start at every agent launch. A plain uninstall then forgets those records, so a reinstall connects them again.
- `uninstall --purge` stops a running Inbox first (its token-guarded stop route, then SIGTERM only while the port still answers with that `serverSession` and pid) and removes `inbox/` (`inbox` is in `PURGE_OWNED_TOP_LEVEL`, `packages/server/uninstall.ts`). An Inbox that is still running after that blocks the data purge: uninstall says to quit it and run `uninstall --purge` again. It also takes down a tailnet mapping a crashed Inbox left (`takeDownInboxTailnet`, only when `inbox.json` has `tailnet`; `takeDownInboxTailscale` for the window's, only when `tailscale` keeps its ports). `--dry-run` lists the stop and the take-down. A plain uninstall keeps the data.

**Store** (`packages/shared/inbox/`, one writer: the server process).
- Layout under `inbox/`:
  - `projects/<key>/` holds `project.json`, `messages.jsonl`, `questions.jsonl`, `annotations.jsonl` and `cards.jsonl` (the Board's cards; see "The Board: cards") (an older store's `decisions.jsonl` stays there, kept only so sequence numbers are never reused; see "Decisions were removed"). `<key>` is the project name plus 6 hex of the root's hash. A key that collides takes more of the hash.
  - `blobs/<sha256>` holds sent attachment versions, the images messages show (`inline_images`) and guided-review snapshots.
  - `seq.json` holds the highest seq across deletions.
  - The Pi and OpenCode connections keep `claims/<reply id>/` (delivery claims), `connection-tools.json` (the last tool list) and `leases/<host>-<session>.json` (which process of a session delivers).
  - The Claude Code mod keeps its claims and lease under `claude-code-mod/<session>/inbox/`.
  - Compose keeps `drafts/<drf_id>.json` (drafts, outside the log), `uploads/pending/<upl_id>.json` (uploads not sent yet) and `uploads/<att_id>/<name>` (sent uploads: read-only copies of their blobs). See "Compose".
- A project is the repository (the git toplevel of the path an agent names) or the folder, with one fold: a LINKED git worktree (`git worktree add`, including Claude Code's `.claude/worktrees/agent-…`) files under its main repository's project, for new messages (owner approval "inbox-project-menu", separate small change, 2026-10-14). One module decides it, `packages/server/inbox-project-root.ts` (`createInboxProjectRoots`, one cache shared by sends and New message's live sessions, so they always agree):
  - The path is taken by its realpath (`folder`); not an existing absolute folder is `validation_error`. Not in a git work tree (no git, not a repository, inside `.git`, a worktree whose main repository was moved or deleted, since git cannot open it): the folder.
  - One `git rev-parse --show-toplevel --git-dir --git-common-dir` in the folder. A linked worktree is git's own layout: its git dir is `<common dir>/worktrees/<id>` (realpaths). Otherwise (a plain checkout, a submodule, whose git dir is its own common dir, a `--separate-git-dir` main checkout) the toplevel is the project, as before.
  - The main worktree of a linked one: `<repo>` for `<repo>/.git`; else a bare repository (`rev-parse --is-bare-repository` in the common dir) is the project itself, or the folder holding it when it is named `.bare` or `.git`; else the work tree git records for the common dir (`core.worktree`, how a submodule's own worktrees point at its checkout). A candidate counts only when git, asked from it, names it as its toplevel and the same common dir; anything else (a separate git dir with no work tree on record, an answer of the wrong shape, a git before 2.5 that echoes `--git-common-dir` back) keeps the worktree's own toplevel.
  - Every path is compared by realpath, both sides (symlinked spellings, macOS `/tmp`). Each git is `inboxGitRunner`: `rev-parse` only, killed at `INBOX_PROJECT_ROOT_GIT_TIMEOUT_MS` (3 s), `GIT_TERMINAL_PROMPT=0`, and `GIT_DIR`, `GIT_WORK_TREE`, `GIT_INDEX_FILE`, `GIT_COMMON_DIR`, `GIT_CONFIG_PARAMETERS`, `GIT_CONFIG_COUNT` and every `GIT_CONFIG_KEY_<n>` / `GIT_CONFIG_VALUE_<n>` cleared (`INBOX_PROJECT_ROOT_GIT_ENV_CLEARED`), so an Inbox started with them exported still asks each folder's own repository with its own config. Answers are cached per folder (at most 512), used as they are for `INBOX_PROJECT_ROOT_TTL_MS` (60 s) and then once more while a background refresh runs, so only the first sight of a folder waits on git. No git installed is an answer (exit 127: the folder is the project, as before).
  - A git that ran past the time limit gives a guess (the folder, or a worktree's own toplevel), marked `settled: false`, used once and never cached. `resolveProject` (`packages/server/inbox.ts`) never makes a project from a guess, because the store keeps every project forever: it takes an existing project at that root, else the existing REPOSITORY project whose root holds the folder most closely (`nearestProjectHolding` over projects whose root has a `.git`, read from disk without git; a folder project such as one at `~` never takes a guess, or a new worktree under it would be filed there for good), else it refuses with `project_unresolved` ("…git did not answer in time. Nothing was sent or saved; try the same call again.", `503` on a window route). Every MCP tool that takes `project_path` (send_message, submit_guide, read_thread, wait_for_reply) answers it as an `isError` result `project_unresolved: …`, which the stdio shim, the Claude Code mod (`deny`) and the Pi / OpenCode connections hand the agent as it is; nothing was written, so the retry (same idempotency key included) lands once.
  - A message sent from a folded worktree keeps the folder it was sent from as its `base_path` though it lies outside the project's root (`sendBasePath` in `inbox-mcp.ts`, through the context's `projectRootOf`), so relative images and attachment links resolve where the agent works. Attachments were already recorded by absolute realpath, relative to `project_path`.
  - Existing projects keyed by a worktree are never rewritten (the store is append-only): their threads, `reply_to` into them and their routing stay as they were. Routing reads only the `project_id` recorded on each message line, never a path, so a replay routes exactly as before.
  - After the upgrade, for an agent in such a worktree: its next plain send (no `reply_to`) starts a new default thread in the main repository's project, which is created then if no agent wrote from the main checkout yet (the old worktree project stays in the sidebar until it is archived and hidden). An idempotent retry that spans the upgrade lands in the main project (keys are per project). Thread reads still find the old threads: `read_thread`'s list and `wait_for_reply` without ids scope by `threadReadScope` (`inbox-mcp.ts`), the resolved project PLUS the project an older Inbox kept for that very worktree (`store.projectByRoot(<worktree toplevel>)`), so an agent that asked before the upgrade (an MCP-only agent in `~/.codex/worktrees/…`, whose shim always fills `project_path`) still gets the person's reply. Chosen over scoping by session alone, which would change what a session sees when it names another repository's `project_path` and does nothing for `asked_by: "anyone"`; the legacy project joins only for a path inside that worktree, so a read from the main checkout is unchanged.
- A project's `name` on every read (rows, threads, the project list, Storage, the event stream, the MCP tools, a push) is the real name of its folder, read from its stored `root` (`inboxProjectLabels`, `packages/shared/inbox/project-name.ts`); when two folders share a name each also names its parent ("api · work"). The stored `name` and the folder `key` stay the `sanitizeTag` slug, which also names plan history and the feedback archive, so nothing on disk is rewritten.
- Every line is a full snapshot `{ v, seq, at, kind, id, record }`. The last line per id is current. Nothing is rewritten in place, and fields are only added.
- `seq` is one counter across the Inbox. The union of lines by seq is the event log that the window's stream and `wait_for_reply`'s cursor read.
- A torn last line is skipped on read, and a newline is appended before the next write to that file.
- No storage caps.
- Records are snake_case with `msg_`, `prj_`, `ses_`, `att_` and `dec_` ULIDs.
- Questions:
  - A question record keeps Workspaces' `Question` wire fields beside Plannotator's `QuestionAnswer` v1 (`packages/core/inbox-types.ts`).
  - State (`open | picked | sent | closed | superseded`) is derived, never stored. `superseded` (the question record's additive `superseded_by: { message_id, key | null }`) wins over `closed`; see "Replaced questions".
  - `Stopped:` and `Holds up:` lines are read as Workspaces reads them (`packages/core/inbox-questions.ts`, over core's `findQuestionBlocks` and `parseQuestionBlock`, so keys equal the card's), with one guard Workspaces' parser is to add as well: a `Stopped:` value or `Holds up:` entry that is only a negative word (no, none, n/a, na, nothing, false, nil, null, a dash; any case, trailing punctuation allowed) is no stop and holds nothing up (`isNegativeWaitValue`). Anything else still stops, an empty `Stopped:` and `No; I need the DB password first` included. Records keep the value read at send time.
- Idempotency:
  - An agent's send is idempotent on its `idempotency_key`. The key is checked before routing. Another body, `reply_to` or thread name under the same key is `409 idempotency_key_reused`.
  - A person's Send is idempotent on its own key.

**Threads and the project filter** (the row model, owner ruling 2026-10-07). A row is a thread. The project is a label on the row and a filter (the sidebar's folders), never the row. `send_message` routes in `InboxStore.sendMessage`, and the first match wins:
1. `reply_to`: that message's thread, as a reply.
2. `thread`, a name:
   - Validation: trimmed, 1 to 120 characters, with no control characters, line breaks or bidi controls, and something visible. Anything else is `validation_error: thread: …`.
   - It joins the newest OPEN thread of that name in the project, across sessions. With none open, it starts a new thread under the name.
   - Names compare by `inboxThreadNameKey` (NFKC, default-ignorable code points dropped, whitespace runs as one space, case folded), so look-alike spellings are one thread. The stored name keeps the first sender's spelling.
3. Otherwise, the sender session's default thread: the newest UNNAMED thread that `agent_session` started in the project while it is open, else a new thread. A sender with no `agent_session` starts a thread with each message.

More rules:
- Resolved means done: the next message starts a new thread. A resolved thread still takes `reply_to` replies.
- A thread keeps its first message's subject, except that a subject derived from a question (the agent gave none) follows that question's replacement, down the `superseded_by` chain (`InboxStore.threadSubject`; the root's additive `subject_question` names the question, and a root older than it counts as derived when its subject is its first question's prompt). An agent-given subject never changes, and a question withdrawn with nothing in its place keeps the subject it gave.
- A subject is one line of plain text. send_message and submit_guide refuse one with leaked tool-call text (`</subject>`, `</parameter>`, `<parameter name=`, `<invoke name=`, `</invoke>`, `<function_calls>`, `antml:`-prefixed tags), a line break, a control or a bidi character with `validation_error: subject: …` before anything is written, so a corrected retry under the same `idempotency_key` lands once (`checkInboxSubject`, `@plannotator/core/inbox-types`; checked in `sendProject`/`sendAgentMessage` and again in the store; ordinary `<` / `>` in prose stays allowed). Subjects an older Inbox kept verbatim are never rewritten on disk: every read serves them through `displayInboxSubject` (first line, cut where such markup starts, controls and bidi dropped, trimmed) at the one funnel `InboxStore.threadSubject` plus a root's wire record, search's fallback, the event stream's message lines and the relay push, so the window, the phone, notifications and agents (read_thread, wait_for_reply, search) all get the cleaned subject.
- Routing reads only the log: two indexes (`sessionThreads`, `namedThreads`) are rebuilt from each root's first line in seq order. A replay therefore routes exactly as the live store did, and an older store with no `thread_name` replays unchanged.
- Routing is synchronous inside the server process, so racing sends land in one thread.
- `read_thread`'s list mode lists the threads the session sent in (`asked_by: "me"`), and `wait_for_reply` with no id waits on those threads.
- Without a cursor, a reply counts when it comes after the caller's last message in the thread.

**The list** (`packages/shared/inbox/list.ts`, pure; labels in `INBOX_SECTIONS`, `packages/core/inbox-types.ts`). The sections, in order: Stopped on you, Holding up work, Waiting on you, New since you looked, Sent, Quiet. Sent sits below New because it waits on the agent, not on the person (owner ruling 2026-10-11). The strongest reason wins:
1. Archived (resolved) and not come back: Quiet. The window leaves archived threads out of the list altogether (see "Archived" below); the list model places them in Quiet only for callers that do not ask for them apart. A thread that came back (an agent wrote after the archive and something there still waits, `back_from_archive`) is placed by the rules below like an open thread.
2. Marked read (Mark read) and no message since but its set-aside note: Quiet, unless unsent work waits and no Re-ask note waits (rule 9).
   After it, before rule 3 (rule 2a of the thread-state model; owner's rule, approval "inbox-reask"; see "Re-ask"): every open question is listed in a Re-ask note that still waits: Sent, whether or not the agent read the note (`reask_pending` on the row). A note waits until the session it went to (its `to`, else the asker) writes again, and only while a question it lists is still open; another session's new question, or the listed questions answered, superseded or closed by anyone, ends it, so a session that never writes again cannot hold the thread in Sent.
3. An open question with `Stopped:`: Stopped on you.
4. One with `Holds up:`: Holding up work.
5. Any other open question: Waiting on you.
6. Picks saved but not sent: New since you looked ("Answered, not sent").
7. The person's reply is the last message and no agent has read it: Sent. The Inbox's own notes (the set-aside and reopened notes below) are read past here and everywhere the list derives from the person's messages: they are neither a reply nor a look (`isInboxNote`).
8. Agent messages after the person's last look: New since you looked.
9. Unsent work (the row's additive `unsent`, see "Reply drafts and the Draft label"): words typed in the reply box, picks not sent, or comments waiting for a Send: New since you looked. A thread holding any of it never sinks to Quiet unless it is archived (rule 1 wins: archiving is the person's explicit "done", and the draft is kept). A Re-ask note that waits (rule 2a) keeps the row in Sent, after a Mark read in Quiet, as without a draft; the row still shows its Draft label. Agents never see this rule: `read_thread`'s list gives them the section without it.
10. Anything else: Quiet.

Sorting and the rest:
- Every section sorts newest first by the thread's latest message (`last_at`, the time the row shows); ties on the thread id (owner ruling 2026-10-08).
- `unread` (bold) means Stopped, Holding, Waiting or New, except a row in New only for the person's own unsent words or comments (no unseen agent message, not "Answered, not sent"): not bold, and not counted as waiting on the person (the sidebar's Drafts row counts it).
- "Looked" is `POST /api/inbox/threads/:id/seen`, sent when a thread opens (capped with `through_seq` at the newest agent message the window read, so one that lands before the server takes the look stays new) and again when a message that arrived while the thread was open has been seen on sight (see "Seen on sight"). The person's own reply also counts; the Inbox's notes do not.
- "The agent read it" is recorded when `wait_for_reply` returns the person's reply or `read_thread` reads the thread, which moves a Sent row to Quiet. Any agent's read counts.
- `?project=prj_…` keeps the sections and drops other projects' rows.
- The list is linear in the store: about 10 ms for 4,000 threads.

**The thread-state model**: `adr/implementation/inbox-thread-state.md` (sections, events, the transition table, invariants, the violations it found and their fixes), checked by `packages/shared/inbox/store.test.ts`, with trace fixtures for the phones in `packages/shared/inbox/fixtures/thread-state/v1/`.

**Archived** (owner ruling 2026-10-12: "Archived messages should move out of the Quiet list … only visible within a panel on the Settings page … the ability to unarchive them").
- **Came back** (mail apps' rule). An agent's `reply_to` reply into an archived thread lands after its archive line. Messages after that line behave as an open thread's; messages before it stay as the archive left them; the thread stays resolved (`resolved_at` kept) until the person acts, and nothing unarchives it implicitly (not even a Send: that would reopen the archive-closed questions and change the agent's default-thread routing).
  - The line: the store keeps, per root, the seq of the root line that set its current `resolved_at` (`resolvedSeq`, rebuilt in seq order by every replay and cleared by `reload`; a look or any other root rewrite with the same `resolved_at` does not move it). `closedByArchive(message)` = the thread is resolved and the message's first line is before that seq. Derived, never written.
  - One question state everywhere: `InboxStore.questionWire(record)` / `questionsOf` read a question as `closed` only when the archive closed its message. The window's thread, the event stream (`eventPayload`, so notifications and the question sound fire), and the relay push (`pushFor`, so the lock-screen answer is offered) all use it. Writes follow the same rule (`messageAnswerable`): picks, Send, and annotations on a message's attachments or guided review are taken for a message after the line and refused (`409 thread_resolved`) for one before it. New message stays refused on an archived thread (the window hides it). The agent side: `read_thread`'s list and `wait_for_reply` treat a thread with an agent message after the line (`agent_after_archive`) as open, so the person's answer reaches the waiting agent, and a seen-line rewrite no longer ends a wait as "resolved".
  - The row: `agent_after_archive` (an agent wrote after the line) and `back_from_archive` (that, and something still waits: an agent message after the line the person has not looked at, a live question open or picked, or the person's reply after the line the agent has not read). While `back_from_archive` the thread is in the list, placed as an open thread would be (New since you looked; Waiting, Holding or Stopped when it asks; Sent after the person replies) and out of the Archived block; once handled it returns to the archive by itself. Questions the archive closed stay closed, so a plain update comes back as New, not Waiting.
  - The window (`Thread.tsx`, from the thread read's additive `archive_seq`): cards, Reply and comments on files and guides are live for messages after the line; the foot carries "Archived · <agent> wrote after you archived it. Your reply goes to it; the thread stays archived." with **Unarchive** above the reply actions (`data-came-back`). Mark read works on what came back (`canToggleRead` / `offersRowMarkRead` accept `agent_after_archive` / `back_from_archive`): it sets aside the post-archive questions (the agent is told once, as for any Mark read), the thread goes back to the archive, the toast says "went back to Archived", and Undo brings it back.
  - Archiving again after the reply (Unarchive, then Archive) writes a new archive line after it: archived again. Unarchive drops a Mark read made while the thread was archived (`person_read_seq` after the archive line, cleared in the same root line, so a replay agrees): it covered only what came back and must not hold the reopened thread in Quiet over the questions the archive had closed. A Mark read made before the archive is kept.
  - The "person reply the agent has not read" that keeps a thread back ignores the Inbox's own notes (Mark read's set-aside note and its Undo's reopened note), as `readAt` does, so Mark read on what came back leaves it in the archive.
- The window's list holds no archived (resolved) thread in any section, Quiet included. It asks `GET /api/inbox/threads?archived=exclude`, which drops them from the sections. Without the parameter (`archived=include`, the default) the list model is unchanged: archived threads stay in Quiet. That default is for the phone: the door forwards `GET threads` to this route as it is, and an iPhone app that draws the sections natively keeps every thread it had, with no new release needed; an older window keeps working too. The sidebar's folder counts never counted archived threads (they count rows waiting on the person) and are the same either way.
- `GET /api/inbox/threads/archived` (`?project=`, `?offset=`, `?limit=` 1 to 200, default 50, `INBOX_ARCHIVED_PAGE`) lists them newest archived first (`resolved_at`, ties on the thread id; `inboxArchivedRows` in `list.ts`), with `total` in the filtered scope and `projects: [{ id, name, archived }]` (every project with archived threads). The door has an explicit allowlist row for it (`GET threads/archived`, read only, before `threads/:id`), so a phone can read it too.
- Settings' **Archived** block (`packages/inbox/components/Archived.tsx`, above "Stored on this machine"): "N archived threads", then one Settings row per archived thread (the agent's mark, the thread chip, the subject; then the agent, "Archived <day>", the message count) with **Unarchive**. When more than one project has archived threads the rows sit under a small header per project with its count ("billing · 2"), the projects in the order of their newest archived thread; there is no dropdown (the owner asked for no native select). 50 rows across the whole list, then "Showing 50 of N" and "Show 50 more"; "Nothing archived." when empty. It reads again whenever the store's cursor moves. Unarchive is the thread's resolve `false`; the window then opens the thread in the main list (`#thread=`, in whatever section its state puts it) with the toast "Back in your Inbox · “subject”" and Undo (archive again).
- Archiving from a thread keeps its toast and Undo. While that thread stays open its row keeps its place in the list, shown archived ("Archived", not bold: `markHeldRowArchived` in `held.ts`), and leaves the list when the person leaves the thread (the held-order rule). A deep link `#thread=` to an archived thread still opens it, with "Archived … · Unarchive" in its foot; its row, which the list no longer carries, comes from the thread read's additive `row`.

**The window** (`packages/inbox`, built by `apps/inbox` as a Vite single-file app).
- Build and serve: `build:hook` copies its `dist/index.html` to `apps/hook/dist/inbox.html`. The binary embeds it, and `runInboxCommand` hands it to `startInboxServer` as `htmlContent`. Without it, `/` says to run `build:hook`.
- Styling: `packages/inbox/inbox.css` carries the design record's values on Plannotator's theme tokens with an `ib-` prefix. Plannotator's own components draw themselves.
- Routing is the hash: `#thread=msg_…` (the link the MCP tools hand agents), `#project=prj_…`, `#settings` (General; on a phone the list of sections), `#settings/<section>` (`general`, `agents`, `devices`, `archived`, `storage`, `about`; an unknown one reads as `#settings`), `#settings/devices/pair` (Pair a phone open), `&file=att_…` (with `&view=full|side`, the file's view; see "Side by side, remembered"), `&guide=msg_…`, `&msg=msg_…` (land on that message: a search result; dropped from the hash once landed) (`packages/inbox/settingsRoute.ts` for the Settings addresses). An old link to the removed Decisions page (`#decisions=…`) opens the list.
- Opening a thread (`#thread=`): the pane shows once `GET /api/inbox/threads/:id` lands. A read that fails (a dropped connection, a 5xx) or has no answer in `THREAD_READ_TIMEOUT_MS` (8 s, an AbortSignal) is read again after `THREAD_READ_RETRY_MS` (250 ms, 1 s, 2 s, 4 s, then every 5 s while the thread stays open; a 404 is not; opening another thread or closing stops it; a read the event stream lands meanwhile ends the wait; `packages/inbox/App.tsx`). Reads are numbered, so an older one never overwrites a newer one that landed. Until it lands the thread's place beside the list says so (`components/ThreadWait.tsx`: nothing for the first 600 ms from the open in any state, then "Opening the thread…" (`aria-busy`), the failure with Try again (said once, not per retry), or for a 404 "not in the Inbox" with Close; focus inside it goes to the thread's subject when the thread lands; a phone and a stacked window keep the list, as before). Before this one failed read left the right side blank until some agent wrote anywhere in the Inbox (the event stream re-reads the open thread). Proof: `packages/inbox/threadReadRetry.test.tsx`.
- Issue refs (#1840): bare `#123` / `@user` in messages and markdown attachments link to the project's git `origin` (GitHub or GitLab, per `forgeRefLinks`, new tab). The server resolves `git remote get-url origin` per project root off the request path (`packages/server/inbox-repos.ts`: for every project once the server is listening and when a project is first seen, at most 4 gits at once, refreshed in the background after 5 min, 3 s git timeout, parsed by `parseRemoteUrl`/`parseRemoteHost`) and `GET /api/inbox/threads/:id` carries it as `thread.project.repo: { display, host } | null` (null for a folder without git or without origin, or until the first resolve lands; a git failure or timeout is cached as null for those 5 min too). The window hands it to `Viewer` as `refRepo`, which links refs without drawing `repoInfo`'s repo badge. A digit-only 6 or 8 digit ref (`#186379`) is an issue ref, not a hex swatch, only in the Inbox (`configurePlannotatorUI({ digitHexIssueRefs: true })`, off for every other host), only when a ref link can be built (a repo on a known forge), and only without a leading zero (#1932).
- The sidebar:
  - The Tater mark (24 frames over 3.5 s, paused offscreen, the first frame under reduced motion).
  - Inbox, and each project folder with the count of rows waiting on the person. A project with no thread in the window's list leaves the sidebar (see "The project menu").
  - Settings.
  - The Update button above Settings (below Copy prompt) when health reports `update` (`components/Updates.tsx`; Workspaces' rules: one full-width filled primary button, 32 px, no motion, never a percentage, never the error colour; tooltip "Plannotator X is available" / "is ready"; Available and Ready read "Update to X.Y.Z", one line, ending in an ellipsis rather than wrapping at the 200 px sidebar (`.ib-upd-l`), so it is never one of two bare "Update"s (approval `inbox-whats-new-header`); the accessible name is the visible text ("Update to X.Y.Z", WCAG 2.5.3 Label in Name), and Failed's is "Update failed: Plannotator X didn't install"). Available opens the update dialog: "Update to Plannotator X", the notes' first paragraph, What's new, what happens (the install script with the remembered flags, the open sessions from `sessions/`, the Inbox restarting), the Claude Code plugin command only when `--skip-claude-plugin` was remembered (the install script updates the plugin otherwise), the "Install new versions automatically" checkbox (writes `autoUpdate` through `POST /api/inbox/settings` `{ auto_update }`), and Remind me tomorrow / Cancel / **Update now**; a binary the script does not manage gets the command instead of Update now. Updating and Restarting show the same button disabled with a small spinner. Ready restarts at once (`POST /api/inbox/restart`: the server stops, the binary on disk starts detached, and the page reloads on the new `serverSession`), first asking when the open thread's reply box holds unsent text (`unsent.ts`). Failed is a neutral outline button that opens the failure dialog (exit code, `update.log`, the install command, Try Again). What's new is a page at `#whats-new=X` (`GET /api/inbox/whats-new?version=X`: the stored notes through the read-only `Viewer`, and the one-line highlights of the releases skipped, "Also in the releases since <since>", folded past three). Its header is the approved Toolbar design (`.product/approved/inbox-whats-new-header/`, not in this repo): a sticky bar (`.ib-wn-bar`, over the notes' own stacking context) with the SidebarTrigger, `‹ Inbox` (`data-whats-new-back`: the browser's Back when the page was opened from that Inbox screen, `backTo` in `history.ts`, else a new entry to the last Inbox screen that was neither Settings nor What's new) and `What's new` on the left; on the right the GitHub release link (new tab) and, only while that release can be installed (`whatsNewCanUpdate`: the update's version is the page's and its state is available or ready), "Update to X.Y.Z" (primary; does what the sidebar's Update does; "to X.Y.Z" drops under 380 px, the name keeps it). Under it, aligned to the notes: "What's new in Plannotator", the version large, "Released <long date>", and one chip (`whatsNewStanding`): "You're on this version"; "Development build" for a running version that is not X.Y.Z (never "You have dev"); behind, a button "You have X · N releases in between" that opens and scrolls to the skipped releases and focuses them (no motion under reduced motion), or "You have X" alone when the notes name none in between; past the release, "You have X". On a phone the bar is one row of 44 px targets (no title, the GitHub mark alone). Proofs: `packages/inbox/whatsNewHeader.test.tsx`, the Back case in `whatsNewLink.test.tsx`, and the restart and downgrade cases in `packages/server/inbox-updates.test.ts`. **Images in the notes** (`packages/server/inbox-whats-new-images.ts`, Inbox only; the shared `update-check.ts`, vendored to Pi, fetches no image): the window never loads a remote image and its CSP stays `img-src 'self' data: blob:`. Instead the Inbox copies the images a release's saved "What's New" markdown shows (markdown images and `<img src>`, outside code, `inboxMessageRemoteImageRefsInOrder`) once, beside the notes, and the page loads the copies from `GET /api/inbox/whats-new/image`. Only `https:` on the default port, no credentials, no empty host label (`.githubusercontent.com` fails), and only the hosts release attachments use (`allowedReleaseImageUrl`): `github.com/user-attachments/assets/*`, `private-user-images.githubusercontent.com` (where user-attachments redirects), `user-images.githubusercontent.com`, and `raw.githubusercontent.com/backnotprop/plannotator/*`; no other `*.githubusercontent.com` host (gist., objects., camo., …). Redirects are followed by hand (`redirect: "manual"`), at most 5, each to an allowed host. Each image: at most 10 MB (declared or counted as it streams) and 50 megapixels, type sniffed from the bytes (`sniffImageContentType`), one 15 s deadline across redirects and body; at most 12 per release (the first 12 the notes show). The release check's rules: nothing is asked while `PLANNOTATOR_UPDATE_CHECK` is off, the `plannotator-update-check` user agent, and a claim per version in `update-state.json` (`releaseImagesFetch`, the `notesFetch` shape: claimed before the request, again 6 h after a failure and 24 h after an answer; nothing at all once every image is stored). A failed image is left out and logged to `update.log`; it never fails the notes. Stored as `update-notes/<version>/<sha256>.<ext>` with the src → file map in `update-notes/<version>/images.json` (its own file, so the daily check rewriting `<version>.json` never drops it); `uninstall --purge` removes `update-notes/` whole. When: in the background, whether or not What's new is ever opened: off the health tick for the newest known release and the "just updated" version once their notes are saved (never awaited), so besides the one daily `api.github.com` request the Inbox downloads up to 12 images per release from those image hosts, only while update checks are on; and from the What's new route, within its same 3 s wait, only for a version the Inbox may fetch notes for (`fetchableVersion`). The route answers `images` (the srcs stored), and the page hands ui's `ImageResolverContext` a resolver (`resolveImage` in `WhatsNewPage`): a stored src loads from `whatsNewImageUrl`, any other image (not saved, another host, an older Inbox without `images`) is drawn as its alt text in ui's quiet dashed chip, never a broken image and never a request. PLANNOTATOR_UPDATE_API_URL pointed at a loopback `http:` origin also lets images from that same origin through (a test's fake GitHub); a non-loopback mirror widens nothing. Proofs: `packages/server/inbox-whats-new-images.test.ts` (the allowlist, redirects, caps, the switch and claim, the route), the DOM test `packages/inbox/whatsNewImages.test.tsx`, and the tailnet refusal in `inbox-tailscale.test.ts`. Settings → About: the version and when it last checked, Check now (`POST /api/inbox/update/check`, an explicit request even with checks off), "Tell me when a new version is out" (`update_check`) and "Keep Plannotator up to date" (`auto_update`, needs checks on).
  - **Copy connect prompt**, an outlined pill (`.ib-cpill`, not an `.ib-nav`) at the top of the sidebar's foot: above the Update button or "What's new in X", which sit above Settings (order: owner's call 2026-10-16; owner approval 2026-10-13, design record `inbox-sidebar-connect-prompt`; look amended 2026-10-15 by `inbox-connect-row`, option 1b; neither in this repo): the Claude Code, Codex, Pi and OpenCode marks (`AgentIcons`, 16 px, own colours, `aria-hidden`), then "Copy prompt"; its name is "Copy prompt to connect an agent" (screen-reader words after the visible ones). Content-wide, capped at the sidebar: at the 200 px minimum the label ends in an ellipsis, never the marks; 44 px tall on a phone. Only a copy button: no preview, no flyout, no tooltip, no shortcut. A click copies the prompt from `packages/inbox/connectPrompt.ts` (the one place its text lives): connect yourself as `<binary> inbox --help` says, send a first message with a question offering real recent work, wait for the answer. `<binary>` is this computer's absolute `plannotator`, `GET /api/inbox/settings` `mcp_command` without its trailing `inbox mcp` (`connectCommand`), or bare `plannotator` plus where it usually lives until the settings load. The label then reads a check in `--success` and "Copied" for 2 s (`CONNECT_COPIED_MS`; the marks stay; the check's colour does not fade), or "Couldn't copy" for 4 s; focus stays on it, a polite live region (`data-connect-prompt-live`) says "Connect prompt copied." or "Couldn't copy the connect prompt.", and the phone sheet stays open (it is not navigation). Shown everywhere, a page opened over the tailnet included: the prompt names this computer's paths, so it is for an agent on this computer. Tests: `connectPrompt.test.ts`, the DOM test `connectPromptRow.test.tsx`, and a step in `tests/e2e/inbox-sidebar.spec.ts` that reads the clipboard in Chromium.
  - The frame is Workspaces' sidebar primitive, copied by the owner's word (2026-10-09) into `packages/inbox/shell/` (each file names its Workspaces source and commit): the toggle at the head of each page and ⌘B / Ctrl+B close and open it on Workspaces' one spring (`shell-motion.ts`, MotionValues from `motion`, reduced motion lands without travel); ⌘B does nothing in an input, a textarea or an editor; the state is the Inbox's own cookie `plannotator-inbox-sidebar-open` (open when absent). Closed, a 600 ms rest on the left edge peeks it (1024 px and wider). The edge collapses on a click and resizes on a drag (200 to 520 px, 232 by default, cookie `plannotator-inbox-sidebar-width`), closing past 100 px and reopening if the held pointer comes back. Below 768 px it is a sheet. A file beside a thread closes it on the same spring without changing the stored choice.
- A wide row shows:
  - the project label
  - the badge ("Stopped", "Holds up N")
  - the agent's mark
  - the named thread's chip
  - the subject
  - the count ("2 questions", or "Answered, not sent"; in Quiet, "Read" or "Archived")
  - the "Guided review" mark when the thread carries one
  - the time

  **Delivery ticks** (approval "inbox-row-delivery", "Ticks", 2026-10-20; `components/DeliveryTick.tsx`, words in `packages/inbox/rowDelivery.ts`): a row whose latest sent item is the person's (their reply or message is the last message, the Inbox's notes read past, or a 👍 Looks good on the latest agent message once it is not withdrawn) shows a glyph before its time, on wide rows, rows beside a thread and phone rows (and, while it waits on a busy agent, "Undelivered N min" in place of the count, see "Undelivered replies go in by themselves"): a clock queued, three dots sending (they brighten in turn; still under `prefers-reduced-motion`), ✓ saved (an agent that reads the thread later, or the session that asked ended), ✓✓ delivered (the row's time is then the delivery time), a warning triangle not delivered. Shape tells the state, the tone only helps (`--ib-tick-*` in `inbox.css`, stepped toward the text colour like the Soft badges' words, light and dark). The state in words is in the row's accessible name (the glyph is `role="img"` with `aria-label` "Queued for Claude Code,", "Looks good, delivered to Pi,", …), and its tooltip (ui's, `Tip`) is the thread's own delivery line word for word (`deliveryText`). The row reads the server's `delivery` field (see "Inbox Server"), so a row and its thread never disagree; Send now stays in the thread. A Sent row now shows its own subject; a reply that tags agents keeps its recipients words; an older Inbox (no `delivery`) keeps the old words, "Queued for <agent>; it gets this as its next turn." / "Saved for <agent>. …" (`sentRowLine`). The glyph sits in the 10 px gap left of the 76 px time column (`overflow: visible`), so the columns do not move. Live: a turn starting or ending writes no store line, so the server compares the live sessions' delivery signature every second while a window listens and sends `event: deliveries` (windows only, never the phone's door); the window reads the list again then, only while some row's delivery can still move (not delivered, and not saved for an agent that only reads the thread, which only a store line changes). Quiet is folded. The Soft look paints the list without moving it (owner, 2026-10-16: Soft modernizes today's Inbox; today's densities, row heights, columns and places win over the prototype's): section bands keep their 34 px band (on `--ib-soft-band`: the raised surface at radius 8 when on, today's muted band when off, the owner's choice), the thread chip is a quiet pill in the window's face (`--ib-soft-chip`; off, today's outlined monospace tag) and the badges tinted pills (`.ib-b-stop`, `.ib-b-hold`), each the same box as before (a border that goes stays as transparent width).
- Rendering cost with thousands of rows: every row stays in the DOM (no virtualization: find in page, focus, the accessibility tree and the scrollbar behave as for any page). A row off screen skips style, layout and paint (`content-visibility: auto` on `.ib-lbody > .ib-group > .ib-rw` and `> .ib-mrow`, with `contain-intrinsic-size: auto …` estimates of 50 px wide, 65 px two-line, 76 px + padding on a phone; `auto` keeps the size a row last rendered at), and rows are memoized on their content (`ListRow` in `InboxList.tsx`: a list read brings new row objects, so it compares them deeply, with callbacks of one identity and today's date, which `shortTime` writes against), so a list update renders only the rows that changed. Measured on 4,000 threads in headless Chromium: an agent message arriving went from about 370 ms of long tasks to none, Show from about 600 ms to 70 ms, and style and layout at load from about 230 ms to 70 ms.
- The look of a row (design record "inbox-polish", approved 2026-10-15, not in this repo; `inbox.css`, `components/InboxList.tsx`):
  - Hover and the selected row are a pill 3 px inside the row (its `::before`, radius 8, `--ib-lr-sm` with `--ib-soft-shape`; no border; variant A): hover muted 45% (`--ib-hover`), selected `--ib-sel` (primary 10% light, 15% dark; 14% / 19% hovered). The selection is the owner's pick of today's (`--ib-soft-selection` off; on, a neutral fill, the text colour at 7%, 10% hovered). Rows have no line between them in the Soft look (`--ib-soft-rows` on in both modes, owner 2026-10-17, after the prototype: the colour study had kept today's hairlines): each row keeps its separator's 1 px as a transparent border, so the pitch is today's and rows part by the pill's 3 px inset and the space around it; the wide, two-line and phone (`.ib-mrow`) rows alike. Off, the separators are today's hairlines and run unbroken under the pill.
  - The thread chip is left out when the subject already starts with the thread's name (`chipName`: compared by `inboxThreadNameKey`, and only where the subject ends there or goes on with a space, or with `:`, `-`, `–` or `—` and a space, so `v2` stays beside "v2.1 release" and `auth` beside "auth-service down"), on the wide, two-line and phone rows.
  - A chip, subject or project label cut with "…" shows the whole text in ui's `Tooltip` on hover (`ClipText` over `Tip`, only while cut; 150 ms, the next one at once within 400 ms). No native `title` on them, not a focus stop, nothing added for a screen reader (the row's name holds the whole text). On a phone the chip's name wraps to two lines instead. The subject's flex-shrink is 1,000,000 (was 1,000): flex shares a shortfall by factor times width, so at 1,000 a chip still lost a fraction of a pixel whenever the subject shrank, and Chrome drew an ellipsis on a chip that fit (the owner's "reconciliation-r…", a 0.06 px cut at a device scale of 2 beside an open thread); the list header's folder and compose's To picker folder take the same factor.
  - **Tooltips are components, never native `title`s** (the owner, 2026-10-17: "I want an actual component tooltip"). Every hover text in the Inbox window is `Tip` (`packages/inbox/components/Tip.tsx`) over ui's `Tooltip`; the window's one `TooltipProvider` (`InboxApp`) sets 150 ms (`TIP_DELAY_MS` = ui's `TOOLTIP_DELAY_MS`, ui's default for every app; also passed per trigger) and 400 ms to the next. `cut` opens it only while the text is cut, `when` decides otherwise (a mark whose label is hidden), else it always opens; where the native title said something the screen does not (a sidebar project's folder: `ProjectTipText`, name over folder; a named search chip's subject; a full date) it always opens. `isTextCut` counts any whole pixel of scrollWidth over clientWidth, and compares the text's Range width with the box's content width (a hundredth of a pixel), so a sub-pixel ellipsis still opens it. A control that can be disabled (`disabled` in its props) hangs the tooltip on a `.ib-tipwrap` span (`flex: none`, so it never shrinks below the control it holds) whose disabled child takes no pointer, since a disabled button gets no pointer events. A trigger inside an open native `<dialog>` (search, compose, the agent-note and update dialogs) portals the popup into that dialog (ui `Tooltip`'s additive `container` prop), else into the window's root (`.pn-inbox`, marked `data-pn-tooltip-root`; ui's `tooltipContainerOf`, which ui's `HostTitle` uses too), so the window's tokens reach it: with Soft's `--ib-soft-float` on, a tooltip (`[data-pn-tooltip]`, ui's popup) floats like the window's menus and the toast (Soft's shadow); off, ui's own float shadow (`--float-shadow`). ui's popup has no visible border either way (the owner's design-system ruling q4: a borderless float at 150 ms in every product; the 1 px border is transparent so forced colors still draw an edge), and the sidebar edge's own tooltip (`.ib-edge-tip`) uses `--float-shadow` too. Nothing opens under `(hover: none)`. Escape closes an open tooltip and still reaches the window (ui `Tooltip`'s additive `escapePassesThrough`), so Escape closes a thread even while a tooltip shows (Base UI's default swallows it). Triggers keep their own `aria-label`; a sidebar project keeps its folder as its accessible description (`aria-describedby` on a `hidden` element). ui's Tooltip draws at `z-[110]`, above the annotation toolbar (`z-[100]`). ui's own hover text inside the Inbox goes the same way through `configurePlannotatorUI({ componentTooltips: true })` (ui `components/HostTitle`; default false, so plan review, annotate, code review and other hosts keep native titles): the annotation panel's and toolbar's buttons and labels (a title that was a button's only name becomes its `aria-label`; any other title stays the control's description, a `hidden` element named by `aria-describedby`, since the tooltip tags nothing for a screen reader), and a message link to an attachment (`resolveLocalLink`'s `title`). Left native: an iframe's `title` (its accessible name), and the ui components not yet routed through `HostTitle` that the Inbox can show (CommentPopover, AnnotationToolstrip, the ImageAnnotator toolbar, CodeBlock's copy button, TableToolbar / TablePopout, DiagramBlock and the diagram viewer, CodeFilePopout, QuestionsPanelSection, HtmlViewer's own controls). `clipTitle.ts` is gone. Proofs: `packages/inbox/componentTooltips.test.tsx` (DOM: a cut row label, a sidebar project and its description, the 0.06 px chip), `packages/inbox/links.test.tsx` (an attachment link's component tooltip), `tests/e2e/inbox-tooltips.spec.ts` (compiled binary at 1440, device scale 2, a thread open: no native title anywhere in the window but iframes, the tooltips, no chip cut by under a pixel at six list widths, Escape with a tooltip open, Mark read never spilling over Archive from 320 to 1440 px, a disabled control's tooltip).
  - Keyboard focus (`:focus-visible` only) is one 2 px `--ring`: row-like items draw it inside themselves following their radius (list rows on the pill; the Quiet band, sidebar rows and projects, a phone's row, fold lines and a message's head with `outline-offset: -2px`), so no neighbour paints over it and the projects' scroll box never clips it. List rows keep a transparent 2 px outline beside the inset ring, so forced colours (Windows High Contrast) still draw one. Free-standing controls keep the base ring, 2 px outside; `button.ib-mut` (Reply, the hold-ups toggle) has radius 6. Measured at 4.9:1 or more against the card, the hover and the selected pill, light and dark.
- Beside an open thread the list narrows to 380 px and takes the sidebar's edge (`shell/ListColumnEdge.tsx`: the same `useResizablePanel`, `CollapsibleEdge` separator and `ResizeHandle`, without the collapse; arrows, Home/End, `aria-controls` the column; its grab area leans toward the pane so a classic scrollbar stays grabbable; cookie `plannotator-inbox-list-width`): a drag widens it from 380 px up to leaving the thread pane 480 px (no edge when the window leaves no room to widen, and none below 768 px), and its rows turn wide while the column's border box is 900 px or wider (`WIDE_ROWS_MIN_LIST_WIDTH`, read from the observer's `borderBoxSize`, the same box as `getBoundingClientRect`) (`tests/e2e/inbox-list-resize.spec.ts`).
- The Soft look (`.product/approved/inbox-soft/`, approved 2026-10-16; not in this repo) modernizes today's window and does not relayout it (owner, 2026-10-16): densities, row and control heights, columns and places stay today's, and a border Soft removes stays as transparent width. The owner's rulings (recorded in the approval): the two blind rounds decided COLOURS only (2026-10-16): today's ground, selected row, row separators and lines, and section band in both modes; Soft's Stopped / Holds up badges (tinted pills), fewer accents (links, Reply, a tile's Open) and question card surface in both; the sidebar's current item and quiet text today's in light and Soft's in dark. Everything that is not a colour is Soft by default (2026-10-17: "I want the soft look to be its own thing"), at today's spacing and row pitch. Each part is one switch at the top of `inbox.css`: the colours `--ib-soft-ground` (Soft's tinted ground; off), `-selection`, `-rows`, `-band` (off), `-badges`, `-accents`, `-card` (on), `-nav`, `-quiet` (on in dark only); `-rows` was today's in the study and is on in both modes since the owner asked for the prototype's rows with no line between them (2026-10-17; only the rows: every other line keeps today's colour, its faint fill a switch of its own, `--ib-soft-lines`, off); and the non-colour parts, all on: `-panes` (rounded floating panes, 8 px gutters, their shadow, no rules between panes), `-labels` (small labels in sentence case at 12 px), `-shape` (radii), `-float` (floating surfaces' shadow, no outline), `-hover` (hover fills and fades), `-chip` (the search field's key hint and the thread chip as grey pills), `-hbtns`, `-foot`, `-accept`, `-surfaces`, `-buttons`, `-segmented` and `-groups`. The type's size is not a Soft switch (the `--ib-soft-type` 13 px switch it replaced is gone): it is the person's Text size setting (see "Text size" under the window's Settings). Layout corners are one scale tuned in one place (`--ib-lr-pane` 10, `-xl` 12, `-lg` 10, `-md` 9, `-sm` 8, `-xs` 7; owner, 2026-10-17: a subtle step smaller, layout only): panes 10 (was 14), dialogs, the search palette, compose and the question card 12 (16), and a phone's bottom sheets' top corners 12 (16; the dialog corner, owner's ruling q8, one token `--ib-sheet-corner`, which ui's `ImagePeek` and review's `MarkdownViewMenu` sheets match with `rounded-t-[12px]`), tiles, Settings' groups, the header's attachment band, the route chooser, popovers and menus 10 (12 to 14), the read line and callouts 9 (12), row pills, section bands, the folded line, the step box, sidebar, Settings-nav and search rows and the question card's options 8 (10), a tile's icon, menu items and picker options 7 (8 to 11); buttons, chips, badges and inputs keep their radii (`--ib-rN-s`). With every switch `initial` the window is today's, pixel for pixel; a space is Soft, `initial` today's, set per mode in the `:root.light` block), by the space-toggle: a token built as `var(--ib-soft-x) <Soft value>` is invalid while its switch is off, and `var(token, today's value)` falls back (for ui's own drawing, to ui's own values, named: `revert-layer` in a `var()` fallback lays the thread out differently in WebKit on Linux). The panes float on today's ground with the ground switch off: the palette's `--background`, the colour today's sidebar paints, with the panes on `--card`; in the palettes whose background is their card's colour (under 1.035:1: synthwave-84, terminal, and neutral, simple and caffeine in light) the ground is `--muted` mixed into `--background` (`--ib-ground-panes`), and `packages/inbox/softGround.test.ts` fails when a palette is added with no ground to float on. The sidebar's control fills and hovers follow the ground switch (card fills on Soft's tint, today's band and muted hovers on today's ground). The panes switch turns on the 8 px gutters; the window's measures read them from `--ib-gutter` at run time (`paneGutters` in `stack.ts`), so that switch alone moves the stacking widths. Every Soft colour, shadow and surface derives from the palette's theme tokens (no colour literals; Soft's dark tinted ground (the ground switch) and the shadows take `--background` toward black in its own hue through relative colours, and a separation floor keeps grounds and raised surfaces visible where a palette sets `--muted` to `--card`); a palette may replace the derived values with `--inbox-ground`, `--inbox-raise`, `--inbox-shadow-ink`, `--inbox-pane-shadow` and `--inbox-float-shadow`. Text on a raised Soft surface follows the quiet-text switch: stepped toward black on a light surface and white on a dark one (`--ib-card-ink`, `--ib-raise-*`, behind `@supports`) where it is on, else the palette's own text with its quiet text moved as far as the surface moved from the card (`--ib-raise-mfg-keep`), so a raised surface never costs today's contrast. Agent marks are on one size scale (the owner's design-system ruling q12, 2026-10-22): 16, 20, 24, 30 and 44 px, corners 16 → 5, 20 → 6, 24 → 6, 30 → 9 (8 with `--ib-soft-shape` off), 44 → 10, declared once in inbox.css as `--ib-mark-N` / `-r` (corner) / `-g` (the glyph in a tile) and used by every rule that sizes a mark (a bare 16 in list rows, menus and pickers, and the Copy prompt pill; the 30 tile in Settings, Settings → Agents, a message and Drafts; 24 in a message's head row and the @ picker; 20 in the first-run lists, the agent-note dialog and the tag stack, now square; 44 the first-run card, 30 on a phone). A width from one step takes that step's corner. `packages/inbox/agentMarkScale.test.ts` fails on a mark sized any other way, or a width and corner from different steps. No other size. Not agent marks of the scale: the in-text tag mark (`.ib-tg-mark`) drawn over a sent reply's `@`, which follows the `@` glyph (10 to 14 px, `tagHighlight.ts`; the test exempts it), and the harness picker's tab glyphs (`.ib-tglyph`, 14 px: icons in a tab label, like the Settings nav's, not agent marks; the reference's mark table does not list them). Of the non-colour switches (all on): buttons lose their outlines for quiet fills at a 10 px radius (`--ib-soft-buttons`; pills in the thread's foot, `--ib-soft-foot`), the Light / Dark / System control is a faint well (`--ib-soft-segmented`), dialogs, the search palette and compose float with a 12 px radius (`--ib-lr-xl`) and `--ib-float-shadow` (`--ib-soft-float`), small labels (dialogs' headings, Settings' eyebrow, setup headings, the search palette's groups) are 12 px sentence case (`--ib-soft-labels`), Settings' groups are raised cards (`--ib-soft-groups`), and Settings' current section follows the sidebar's current-item switch (`--ib-soft-nav`). On a phone, buttons keep 9 px and the annotations list and New message's sessions stay bottom sheets in both looks. Every declaration falls back to today's value (`var(<switch token>, <today's>)`), so the window with every switch at `initial` is today's pixel for pixel at 1440 px, light and dark, list, thread, file, Settings, search, compose and a phone (proved by screenshot diffs against main), except two named exceptions: the question card's decision row, dropped by a ruling of its own and since gone with Decisions, and the agent marks, which follow the q12 size scale (below) in both looks (the 22 and 36 px marks, the tag stack's 18 px circles and the agent-note dialog's 18 px glyph changed with Soft off too).
- Held order (`packages/inbox/held.ts`, `packages/inbox/settle.ts`; design record "inbox-open-stays-put", variant B, approved 2026-10-12, not in this repo): while any thread is open, the list's rows do not move. Opening a row records the look and unbolds that row where it is (it does not re-sort or leave its section, so focus and the selection stay on it); opening another row while one is open moves nothing; the person's own writes (a pick, a Send, Mark read, Archive) show in place (`refreshHeldRows`, owner ruling 2026-10-11; an archived row shows "Archived" in place through `markHeldRowArchived`, since the window's list leaves archived threads out). Sidebar counts stay live. The list settles (`settleOwn`: the person's own reads and actions take their places) when the thread closes: a thread archived while it was open leaves the list then, and one Mark read sent back to the archive leaves too, while an agent message that brings a thread back from the archive waits behind "N new" like any agent activity; it adopts everything when the folder changes, Settings or What's new open, or Show is pressed. New agent activity waits behind "N new in <project> · Show" and stays there after a close (owner's decision 4: closing settles only the person's own reads and actions); Show brings everything in, and each row it brought in (`showBroughtIn` in `held.ts`: new to the list, or carrying agent activity the row on screen lacked; never one that stayed as it was or changed by the person's own hand) lights up briefly where it landed (owner's request, "inbox-polish" item 6): `data-lit` on the row once the rows have slid into place (`SHOW_LIT_AFTER_SLIDE_MS`; at once under reduced motion), the Show bar's tint on the row's pill held 1.2 s and faded over 1.8 s (owner, 2026-10-20; `@keyframes ib-lit` holds its first 40%, `SHOW_LIT_MS` 3000, then the mark comes off), under the selection and hover, which paint over it with `!important` while the animation keeps running, and under the focus ring; a phone's row takes the same tint. Only Show lights rows: never a close's settle or the first load. The thread the person has open is the exception (design record "inbox-new-in-open-thread", approved 2026-10-12; the `open` argument (`OpenThread`) of `heldNotice`, `refreshHeldRows` and `settleOwn`, which `App.tsx` passes as the open thread, else the one just closed until the list settles, with its row as it stood at the close (`asOf`), so an agent message that lands after the close, in the settle's beat, is news like any other): an agent message that arrives there is never counted or named in "N new", its row takes its state in place (bold on the arrival, not bold once seen on sight), and on close it settles where that state puts it, an arrival the person did not see bringing it back unread (New, or Waiting when it asks) instead of waiting behind Show. Where the thread covers the list (`COVERED_LIST_SETTLES` `'while-covered'`), Back moves that one row only when an arrival there is still unseen (`settleThread`); everything else stays as left. With no thread open, a write (the row's hover Mark read) moves the row at once. One exception to holding still: a click on a browser notification opens its thread and adopts the list as it now is, even with a thread open, because the person was away and the notified thread may not be on screen. The route-change layout effect in `App.tsx` decides when; one `[shown]` layout effect plays the motion and repairs focus.
  - Click Inbox to refresh (the owner, 2026-10-20: "Just click inbox, it refreshes. That way I don't have to refresh the page"; `refreshInbox` in `App.tsx`): a click (or Enter / Space) on the sidebar's Inbox row while the whole list shows, on the project folder the list shows, or on the list header's title (a button inside the `h1`, `data-list-refresh`) reads the list again and adopts it as Show does (held rows settle, rows it brings in light up, "N new" goes), and reads the drafts, settings and an open thread again: what a page reload would bring and nothing more. It records no look, so the rows' New and the tab's count (#2011) stay as the server says; the stale things it clears are the held rows (a Stopped badge or bold row whose thread moved on behind "N new") and a load error line. With a thread open the sidebar row keeps today's behaviour (the thread closes, a new history entry) and the list adopts the read instead of settling a beat later (`refreshPending` skips the settle); the title refreshes beside the open thread and keeps that thread's row in the group it is drawn in, between the same neighbours (`adoptKeepingOpen` in `held.ts`; a thread archived while open, which the window's read leaves out, keeps its row as drawn, Archived, until it closes), so the selection never leaves view. A click while a refresh is reading is ignored, and a read that brings nothing in leaves Show's light on. Signal: on hover (and keyboard focus) while the list shows with no thread open, the Inbox row's icon (or ↻ after the current project's name) becomes ↻ (`data-refreshes`) with the component tooltip "Refresh"; the title shows ↻ beside it on hover; a refresh turns the icon once (`data-refreshing`, `@keyframes ib-refresh-turn` 500 ms, no turn under reduced motion) and the live region says "Inbox refreshed" (or "<project> refreshed"), also when nothing changed. Focus stays on what was pressed. No keyboard shortcut. Tests: `packages/inbox/clickToRefresh.test.tsx` (DOM), `tests/e2e/inbox-refresh.spec.ts` (compiled binary; screenshots in `PLANNOTATOR_REFRESH_SHOTS`).
  - Motion (wide window): on close the list widens at once, then after `SETTLE_BEAT_MS` (160 ms) the rows slide to their places (FLIP over WAAPI: `captureSettle` before the change, `playSettle` after, reads then writes; `translate` 220 ms ease-in-out-cubic, raised with `z-index` while they move; a row that left the rows on screen is a fading copy where it was, 160 ms ease-out, under the moving rows; a row or band that joined fades in after 120 ms, 160 ms ease-out). A new settle cancels the last one's animations and starts from where the rows are on screen; opening a thread inside the beat cancels the settle, and opening one during the slide stops it (`stopSettle`), so nothing slides under the narrowed list. Show and the row's hover Mark read slide the same way without the beat. When the close also gives back the docked sidebar that #1871 held closed beside a file (a window of about 920 to 1050 px), the beat is the sidebar's spring instead (`SETTLE_AFTER_SIDEBAR_MS`, its 500 ms plus 40), so the rows slide from the column's final width rather than changing shape under the slide. Under `prefers-reduced-motion` nothing animates: the close settles in the same frame. Animations carry the id `ib-settle`; the fading copies are `.ib-settle-ghost` (`aria-hidden`, `inert`, no `data-row`/`data-thread-id`).
  - Focus: the window moves focus for the person only after a key (`lastInput` in `App.tsx`: the last `keydown` or `pointerdown`; a `click` that counts no clicks, `detail` 0, is a screen reader or switch press and counts as a key). After a keyboard close, focus that the pane took with it goes to the thread's row; when a focused row leaves the rows on screen (for folded Quiet), focus goes to the row now in its slot (`rowInSlot`: the next on screen, else the one before, else the Quiet band); a keyboard Show (whose line goes away) puts it on the first row it brought in. After a mouse or a tap nothing is moved, so no row the person did not choose holds focus, except a stacked window's Back (#1866), which returns focus to the thread's row as before; that focus is not `:focus-visible`, so the row's Mark read action stays hidden and `E` ignores it. The row's Mark read action shows on hover or keyboard focus (`.ib-rw:has(:focus-visible)`), and `E` acts on a row only when it has keyboard focus (`:focus-visible`), else on the open thread.
  - Where the thread covers the list (a phone, a stacked window), `COVERED_LIST_SETTLES` in `settle.ts` decides; owner's answer (2026-10-12): `'while-covered'`: Back shows the list exactly as left (the row read in place, no longer bold; focus on it after a keyboard Back) and it settles while the next thread covers it (before that thread's look), or on Show or a folder change. `'on-back'` (settle with the slide when the person goes Back) is the one-value alternative.
  - Mark read from inside an open thread: the toast says "Marked read · Moves to Quiet" (phone "Read · Moves to Quiet"), since the row moves only when the list settles; from the row's hover action, with nothing open, it says "Moved to Quiet · “<subject>”" (`markReadToast`'s `deferred`). Its Undo says "Moved back." with a thread open (the row never left), "Moved back to the top." otherwise.
  - Proofs: `held.test.ts`, `settle.test.ts`, the DOM test `openStaysPut.test.tsx` (over `tests/helpers/inbox-dom-server.ts ... news`, which also takes an agent's message on stdin) and `tests/e2e/inbox-open-stays-put.spec.ts` (every frame of the settle sampled; reduced motion; a keyboard Show; a mouse close that hands no focus and lets `E` mark nothing; a phone in WebKit and a stacked window).
- First run (no project yet), "No agent has written yet": "One next step" (design record `.product/approved/inbox-connect-next-step/`, variant C, approved 2026-10-16; not in this repo; `components/EmptyState.tsx`, pure rules in `packages/inbox/connectSteps.ts`). Plannotator's own connections first (Claude Code, Pi, OpenCode: replies come back into the session by themselves), agents through MCP after; MCP stays reachable as "Use MCP instead" and the picker at the end.
  - Read from `GET /api/inbox/agents`. Each agent's state (`connectRowOf`): a plugin host is `ready` (its plugin installed, `reach.kind === 'tool'`, tool on), `tool-off` (`locked` while `PLANNOTATOR_INBOX_TOOL` decides), `mcp-only` (no plugin, connected through MCP: done, but replies don't wake it), `missing` (found, no plugin, not connected) or `absent`; another agent is `mcp` (connected), `connect` (not connected, one click) or `manual` (only a person can add it). One the person turned off, removed or holds its own entry is left out.
  - One large card names the next step (`connectPlan`: turn a tool on, then install a plugin, then give an MCP-only host its plugin, each in Claude Code, Pi, OpenCode order, then MCP agents): "NEXT STEP · 1 of N" / "last one", a title ("Turn on Pi's Inbox tool", "Connect Claude Code with Plannotator's plugin", "Give Pi Plannotator's extension", "Connect Codex", "Connect Cline by hand"), one sentence (Pi and OpenCode's Turn on names the measured cost, `inboxToolCostText`), and one primary: **Turn on** / **Connect** (one click, `POST /api/inbox/agents { agent, reach: true }`; a refusal shows on the card with Try again; the live region says when it applies), or the install command to **Copy** (Claude Code's `claude plugin marketplace add … && claude plugin install …`, Pi's `pi install npm:@plannotator/pi-extension`, OpenCode's `opencode.json` line with an OpenCode 2 / 1 switch; the window never installs) with "Use MCP instead" folded for a host that is not connected (`hostMcpSnippet`, "replies won't come back into the session by themselves"). **Not now** puts a step off for this page load (it stays in Left to do as "later"). A tool locked off, or one config.json turns off by name (`tool.chosen_off`), is never a step (Left to do: "locked by …", "off"). The buttons use `aria-disabled` while saving and focus moves to the next card's heading (to Try it once nothing is left), never to the page. A host with a live session (`GET /api/inbox/sessions`) counts as connected whatever the files say (a project's own settings, `claude --plugin-dir`).
  - Under it, "Already connected" (plugin / extension, "· running now" while a session of that host is live, "next session" after Turn on, "MCP", "MCP, no wake") and "Left to do" (the step "now", the rest, "locked by PLANNOTATOR_INBOX_TOOL=0", plugin hosts "not on this computer"). Nothing found: "FIRST STEP · Connect your first agent" with a Claude Code / Pi / OpenCode switch and that host's install command, no lists. With nothing left: "ALL SET · Your agents reach the Inbox".
  - Try it: **Message <host>** (opens compose to the live session of a ready host, `GET /api/inbox/sessions`; the primary when nothing is left) and "In a new Claude Code or Codex session, ask:" with the test prompt and Copy. Then "Another agent or editor" folded: the harness picker without the three hosts (`OTHER_HARNESSES`), with one verified artefact, one note and a folded "Another way" per harness.
  - The screen moves on by itself: while it shows, `App.tsx` reads the agents again when the window gets focus or becomes visible and every 8 s (at most once per 2 s; the read runs no agent CLI; never over the tailnet), and the live sessions every 5 s while the tab is visible. A numbered read never replaces a newer read or save (`agentsSeq` in `App.tsx`). Over the tailnet (`settings.via`) the agents route is local only: the first step with the commands and "Open the Inbox on the computer to connect agents with one click." A read that failed on this computer says so, with Try again.
  - `InboxAgentRow.plugin` (additive, the three hosts only): whether Plannotator's own plugin or extension is installed (`inboxPluginInstalled`). Claude Code is now found by `claude` on PATH too; its plugin counts as enabled when user `settings.json`, `settings.local.json` or managed settings enable it, or `plugins/installed_plugins.json` records it and no scope says false (`claudeCodePluginEnabled`). Without it its reach is `manual` ("install Plannotator's Claude Code plugin") and Turn on is refused. `tool.chosen_off` (additive): config.json turns the host's tool off by name.
  - Every command names this CLI's absolute path (`mcp_command` from `GET /api/inbox/settings`).
  - Proofs: `packages/inbox/connectSteps.test.ts`, the DOM test `packages/inbox/connectNextStep.test.tsx` (each of the mock's computers, `connectSteps.fixtures.ts`), and `tests/e2e/inbox-first-run.spec.ts` (compiled binary, scratch HOME and stub PATH per computer; Turn on, the auto-advance after an install, shots desktop and phone, light and dark, into `PLANNOTATOR_FIRST_RUN_SHOTS`).
- Settings, in sections (design of record `.product/approved/inbox-settings-tabs/`, approved 2026-10-12; `components/Settings.tsx`): Workspaces' SettingsFrame in the Inbox's scale. A focused page: "← Inbox" on top (`data-settings-back`, back to the last hash that was not a Settings page, so moving between sections never changes where it goes), then a 184 px section nav (eyebrow "Settings"; a `nav` of links with `aria-current="page"` on the section shown; a count on Archived, a dot on About while an update is available, ready or failed, and a warning dot on Devices while a way a phone reaches this computer, or Over your tailnet, is switched on and not working) beside one section's page: an `h1` that takes focus on each section change (not on the first load), a one-line lede, and grouped cards of rows. The Inbox sidebar slides away while Settings is open and comes back on leaving, without writing its cookie (`settingsSidebar` in `App.tsx`; ⌘B there opens it for that visit only). A section change is a new history entry, so Back and Forward walk the sections. On a phone `#settings` is a list of the six sections with a value on each (the theme, the agents with the tool on, phones paired, archived count, store size, version) and a section opens with "‹ Settings", the browser's Back when it was opened from the list (`history.ts`); back on the list, focus is on the row of the section just left. A failed settings read shows "Settings did not load" with Try again. The sections:
  - General: Appearance (Theme, and Text size), and "When an agent asks you" (Desktop notifications with the browser's permission, the blocked warning, and the question sound's row).
  - **Text size** (owner, 2026-10-18: "it's default 14, but I could also go to 13 or 15 or even 12 ... I have to be able to test it"; `packages/inbox/textSize.ts`): a segmented 12 / 13 / 14 / 15 control in Appearance, the Theme control's style, applied at once with no reload. It sets `--inbox-text-size` on the document element (removed at 14), which `inbox.css` reads as the window's one type knob, `--ib-type: var(--inbox-text-size, 14)`: every size `inbox.css` sets is `font-size: var(--ib-fs-N, Npx)` with `--ib-fs-N = max(min(N, 11) px, N px × --ib-type / 14)`, so the whole ramp (rows, subjects, the sidebar, message bodies, question cards, Settings, timestamps, chips, badges) keeps its relative steps, nothing goes under 11 px (a size already under 11 never under its own), and at 14 each size is exactly today's (a screenshot at 14 is byte-identical to the window before the setting). Phone controls' 16 px take `--ib-fs-16-in = max(16px, …)`, so iOS never zooms. ui's drawing inside the window follows through Tailwind's `--text-xs` (never under 11 px) … `--text-5xl` scaled on `.pn-inbox`, ui's fixed `text-[12.5px]` … `text-[15px]` in the `ib-type` layer after Tailwind's utilities, and the code blocks (`pre code.pn-code`); ui's other fixed sizes under 12 px are left as they are. Row and control heights keep today's pitch, so phones keep 44 px targets. Kept in config.json `inboxTextSize` through `POST /api/inbox/settings` `{ text_size }`, and adopted from the first settings read like the theme (never over a pick made on the page first); the `plannotator-inbox-text-size` cookie keeps the last size this browser showed, so a reload paints at it before the read answers. Not on the phone's door. `packages/inbox/softType.test.ts` fails on a bare `font-size` or a token without its floor; `packages/inbox/textSize.test.tsx` (DOM) proves a pick moves a row's subject and a message body and 14 is today's.
  - Agents: the `inboxTool` knob per host ("applies to the next session"; a lock line and disabled switches while `PLANNOTATOR_INBOX_TOOL` decides) and Connect an agent (the compact picker: Other MCP client, the command and `http://127.0.0.1:<port>/mcp`), as they were; the Agents design of its own ships separately.
  - Devices: Phones and "How your phone reaches this computer" (This Wi-Fi, Tailscale; see "Phones"), only while the Inbox serves phones, then "Over your tailnet" with the difference written out ("Your phone's app does not need this"). With phones off, Devices is Over your tailnet alone.
  - Archived: the archived threads, with Unarchive (`components/Archived.tsx`; see "Archived" under "The list").
  - Storage: the store on disk, then per project and thread with Delete thread and Delete project ("Delete? Click again").
  - About: the version with its status, Check now, Update now while an update shows, the two update switches, and "Where things are" (the data folder, the MCP address and command, shell-quoted with `shellLine` so a path with a space copies whole).
- Paste follows the field (`packages/inbox/pasteTarget.ts`, installed once by `App.tsx`): dictation apps (Hex and most others on macOS) insert text as the clipboard plus a synthetic ⌘V, which lands wherever focus is. In the Inbox focus often leaves the field being written in without the person noticing (a click on a question card's choice moves it to that radio, a click on the message text or a reply-box chip to the page, while the reply box stays open with its border), so the dictation used to land nowhere. The window remembers the last 8 text fields that had focus (reply box, a card's note or Other, compose, a comment box, any input) and, on a ⌘V (Ctrl+V off macOS) while focus is on something that takes no text, puts focus back in the newest one still on screen before the browser pastes, its caret where it was (read before `focus()`; a range the person had selected collapses to its end, so the dictation replaces nothing). Chrome runs the paste after the page handled the keydown, and the keydown is never cancelled. Paste is the platform modifier with V by the key's name when that is a Latin letter (so Dvorak's ⌘K, Colemak-DH's ⌘D and Workman's ⌘C on V's physical key are not paste), else by its place (`code` `KeyV`, for Cyrillic or Greek layouts). Left alone: focus already in a text field or a frame; text selected inside an attached file's viewer (`.ib-view`) or a guided review (`.ib-viewer`; code selected in its diff sits in Pierre's shadow root, which Chromium and WebKit report on the document as a collapsed selection at the host's parent whose `toString()` still holds the words, so the words decide, not `isCollapsed`), or any selection toolbar showing (every `[data-pn-annotation-toolbar-row]` is checked: ui's viewer draws the words as a pending highlight and clears the browser's selection; except words selected in a thread message, whose toolbar is an offer: `messageSelectionPending`, see "Comments on the text of an agent's message"), because the person is about to comment on it (a word selected anywhere else, a double-click in a thread message (its comment toolbar showing) or on a choice's label, does not turn this off); and a field that is gone, hidden, disabled, read-only or `inert`, outside an open modal dialog, scrolled out of view (out of the window, or outside the box of an ancestor that clips it, overflow not visible, at its first line), with something drawn over it (the hit test at its first line, `elementFromPoint`, finds neither the field nor something inside it; an element that merely holds the field, its pane or the page, does not count as the field), or outside a full-screen file `.ib-view.ib-full` or a guided review `.ib-viewer` unless the hit test shows it on top (a comment box, the search palette or compose, portaled over the cover; with no hit test the browser cannot tell and it is refused). Proofs: `packages/inbox/pasteTarget.test.ts` (DOM, in test.yml's DOM list: field kinds, the layouts, a selected range, the covers and a box portaled over one, several fields remembered, a file-view selection, code selected in a guided review's shadow-root diff with a guide comment left open, and a word selected elsewhere, the toolbar and a hidden toolbar before a showing one, out of view and clipped out of its pane, a sheet drawn over), `tests/e2e/inbox-dictation-paste.spec.ts` (Chromium: the reply box after a pick, a click on the message and a chip; after a word double-clicked in the message; a selected range kept; a card's note after a pick; a paste aimed at another field; compose; a page with no field used; a file full screen over the thread; its own comment box; search opened and closed; words selected in a file; with image paste, an image pasted after a pick attaching once to the reply box; WebKit: the refocus and caret). It only moves focus on the keydown, so the browser's one paste event then reaches the field and the image-paste handlers around the reply box and in compose (`packages/inbox/compose/paste.ts`): an image pasted with focus off the field now attaches too, and text is inserted once, by the browser.
- **Plain-text paste, inserted by the page** (`packages/ui/utils/pasteInsert.ts`, `installPlainTextPaste`, installed once by the Inbox, plan review / annotate and code review Apps): a workaround for Chrome 155-156 on macOS, to remove once Chrome 157 is stable. It runs ONLY there (`chromiumPasteBugAffected`: the "Chromium" brand of `navigator.userAgentData` at major 155 or 156, else `Chrome/<major>` in the UA string, and a macOS platform), so it turns itself off at 157 and Safari, Firefox and older Chromium (VS Code's webview) keep the browser's own paste: Safari's `execCommand('insertText')` merges with the typing before it, so one ⌘Z after a paste would also erase what was typed. Tests turn it on with `window.__plannotatorForcePlainTextPaste = true` (`FORCE_PLAIN_TEXT_PASTE_FLAG`) or `installPlainTextPaste(win, { enabled, allowUntrusted })`. Chrome 155's post-paste check (CL 8217390) skips its own insertion when the clipboard's sequence token changed during the `paste` event, and an older ClipboardMac race gives the token a second value when an app writes the pasteboard and posts a synthetic ⌘V right away (dictation apps such as Hex, text expanders): the `paste` event carries the text, `beforeinput` arrives empty, nothing is inserted (fixed in Chromium main by CL 8503629, crbug 568453825). So a window-level `paste` listener, bubble phase (every page handler runs first), takes a paste that nothing cancelled, that carries no files and has `text/plain`, aimed at a focused, writable textarea or text-like input (`text`, `search`, `url`, `tel`, `password`), trusted (a script's `paste` event inserts nothing), and not mid IME composition (focus moving or the window losing it also ends a composition, so a lost `compositionend` cannot leave it off): it cancels the browser's insertion and inserts with `execCommand('insertText')` (an undo step; fires `input`, so React's onChange runs), else `setRangeText` plus an `input` event. It does what Chrome would: the selection is replaced, `maxlength` truncates (never splitting a surrogate pair; no room leaves it native), line breaks stay `\n` in a textarea and become spaces in an input. Left native: contenteditable, code editors (`.cm-editor`, `.xterm`, `.monaco-editor`), email and number inputs, and anything under `[data-native-paste]`. It composes with paste-follows-the-field: that moves focus on the keydown, this inserts on the paste. Tests: `packages/ui/utils/pasteInsert.test.ts` (DOM: the rules and the gate) and three cases in `tests/e2e/inbox-dictation-paste.spec.ts`: forced on with the browser's `insertFromPaste` cancelled to simulate the bug, forced on without it (inserted once), and off in this Chromium (the browser pastes).
- Theme: it follows the OS until the person chooses, and the choice is Plannotator's one theme preference (`themePair.mode`: the `plannotator-theme` cookie, and config.json `theme`, which plan review, code review and annotate also read and write), so a choice in either place holds in the other (`packages/inbox/theme.ts`). `configurePlannotatorUI`'s `serverSync` (`inboxThemeSync`) forwards only `{ theme: { mode } }` to `POST /api/inbox/settings` (which merges per field), never the palettes: the store hands over the whole pair, and a tab's copy can be days old or the defaults, so sending it would undo palettes picked in plan review since. Every other server-synced setting stays in cookies. config.json's `theme` beats the cookie, as in plan review, but is adopted once, from the first settings read, and never over a choice made on that page first. WebMCP is off.
  - The toggle (`ThemeToggle` in `components/Sidebar.tsx`): an icon button at the far right of the Settings row, a sibling of the row's button (`.ib-setrow`), never inside it. It writes an explicit light or dark, the opposite of what is shown, named "Switch to light mode" / "Switch to dark mode" with the destination's sun or moon. It never opens Settings and never closes the phone sheet or the peek; the docked sidebar, the peek and the sheet all draw it. No keyboard shortcut.
  - Settings → Appearance: Light / Dark / Match system (native radios as one segmented control), the way back to following the OS.
  - The switch crossfades with theme.css's 150 ms colour transition; under `prefers-reduced-motion` it lands in one frame (`html.ib-theme-instant` held for two frames). Diagrams and code re-theme as in plan review.
  - Phones: the toggle is drawn at 40 px with a 44 px hit area (`::after`).
  - Proof: `packages/inbox/themeToggle.test.tsx` (DOM, the whole window over a real Inbox; each test sets its own cookie, store, config.json and OS start, including a stale tab whose palettes changed on disk and a click before the first settings read).
- On a phone (`PHONE_QUERY` in `packages/inbox/phone.ts`: under 768 px wide, or a touch screen under 500 px tall and under 1024 px wide, so a phone on its side too but not a short iPad window; every phone `@media` block in `inbox.css` spells the same query, and the landscape-only rules use its second half) the window shows one screen at a time, like a mail app:
  - The list's rows are `PhoneRow`: the agent's mark, the project (the agent in one project's list) and the time on line 1; the subject on up to two lines; then the badge, the thread chip, the count and the guided review mark on a line that wraps. A phone never draws the wide row or the two-line row.
  - A thread covers the list. The list stays mounted under it, hidden, so it keeps its scroll. The header leads with `‹ Inbox` (or the project), then Mark read, and ends with Archive at the right edge, where the close was. A file covers the thread in the one full-screen mode (see "Attachments and annotation"): its toolbar sits bottom right with 44 px targets (‹ Back to the thread, the pen, the comment count, ⋯, Hide tools), the count opens the annotation panel (ui `presentation="embedded"`) as a bottom sheet, and Hide tucks the toolbar into a 44 × 52 px handle you tap.
  - New message's sessions and the annotations list are sheets from the bottom edge. Primary targets are 44 px. Inputs are 16 px, so iOS does not zoom. Edges clear `env(safe-area-inset-*)`. `trackKeyboard()` keeps `--ib-vvh` at the height the keyboard leaves, so the reply foot sits on the keyboard.
  - `.pn-inbox[data-view]` names the screen on top (`list`, `thread` once loaded, `file`, or the page).
  - History is a stack on a phone (`packages/inbox/history.ts`). Each screen's entry records the screen it was opened from. On a phone, Back, Escape and close are the browser's Back when they lead to that screen, so the iOS swipe and Android's back agree with them. A second press before that Back lands does nothing, so a double tap never leaves the Inbox. Otherwise, and always on a desktop, they push the screen as a new entry, so the browser's Back reopens what was closed, as before.
  - On its side, the Comments sheet takes the file's height. A file has no stepping bar or reply strip on a phone: ⋯ and the sheet's foot hold the position, and the sheet's foot says what rides the next Send with Write the reply.
  - The toast spans the window above the thread's foot whatever the foot's height (`components/Toast.tsx` measures it, so an open reply box too): one 44 px line, "Read" in place of "Marked read", Undo with a 44 px target, no Reply (the foot has it) and no Z hint; an error wraps.
  - Small controls keep their look and take a 44 px tall hit area (an `::after` box): the reply's Keep open / Skip them, and the file's toolstrip, Global comment and Copy file (ui). ui's toolstrip buttons clip their sliding label with `overflow`, so on a phone they clip with a `clip-path` that reaches 8 px above and below and 4 px at the sides instead (drawn the same, the keyboard focus ring whole). Side by side controls cannot all be 44 px wide; they keep their widths.
  - Proved in WebKit (iPhone 15) and Chromium (Pixel 7) by `tests/e2e/inbox-mobile.spec.ts`. The surface the native apps host (`packages/inbox/surface`) is a different thing and is not affected.
- In a window too narrow for two panes that is not a phone (an iPad upright, a narrow desktop window, a Stage Manager tile; `packages/inbox/stack.ts`), the pane on top covers the one under it:
  - A thread covers the list when the list's 380 px column and a 440 px thread (the column a thread keeps beside an open file) do not both fit in `.ib-main` (the window less the docked sidebar's target width). With the default sidebar that is under about 1052 px, so an iPad on its side (1080) keeps the list beside a 468 px thread, as iPad Mail does, and an iPad upright (810) stacks.
  - An open file covers its thread, full screen, when the thread's 440 px column and a 480 px file do not fit the window (under 920 px; 944 with the Soft panes' 8 px gutters).
  - `.pn-inbox[data-stack]` holds `thread` and/or `file`, measured before paint when the route or the sidebar changes, and by a ResizeObserver otherwise.
  - The desktop chrome stays: the docked sidebar, the wide list rows, the desktop headers (a stacked thread's leads with `‹ Inbox`, or the project, in place of its close; an open file is full screen, its toolbar led by Back to the thread in place of Side by side). The list stays mounted under a stacked thread, at its own width, so it keeps its scroll.
  - Focus follows the screen: a thread that covers the list takes focus to `‹ Inbox`, and closing it puts focus back on the row of the thread just closed.
  - A resize across the stacking width never drops focus to the page. Shrinking with a thread open while a row of the list has focus hides that row under the pane, so focus goes to `‹ Inbox` and Back returns it to that row (a hidden row cannot hold focus). With only the list on screen the row keeps it. Growing back out, with the pane's Back focused, puts focus on the row beside it (the one focus came from, else the open thread's).
  - History: closing a stacked thread back to the list is the browser's Back when it was opened from there (`closeTo`, as on a phone), so an iPad's swipe back and `‹ Inbox` agree. Every other close, and every close in the two-pane layout, pushes a new entry as before.
  - A window at 1280 px and over with the default sidebar never stacks, so it is drawn exactly as before (a pixel comparison against the previous build shows no change). Proved on an iPad upright (WebKit, 810 by 1080, touch), a 900 px and a 1000 px Chromium window and an iPad on its side (1080) by `tests/e2e/inbox-mobile.spec.ts`, and the widths by `packages/inbox/stack.test.ts`.

**Questions and Send.**
- A row opens the thread beside a narrowed list and records a look.
- The thread reads as email: the subject, the sender row, and each message through `Viewer` with the `answerOnly` seam. There are no comments on the text and no document actions, and the question cards keep their handlers.
- A click on a card is a pick, saved at once (`POST /api/inbox/messages/:id/picks`, serialized per thread, a stale revision `409 question_revision_conflict`). The card's footer says "Picked 10:51 AM · in your draft" (its tag "Draft"), "Sent 10:52 AM", "Skipped · 10:52 AM" (the person pressed Skip them; see "Mark read and the Send that skips") or "Closed unanswered when you marked it read · 10:52 AM". "Waiting on this answer · Holds up N" sits under the asking message.
- Only an open or picked question can be answered: a card whose question is sent, closed (a Mark read, the archive) or superseded draws read-only (no ticks, no Accept recommended, no Skip), even while another question in the same message is open (`answerLocked` in `Thread.tsx`, through `Viewer`'s `questionReadOnly`; proof `packages/inbox/sentQuestionLocked.test.tsx`).
- The foot:
  - "Send · Edit draft · Re-ask … Draft · 2 picks · <skip chip>" when picks, comments or kept words wait (see "Reply drafts and the Draft label"; approval "thread-foot-status-right", option A): the buttons stay on the left in today's order and the draft status with the skip chip sits at the row's right end, after the buttons in the DOM (Send and Edit draft name it in `aria-describedby`). Where the row cannot hold both (beside a file, a stacked window, a phone) the status takes its own line ABOVE the buttons, never between them: two flex items, `flex-wrap: wrap-reverse` with `space-between` (`[data-foot-row]` > `[data-foot-buttons]` + `[data-foot-status]`, CSS only). The error after a failed Send renders above the button row (`data-foot-error="above"`), in the closed foot and the open reply box.
  - The reply box with its "N picks" and "N annotations" chips. Mod+Enter sends. The answers picked on the cards are listed live inside the box under the words (`ReplyAnswers`, `packages/inbox/components/ReplyAnswers.tsx`: "Your 3 answers go with this reply", one row per answer, `Q2 <prompt> → Yes`, a saved pick or one being saved, which the "N picks" chip counts too; a cut prompt or answer shows whole in a `Tip`; answers to several messages are grouped under each message, "go with your replies"; a row jumps to its card; on a phone about two and a half 44 px rows, then it scrolls), so a pick made while the person writes shows at once. They are never written into the words: Reply / Edit draft opens the box with the kept draft or nothing (until 0.28.25 it seeded a one-time "Prompt: answer." summary of the picks, which went stale as the person picked on and reached the agent twice, beside the answers section; the owner, 2026-10-21, "When i edit a reply, and then add new answers... do they get added to the reply? Because I dont see them"). Proof: `packages/inbox/picksWhileComposing.test.tsx`. Its chip row wraps inside the box (`.ib-rfoot`): a chip never shrinks or breaks its label, and the skip chip's sentence wraps inside itself only where the box is narrower than it (a phone). Before this, in the 440 px thread beside a file, "3 annotations" broke over lines and spilled out of the box. `tests/e2e/inbox-attachments.spec.ts` checks the chips stay inside the box at 440 px, 1440, 810, 900, 390 and 320. The no-wrap applies to the chips only, never to the "N annotations ride this reply" list (`.ib-annpop`), whose quotes and comments wrap; where that list would run past the window's right edge it lines up with the reply box's right edge (`--ib-annpop-shift`, set by `AnnotationsChip`); the same e2e checks both at every width.
- A Send is `POST /api/inbox/messages/:id/reply`, ONE per agent session it answers (owner approval "inbox-explicit-skip", 2026-10-21: "answering questions across messages should just become one reply"), with an idempotency key per (Send, session), kept for a retry. Before it, a Send posted one reply per message, so an agent that asked across 8 messages woke on the first reply and acted before it saw the rest. `sendTargetsOf` (`packages/inbox/sendTargets.ts`) groups the picks waiting, and the questions chosen with "Skip them", by the session of their message (`author.host` + `author.session`; a message with no session is a reply of its own); each group posts to the latest of that session's messages it touches, and every pick or skip on another of its messages names it: `questions: [{ message_id?, key, revision, answer? }]`, `skip: [key | { message_id?, key }]` (`message_id` absent = the route's message). The words, annotations and pasted files ride the reply of the session that wrote the latest agent message (that group goes last), or a last reply to the latest agent message when that session has nothing else to send. The store (`sendReply`) checks each `message_id` (`sendMessageOf`: the same thread and the same agent session as the reply's message, else `422 validation_error`; a message the archive closed, `409 thread_resolved`), plans each message's answers with its own revisions (a stale one refuses the whole reply, nothing written), and writes ONE person reply `reply_to` the route's message, marking every question it sends with that reply's id. Re-ask's picks-only reply (`reaskTargets`' `picks`) is one reply the same way. The reply's body, in this order: its first line (`Answered N questions.`, `Skipped N questions.` or `Answered N questions, skipped M.`, counted across every message by the answers section's own rule, so it never disagrees with "x of y answered"), the person's words, the still-open line, the answers section, then the annotations' feedback. The answers section is `formatQuestionAnswersSection` for the one message the reply answers; when the answers are on several messages, or on another message than the one replied to, it is one "Answers to your questions" section with a `### Your message <message id>` heading per message, in thread order, each with its own "x of y answered" line and its questions numbered as its cards are (`composeInboxReplyBody`'s `messages` and `replyTo`, `packages/core/inbox-questions.ts`), so the agent can tell which "Q1" is which. The still-open line (approval "inbox-words-only-reply", 2026-10-13, extended by "inbox-explicit-skip"): counts every question the replied-to message's session asked in this thread that is still open, or picked and not sent, leaving out the ones this reply sends (another session's questions are never counted, and a message with no session counts only its own); none when nothing is left open. A reply that answers or skips something says "You have N other questions open in this thread. They stay open; the person will answer them in the Inbox. Don't re-ask them." (`inboxOtherStillOpenLine`; for one: "You have 1 other question open in this thread. It stays open; …"). A reply that sends no answer and no skip (words, annotations, or both) keeps its own wording, with no first line and no answers section: "No questions answered yet; all N are still open. Don't re-ask them; the person will answer in the Inbox." (`inboxStillOpenLine`; for one: "No question answered yet; it is still open. Don't re-ask it; …"; when an earlier reply already answered some: "No new answers in this reply; N questions are still open. …"). `INBOX_STILL_OPEN_LINE` matches every form, and the folded line's `replyWords` cuts the reply there, so a snippet shows only the person's words; `withoutAnswersSection` (read_thread's earlier messages) cuts the grouped section too, and search's `inboxSearchReplyText` cuts at the still-open line as `replyWords` does. `wait_for_reply`'s structured `questions` and its facts line cover every message the reply answered or skipped on (its `reply_to` and each other message holding a question the reply sent), each question with its `message_id`. A retried Send keeps each reply's key unless its words, files or comments changed or it carries a pick or skip the last try did not (`replyKeysToRenew` in `sendTargets.ts`), so a new answer is never dropped by a replay. When the chosen session ends mid-Send, the route's error counts agents: "N of M agents got their reply". The wake text is unchanged and carries this body. Plan review's export (`formatQuestionAnswersSection`, `packages/core/question-block.ts`) is untouched.
- The sent questions are marked before the reply line lands. When the reply line never lands, they read as picked again, so a retry never reads "already sent" with nothing sent.
- After a Send, the line under the person's last reply or message says where it is (`deliveryLine`, `packages/inbox/deliveryLine.ts`; the owner's request 2026-10-16, "it should say this message is queued up … and then maybe an option just to send it immediately"). For a session whose connection wakes it (a reply to a message with `wakes`, or a message with `to`), the window reads that session's connection every 3 s (`GET /api/inbox/threads/:id/sessions?asker=<session>`, the additive `asker.connection` = `{ busy, idle_since, send_now, waits }` while it polls, null when it does not): "Undelivered 3 min · Claude Code is working · goes in by itself in 2 min" with **Send now** (`data-send-now`, only while `send_now`; see the next bullet but one; "Queued · Claude Code is working; it gets this when its turn ends." in the few seconds before the server starts the reply's clock), "Sending to Claude Code…" while idle, "Queued for Claude Code; it gets this as its next turn." when the connection does not say (or an older Inbox), "… when its session is back." when it does not poll (also after Send now was pressed or the Inbox marked it: a session gone after the mark is never "Sending … now"), "Sending to Claude Code now…" once Send now was pressed (`deliver_now_at`) while the session polls. A reply to an agent that only reads the thread (MCP, OpenCode 1) reads "Saved for <agent>. It sees it when it next reads this thread." Then "Delivered to <agent>, 10:52 AM", unchanged. The ended-session and Not delivered lines are unchanged.
- **Undelivered replies go in by themselves** (owner approval "inbox-busy-agent-reply", 2026-10-21, behavior and look; `.product/approved/inbox-busy-agent-reply/`). A reply, a message or a Re-ask note that waits on a BUSY session (never the note carrying a 👍, below) goes into the running turn by itself after `INBOX_AUTO_SEND_AFTER_MS` (5 min, `packages/core/inbox-delivery.ts`), exactly as if the person pressed Send now: `deliver_now_at` plus `deliver_now_by: "auto"` (a person's press writes `"person"`; on the message, or on a tag for a tagged session's own copy) and `wait_started_at` (when it began to wait on the busy session), and the bridge command's `now: true`, delivered into the turn per host as below. Only where Send now is possible (the session polls `busy: true` and `send_now: true`); elsewhere it keeps waiting and the line says why. **The clock is the server's, never the item's `created_at`** (`createInboxLiveSessions`' `trackWaits` in `packages/server/inbox-sessions.ts`, in memory): each item a session is handed (`pendingReplies`) gets `since` the first time the server sees that session busy while the item waits for it (the "Undelivered N min" number, row and band alike), and `autoSince` the first time it also sees the session able to take it mid-turn (`send_now`; the countdown "goes in by itself in N min" runs from it, so a session that becomes able after a `/reload-plugins` still gives the person the full 5 minutes). Clocks are looked at on every poll and `state` event, when a person's item is written, and every `INBOX_AUTO_SEND_SWEEP_MS` (5 s). A delivered item, or one moved to another session ("Send to another session", which also clears `deliver_now_at`, `deliver_now_by` and `wait_started_at` in `readdressMessage`), leaves the old session's clocks; a session that stops being live loses all its clocks; an Inbox restart starts every clock again. So a reply left for a session that ended, or a message moved to a busy session, waits its whole 5 minutes from when that session is busy, and the wait is never shorter than 5 minutes (a restart can make it longer). The sessions route carries the clocks as `connection.waits` (`{ [item id]: { since, auto_since } }`); the store reads them through `InboxDeliveryPresence.waitOf` for the rows. `InboxStore.autoSendDue(session, { afterMs, tags, clockOf })` marks every pending item whose `autoSince` is at least the wait ago and that has no `deliver_now_by` yet; the server calls it for every live busy `send_now` session on the sweep and on each such session's poll (`packages/server/inbox.ts`). Never twice: `deliver_now_by` stays when a failed attempt (`send_now_failed`) clears `deliver_now_at`, and the Inbox never tries again by itself (the person's Send now still can). Never for the Inbox's set-aside and reopened notes. **A 👍 waits for the turn to end** (owner's decision 2026-10-21, approval "inbox-busy-agent-reply": "a thumbs-up isn't worth interrupting a turn"): the note carrying a 👍 never goes in by itself. One switch, `INBOX_AUTO_SEND_ACK_NOTES` (`false`, `packages/core/inbox-delivery.ts`), decides it in the server's marking (`autoSendDue` skips `ack_of` notes), the row (`rowDelivery`: no `auto_send_at`) and the 👍 line (`ackPillLine`: no countdown) alike. **How it went in:** when the connection reports `delivered` for an item the Inbox marked, the server writes `delivery.into_turn` (additive): false when the session was seen idle after the mark (its own Ask this session question held the turn, so the item went in when the turn ended), true otherwise (`live.deliveredIntoTurn`). `startInboxServer` takes `autoSendAfterMs` / `autoSendSweepMs` (tests), `plannotator inbox` the testing knob `PLANNOTATOR_INBOX_AUTO_SEND_MS` (see the env table). The look (one rule for row and thread: `inboxDeliveryState`'s `wait` / `autoAfterMin` / `turnEnded`, inputs `waitingSince` (the server's `since`, after the mark `wait_started_at`), `autoSince`, `nowBy`, `nowAt`, `intoTurn`, `autoSendAfterMs`; the window gathers them with `waitInputs` in `deliveryLine.ts`): the row's additive `delivery.waiting_since`, `steerable`, `auto_send_at`, `auto_after_min`, `turn_ended`, and the sessions route's `connection.auto_send_after_ms` and `waits` (absent from an older Inbox: no countdown). A session that stops polling wins over a mark: the line reads "… when its session is back.", never "Sending … now" (`connection === null` is decided before `sendingNow`). The list row draws "Undelivered N min" in place of the count (`UndeliveredBadge`, `components/Undelivered.tsx`; blue `--ib-wait-*` while it can go in now, grey `data-stuck` when not; whole minutes, "Undelivered" under one; its own 5 s clock, so a memoized row is not rendered again); the wide and two-line rows offer **Send now** on hover and keyboard focus only (`data-row-send-now`, a sibling of the row like Mark read; never on a phone row). Under the reply the band (`UndeliveredBand`): "Undelivered 3 min · Claude Code is working · goes in by itself in 2 min" ("in under a minute"; "it gets this when its turn ends" when it will not) with a filled Send now; grey with no button and no countdown when it cannot go in sooner, then why and the fix (`StuckReason` in `RestartNote.tsx`: the older-plugin sentence with `/reload-plugins` and Copy, the update steps, else "It can't go in sooner."). Tagged sessions' lines say the same; a 👍's line says how long it waited and "it gets this when its turn ends", with no countdown and no Send now. After: "Delivered to Claude Code, 1:53 PM · went into its turn by itself after 5 min" (`data-auto`, the delivered tick's colour) only when it went into the running turn; "Delivered to Claude Code, 1:53 PM · went in when its turn ended" (`TURN_ENDED_TEXT`) when `into_turn` is false. "Not delivered" for a gone session is unchanged. No toast, no shortcut. Tests: `packages/shared/inbox/store-auto-send.test.ts` (injected clock: never without a clock, not before, at 5 min, once, the countdown from `autoSince`, a failed attempt, a move to another session, notes, the 👍 switch, tags, the row, `turn_ended`, a session gone after the mark), `packages/server/inbox-auto-send.test.ts` (the server's timer with a short wait: the poll's `now`, never without `send_now` or for an idle session, a restart starting the clock again, a reply left for an ended session, a message moved to a busy session, `into_turn`), `apps/hook/server/inbox-auto-send-knob.test.ts`, the DOM test `packages/inbox/undelivered.test.tsx`, `tests/e2e/inbox-undelivered.spec.ts` (compiled binary: the badges and hover, the bands with the page's clock moved forward, going in by itself with a one-minute knob across a restart, the live timer; 1440 light and dark, a phone).
- **Send now** (`POST /api/inbox/messages/:id/send-now`, window guards; door 7.58): the store writes `deliver_now_at` on the message (`requestDeliverNow`; a second press writes nothing; `already_delivered`, `not_addressed`), after the server checked the recipient's connection polls now and said it can deliver into a running turn (`send_now_unavailable` otherwise; `recipientOf` names the session). The Inbox writes the same mark by itself (`deliver_now_by: "auto"`) for a reply, message or Re-ask note that waited 5 minutes on a busy session that can take it (see "Undelivered replies go in by themselves"); never for the note carrying a 👍, which waits for the turn to end (owner's decision 2026-10-21). The bridge command carries `now: true` only on a poll that says `send_now` (so a connection that cannot steer never skips its idle wait), and a held poll answers at once. Once a reply carries `now`, the connection delivers the waiting replies at once, OLDEST FIRST (an urgent reply never overtakes an older one to the same session): the Claude Code mod as a user row in the running turn (`$.session.append`, the one way a plugin puts words into a running turn: `$.prompt.submit` never folds into one); Pi as `sendUserMessage(..., { deliverAs: "steer" })`, delivered when Pi starts it (`message_start`); OpenCode 2 as `session.prompt({ delivery: "steer" })`, delivered only on `session.inbox.delivered` for that row id (a `session.inbox.delivery.changed` to `queue` for it counts too: OpenCode will deliver it); when the run ends first and the row is not delivered within `STEER_IDLE_GRACE_MS` (3 s after the end event), it is sent again as a queued turn ending with `inboxRepeatLine`. There is no cap while the run goes on (a tool call may take minutes, and OpenCode promotes the row at the run's next step): a steer still waiting is looked at every `STEER_WATCH_MS` (2 s), a run with no event for `RUNNING_CROSS_CHECK_MS` (20 s) is checked with `session.wait` (idle: the grace starts), and after the event stream ends the row waits until `session.wait` says idle, then counts as delivered when `session.context` holds it (by its id, or a user message with its text), else the queued turn goes. OpenCode cannot withdraw the steer row and promotes it with that turn (#1734, live on 2.0.22), so the plugin's `context` and `generate` hooks drop the later of the two copies from every model request (`dropInboxDuplicates`, the way they drop the session-URL notice; pairs kept for the plugin's life, at most 200); a later copy that is its message's whole content is never removed (the request would end on an assistant message: a wasted turn or a provider error) but replaced by `inboxRepeatPointer`, the same text in every request so the prompt prefix stays stable; idle, as a turn at once. Pi: Esc during the run puts a steer that has not started into the editor (Pi's `restoreQueuedMessagesToEditor`); when the steer's watchdog then finds the session idle without it, the extension takes the reply's exact text back out of the editor (`editorWithout`, the person's own words and other queued messages kept; an edited copy is left alone) and the reply waits for idle and arrives as a follow-up, so it is never sent twice. Pi and OpenCode never steer into this session's own Ask question either: their wake target's `canSteer` is false while it runs (Pi: `isAskActive`; OpenCode 2: `isAskTurnActive`, a per-session mark the session bridge holds while its Ask turn is in progress), so the poll and the wake's `state` events (`InboxWake` now carries `send_now` on them, as the mod does) stop offering Send now and a pressed reply waits for idle. The mod: the decision is taken right before the append, after every await of the delivery (fresh check, lease, claim), from `steerableTurn` = the running MAIN turn that is not this session's own Ask question (so an Inbox reply never streams into the Ask AI panel; while the Ask question runs or waits queued, Send now waits for idle); a turn that ended by then means a turn instead; after the append, a turn that ended or changed means one short pointer turn at once (`inboxSentNowFollowUpText`), else the row is tied to that turn id and a turn that ends with no model request after it gets the pointer (several per turn). A refused append (or a failed steer on Pi or OpenCode) posts `send_now_failed`: the server clears `deliver_now_at` (`clearDeliverNow`), the line reads queued again, and the reply waits for idle. A connection says it can with the poll field `send_now: true` (`INBOX_SEND_NOW_POLL_FIELD`): the mod on an engine at least `SESSION_APPEND_MIN_ENGINE` (2.1.301, the first build whose published API documents `$.session.append`; decided from `$.session.version()`, because `claude plugin validate` refuses reading `$.session.append` as a value) until an engine refuses a row; Pi where the wake target has `steer`; OpenCode 2 while its event stream runs (`canSteer`, how a steer's delivery is seen). OpenCode 1 and older connections never, so Send now is never offered there. Nothing is ever aborted. Claim-once holds: the same claim folder and lease as a normal delivery; the mod refreshes `alive` for the claim it is submitting under, so another process never reports a reply this one is still delivering; a claim it won but cannot use at once (its own Ask question took the turn, a turn started right after the claim, or the append was refused) it gives back (`INBOX_RELEASE_SCRIPT`: the claim folder removed while still its own and neither delivered nor reported), and a process that lost that claim takes the reply back as pending when the folder is gone, so the process the person works in delivers it even when the lease moves while the turn runs. The mod's `send_now` (poll and `state` events) is true only while a reply could go in now, so while this session's own Ask question holds it Send now is not offered and a pressed one reads "Queued", not "Sending … now". The line under the reply also reads "Queued" for a message sent without the wake mark (the stdio shim run inside Claude Code) while its session's connection polls. Tests: `packages/server/inbox-send-now.test.ts` (routes, guards, the poll, `send_now_failed`, agent-link's steer and order), `apps/hook/hooks/mod/inbox.test.ts` 12 to 17 (the mod against a real Inbox: into the turn, the pointer turn, the turn ending before or during the append, the Ask question running or queued, oldest first), `apps/hook/hooks/mod/send-now-engine.test.ts` (the version gate), `apps/hook/tests/register.test.ts` (the engine harness: the row through `$.session.append`; an older engine never offers it), `apps/opencode-plugin/inbox-v2-wake.test.ts` (the steer confirmed by its delivery, and the fallback; a tool call longer than the old 60 s cap with no fallback; the event stream ending mid-run, then the row found in the context or the fallback once idle; the pointer for a whole-message copy), `apps/opencode-plugin/opencode-session-bridge.test.ts` (the Ask turn mark), `apps/pi-extension/inbox-send-now.test.ts` (the steer, delivered on `message_start`; no Send now during an Ask; `editorWithout`), `apps/hook/hooks/mod/inbox.test.ts` 16b (a claim it cannot use given back) and 16c (two processes: the lease moves while the claimant's turn runs, and the other process delivers once), `packages/inbox/deliveryLine.test.ts`, the DOM test `packages/inbox/sendNow.test.tsx`, `tests/e2e/inbox-send-now.spec.ts` (compiled binary; light, dark and a phone).
- **A session that needs a restart after an update** (owner approval "restart-warning", 2026-10-19; design record not in this repo; `packages/server/inbox-restart.ts`). The Claude Code mod reports what it loaded on every bridge poll, additive: `plugin: { version, root, loaded_at }` (plugin.json's version read once from `${$.plugin.root}/.claude-plugin/plugin.json`, the folder, and the module's load time; `readLoadedPlugin` in `register.ts`, `Host.loadedPlugin`), ALWAYS, with `version` or `root` null when it could not read them, so a poll without `plugin` only ever means a mod older than `INBOX_PLUGIN_REPORTS_LOADED_SINCE` (0.28.24, in core; this must merge before the version bump to it); `engine` (`$.session.version()`'s `base`, `Host.engineVersion`); and `session_folder` (`$.session.root()` read once when the link starts, so a later `/cd` does not move it: the folder `claude --resume` runs in; `project_path` stays the current working folder). Pi sends `plugin: { version }` (`InboxWakeTarget.pluginVersion`, the extension's package.json), never inside Oh My Pi (`detectPiHost`), which updates differently; OpenCode sends nothing yet. The Inbox reads Claude Code's plugin registry (`<CLAUDE_CONFIG_DIR>/plugins/installed_plugins.json`, only `plannotator@plannotator`, the repo marketplace's name, so a fork is never judged against; at most every 2 s through the Inbox's agent environment) and judges each session against the record a restart would load (`chooseClaudePluginInstall`: the record whose `installPath` is the folder the session loaded, then a project- or local-scope record whose `projectPath` holds the session's folder, the deepest, then the user record). A session is outdated (`claudeSessionOutdated`) when what it loaded is not what a restart loads: the versions differ, its folder is not `installPath`, or it loaded before BOTH the record's `lastUpdated` and the install folder's last change (`pluginFolderChangedAt`: `.claude-plugin/plugin.json`'s mtime, else the folder's), an update that reused the folder and the version (`lastUpdated` alone also moves for a project-scope install of the same folder with no new code; whether Claude Code ever reinstalls into the same folder was not verified live). Every path compares by its real path (`realish`: the deepest existing part realpath'd), so a symlinked `~/.claude` or CLAUDE_CONFIG_DIR neither hides nor invents a difference. A session that sends no `plugin` (a mod older than the field) is outdated with its version unknown once the installed plugin is at least `PLUGIN_REPORTS_LOADED_SINCE` (0.28.24). A plugin loaded from outside Claude Code's plugin folder (`claude --plugin-dir`, and a local or directory marketplace, which Claude Code loads in place) reloads that folder on restart and is never outdated. When the installed plugin is itself behind this Inbox's release, a restart alone does not help: `fix: "update_plugin"` with `update_command` (the install script's two commands, `--scope user`); otherwise `fix: "restart"`. Pi behind this Inbox's release is `fix: "update_extension"` (`pi update --extensions`, then `/reload`). Where it shows: (1) `asker.connection` gains additive `outdated: { loaded, installed, fix, update_command? } | null`, `engine` and `restart_command` (`cd <folder> && claude --resume <session>`, the folder being `session_folder` (else `project_path`) with `~`, quoted when unusual; `claudeRestartCommand`); the line under a reply (`restartNote` in `deliveryLine.ts`, drawn by `RestartLine` in `components/RestartNote.tsx`, the approved "Steps") shows ONLY while that session works, has no Send now, and is outdated with a loaded version that is unknown or older than `INBOX_SEND_NOW_SINCE` (0.28.24, the first release with Send now: a session on that or newer that lacks Send now lacks it for another reason, its own Ask question or a refused row, so the line never blames the plugin), and never for an engine older than Send now's floor (`inboxEngineTooOldForSendNow`, a copy of `SESSION_APPEND_MIN_ENGINE` pinned by `send-now-engine.test.ts`; the owner chose to say nothing about the engine itself, 2026-10-19). Its shape (simplified 2026-10-21, owner: "simple buttons win"; `ReloadLead` and `Fold` in `components/RestartNote.tsx`, shared with Settings): one lead line, "Type /reload-plugins in that Claude Code to get Send now." with a Copy that copies `/reload-plugins` (the owner checked live that `/reload-plugins` loads the new plugin in place and keeps the session). With `update_plugin` the lead is two steps: the update command with Copy, then `/reload-plugins` with Copy. The manual path is folded behind "Still no Send now after reloading?" (`aria-expanded` / `aria-controls`): `/exit` in that Claude Code, then the resume command with Copy, the warning that `/exit` stops the running turn, and "Your reply waits here." `/restart` is never mentioned. Each Copy says so in a polite live region ("/reload-plugins copied.", "Restart command copied."). (2) The list model and the event stream's `status` carry additive `restart_claude_code` (live Claude Code sessions whose fix is `restart`; pushed when it changes, checked every 5 s): the sidebar's "Reload Claude Code N" (`data-restart-sidebar`, a button under the Update button / "What's new in X", above Settings; in the navigation sheet on a phone) opens Settings → Agents and goes away by itself once they reload or restart; not on a page opened over the tailnet, where Agents is local only. (3) `GET /api/inbox/agents` carries additive `sessions: { "claude-code"?, pi?, opencode? }` (`InboxHostSessions`: `running`, `outdated`, `installed`, `update_command`, `sessions: [{ session, project, folder, started_at, busy, plugin, outdated, restart_command }]`, newest first, live polling sessions only); Settings → Agents shows an "Open sessions" row per host ("3 running · 2 on plugin 0.28.21"). For Claude Code sessions that need it, a box under the row leads with the same `ReloadLead` ("Type /reload-plugins in each of these N Claude Code sessions." with Copy; with `update_plugin`, the update command first), then the sessions as a short list with no buttons (project, "since <time>", idle or working; two in one folder are told apart by start time), then "Still listed after reloading?" folded, which opens `/exit` and a Copy restart per session (named "Copy restart: the command that restarts the <project> session started <time>"). Pi and OpenCode keep a one-line sub. the head reads "Connected · 2 need a reload", the Agents nav gets the warning dot, and Settings → Agents re-reads every 5 s while open. Only sessions that poll are seen (the Inbox tool on; one process of a two-process session). No keyboard shortcut. Tests: `packages/server/inbox-restart.test.ts` (every rule, the registry's shapes, the command, and over a real Inbox with a scratch `CLAUDE_CONFIG_DIR`), `apps/hook/hooks/mod/inbox-loaded.test.ts` (the poll fields over the in-memory Host), `packages/inbox/deliveryLine.test.ts`, the DOM test `packages/inbox/restartWarning.test.tsx` (the whole window over `tests/helpers/inbox-dom-server.ts` `restart`).
- No tool answers, approves or sends for the person.
- **Re-ask** (approval "inbox-reask", 2026-10-20; `.product/approved/inbox-reask/`): the person asks the agent that asked for its questions still open in the thread again, together in one new message with fresh context (the open questions spread over several messages, or went stale).
  - The button: **Re-ask** (refresh icon) beside Reply in the thread's foot (`data-reask`, named by its text; 44 px on a phone), shown when two or more questions wait (open or picked, not sent) and at least one has no pick (`reaskOffered`, `packages/inbox/reask.ts`). A session is left out while its note waits (no message of that session after its latest note) and right after it answered one (everything it still has open sits in its one message that answers the note). Tooltip: "Ask Claude Code to ask the 3 open questions again, together in one message with fresh context. Questions that no longer apply are closed; until then they stay open here." No keyboard shortcut.
  - One note per session (owner's rule 3): `reaskTargets` groups the thread's live agent messages by session and posts `POST /api/inbox/messages/:id/reask` (`{ serverSession?, idempotency_key, to? }`, window guards; door 7.61) to each session's latest message with a question waiting, one key per target kept for a retry. A pick still being saved is awaited first. A session with picks not sent and nothing open gets no note: the same press sends it a plain reply carrying the picks as answers (`kind: 'picks'`, one reply per message, its own kept key), so a Re-ask never strands a pick. A session is hidden from Re-ask only while a note of its waits by rule 2a (its session has not written since, and something it lists is still open); a note that went to another session (the asker ended) stops hiding it once that session wrote, so whatever it neither replaced nor superseded stays re-askable.
  - The store (`InboxStore.sendReask`) writes one person message, `reply_to` that message, with `reask: [<message id>/<key>]` (the session's open questions in the thread, from every live message of that session) and a body from `composeInboxReaskBody` (`packages/core/inbox-questions.ts`): what to do ("Please ask your 3 open questions in this thread again, together in one new message…"), the list by id and prompt, the rule (still needed: ask again with today's context and a `Replaces: <id>` line in its block; no longer needed: its id in `supersedes`, one line why), `reply_to <note id>`. Picks the person made and has not sent go with it (owner's rule 2): marked sent with the note (`sent_reply_id`), printed under "Answers to your questions" with the reply's answer lines (`formatQuestionAnswerLines`), and not asked again. Refusals: `409 nothing_to_reask` (nothing of that session open), `422 validation_error` (a person's message, no key), `409 thread_resolved`, `409 session_not_live` for a `to` that is not live; a replayed key answers the note (a reply's key: `409 idempotency_key_reused`).
  - The note is the person's reply, never an Inbox note: it is delivered like one (the queued/sending line, Send now, "Delivered to"), and while every open question is in a note that still waits the row is in Sent (rule 2a above) (`reask_pending`; the Sent row reads "Re-ask queued for <agent>…", or "Asked <agent> to re-ask; waiting for its message." once delivered, `reaskRowLine`). The old questions stay open (answerable) until the agent replaces them; their cards' footers read "Asked again <time>" (`reaskedIn`).
  - The wake: the bridge command carries `reask: true`, and `inboxWakeText` takes `INBOX_REASK_INSTRUCTION` (connection contract, the mod's copy in step) in place of the reply's line ("it is their answer to you" is not true of a Re-ask). An older connection words it as a reply; the body still says what to do.
  - In the thread (`components/ReaskNote.tsx`): "You asked Claude Code to ask the 3 open questions again, together in one message. They stay open here until it does." (plus "Your N picks went with it."), the body behind "What Claude Code was sent". Folded: "Asked to re-ask 3 open questions in one message".
  - Action items (owner, #2059): a session's open action items are asked again with its open questions (the button counts them, the note lists them as `(action item)` and asks for a `:::action` block with `Replaces:`, or `supersedes` / `done`); see "Action items an agent needs you to go do".
  - The session that asked has ended (one target, that session, another live): Re-ask opens the reply's route choice with its own words ("Who should ask again?", primary "Ask Claude Code to re-ask", Cancel); the note goes with `to`, its body says "the N open questions <agent> asked" (named from the host), and its wake carries `redirected_from` with `inboxReaskRedirectedLine` (the questions are another, ended session's; read the thread, then ask them again) in place of the reply's redirected line.
  - Search indexes only the person's own words: a note's body is the Inbox's instructions and the prompts it lists, so `inboxSearchReplyText` gives nothing for it. Several sessions: each note goes to its own session, an ended one's waits for the next agent.
  - Tests: `packages/shared/inbox/store-reask.test.ts`, the thread-state model's `reask` op (`store.test.ts`, property runs), `packages/server/inbox-reask.test.ts` (routes, guards, the wake, an MCP agent superseding, the door), the DOM test `packages/inbox/reask.test.tsx` (A asks 2, B asks 1 and B is picked: one press, A's note and B's plain reply), `tests/e2e/inbox-reask.spec.ts` (compiled binary; desktop light and dark, 1280, the ended choice, a phone in WebKit).
- **Paste to attach** (the owner, 2026-10-16: "When I'm writing a new message or even a reply, I need to be able to paste in images"). A paste in compose (anywhere in the dialog) or in the reply box (`.ib-rbox`'s `onPaste`) that carries files attaches them through compose's upload path, tiles and progress (`useComposeFiles().paste`, `packages/inbox/compose/ComposeFiles.tsx`; the rules in `packages/inbox/compose/paste.ts`). A clipboard image with a name nobody chose (`image.png`, `Pasted Graphic 2.png`, `blob`, none) is renamed `pasted-image-YYYY-MM-DD-HHMM.<ext>` in local time (`pasted-file-…` for anything else), `-2`, `-3` when the name is taken in this message; a real name (a file copied in the file manager) is kept. Text is never taken from the browser, because dictation apps (Hex) write the clipboard, post a synthetic paste and restore the old clipboard about 500 ms later: everything reads `event.clipboardData` synchronously inside the event, never `navigator.clipboard`; a paste of text alone is left to the native path (no `preventDefault`; on Chromium 155-156 on macOS the plain-text insertion below inserts it); a paste of files beside text (an image copied from a page brings HTML, a file from Finder its name) attaches the files and still lets the browser insert the text (`clipboardHasText`); only files with no text is prevented. Text with an unnamed picture is text: a cell copied in Excel, Numbers or Pages carries a picture of itself, which Chromium hands over as `image.png`, so when the clipboard has non-empty `text/plain` only files with a real name attach (`isGenericPasteName`; a screenshot and Chrome's "Copy image" carry no plain text and attach, a Finder copy keeps its name). Each attach by paste is said politely ("Attached <name>"): the thread's live region for the reply box, the dialog's own (`[data-compose-paste-live]`) for compose, since the window's region sits outside the modal dialog. Local previews' object URLs are freed on remove, reset and unmount. No paperclip, drop zone or shortcut in the reply box (the owner asked for paste only).
  - The reply box's files are tiles inside the box above its chips (`[data-reply-files]`, `.ib-rfiles`; each at least 200 px wide in a row, the whole box when that is narrower: they fit a 320 px phone, and a tile's × takes a 44 px hit area on a phone). They live with the box: Cancel, Escape, a Send and another thread forget them (uploads in flight are aborted; `useComposeFiles().reset`); there are no reply drafts. Send waits while one uploads ("Wait for the files to finish uploading."). The ids ride the reply that carries the words (the last target, with the words and annotations), as `uploads`. A Send clears only the files it carried (`useComposeFiles().forget`): one pasted while it was in flight keeps the box open for the next Send. A retry after a failed Send whose words, files or annotations changed takes a new idempotency key for the reply carrying them (`sendContents` in `Thread.tsx`), so a Send that went through but answered an error is never replayed in place of the changed one. The ended-asker note counts only finished uploads, as Send does.
  - Server: the reply route takes `uploads: [upl_id]` with compose's rules (`inboxUploadAttachments`: each copied, read-only, to `uploads/<att_id>/<name>`, the pending record removed once the reply is written; `404 upload_not_found` for an id that is gone, `422` for a list that is not one; copied files are removed again when the store refuses the reply, an archived thread for example). A replayed idempotency key answers the reply it wrote before anything is copied (`InboxStore.replyByKey`). The reply carries them as `attachments`, so agents get them as compose's files: `Attached: <name> (<path>)` lines under the body on the wake and from `wait_for_reply` (`inboxBodyForAgent`; a reply with no words is the lines alone), attachment records in `read_thread`. A Send of files alone (no words, no answers) is a reply, read as a words-only one: nothing answered, the still-open line; its folded line names the files (`foldSnippet`). The window shows them on the sent reply in the same read-only tiles and viewers as compose's files. The phone's door forwards `uploads` unchanged (contract 7.57). Tests: `packages/server/inbox-reply-uploads.test.ts`, the door case in `inbox-devices.test.ts`, `packages/inbox/paste.test.ts`, the DOM test `packages/inbox/pasteFiles.test.tsx` (a text-only paste never prevented), and `tests/e2e/inbox-paste.spec.ts` on the compiled binary.

**Reply drafts and the Draft label** (approval "inbox-reply-drafts", variant Label, 2026-10-20; record in `.product/approved/inbox-reply-drafts/`, not in this repo). The owner: "I need a way of knowing that I typed a message and haven't sent... 'not sent' is helpful but 1. looks bad. 2. doesn't help me when I'm no longer in the thread".
- **The words are kept per thread as a server draft** (`packages/shared/inbox/reply-drafts.ts`, `inbox/reply-drafts/<thread id>.json`, 0600 in a 0700 folder, written whole; the store reads them at open, `InboxStore.replyDraft` / `saveReplyDraft` / `deleteReplyDraft`). Outside the event log, like compose drafts: no line, no seq, nothing an agent, the MCP, search or the phone's event stream sees. A save is a compare-and-set on `updated_at` (`base`; `409 draft_conflict` with the newer draft); an empty body deletes it; a deleted thread or project takes its drafts with it. Routes (`packages/server/inbox-reply-drafts.ts`): `GET /api/inbox/threads/:id/draft`, `POST` the same `{ body, base }`, `POST …/draft/delete`; same-origin and `serverSession` for the POSTs, another site's read refused. The reply route's `clear_draft: "<updated_at>"` (the window puts it on the reply that carries the words, naming the `updated_at` they were saved as) deletes the draft with the Send only while it is still that draft (`InboxStore.clearSentReplyDraft`, a compare-and-set: another window's newer draft stays); a Send without it (the phone's) leaves it. A save may name `base_body`, the words that window saved last: a draft still holding them is accepted as the window's own even when `base` is a step behind (the page's last save as it goes). A change sends `event: drafts` `{ thread_id }` on every window's stream (windows only, and `InboxStore.onReplyDraftChange` in-process, which search uses to drop the thread's cached facts so its status filter follows), and the window reads the list and the Drafts again, and the open thread its own draft. A row's comment count is kept per thread as annotations change (`unsentAnnotations`), never scanned.
- **The window** (`packages/inbox/replyDraft.ts`, `useReplyDraft`; `components/DraftLabel.tsx`): typing saves after a 500 ms pause (`REPLY_DRAFT_SAVE_MS`), leaving the thread saves what waits at once, and a page going away sends it with `keepalive` (`pagehide`). Opening the thread puts the words back in the box, open but without focus (j/k and the page keep working). Cancel and Escape keep the words; Discard (the link beside "Saved 4:43 PM" above the box) drops them; the Send that carries them clears them. Each save uses the `updated_at` this window last knew for that thread (kept per thread, also for the save made on leaving a thread). When `event: drafts` says the thread's draft changed (another window, or a Send from the phone), the window reads it (`reload` with the box's words): unchanged since its base, nothing moves; changed, and the box has no edits since its last save or read (or is closed), the window takes the new draft and the box shows its words, or closes when the draft is gone ("This reply changed / was sent or discarded in another window", said in the thread's live region); changed while the box HAS edits, the base does not move, so the window's save (made at once) is refused. A refused save (`409 draft_conflict`) is never written over: the window adopts the draft as the server holds it. When both windows hold words (this box is not empty and differs from the server's), its words stay in the box, not saved, and one line above the box says "Not saved: this reply changed in another window." (or "…was sent or discarded…"), with **Keep mine** (saved over it) and **Discard mine** (only this window's words go: the box takes the other window's words, or empties); the line is not a live region but is said once in the thread's live region when it appears, the textarea names it in `aria-describedby`, focus goes back to the textarea after either button, and the two buttons stay on one line 20 px apart (24 px on a phone), wider than their hit areas reach. An empty box (a delete) or the same words refused shows nothing and never deletes the other window's draft. A Send claims the thread when it starts (`claim`): what waits is saved, every save in flight is answered, the thread's generation is raised (a save queued earlier does nothing) and no save of it runs until the Send ends (`sent`) or fails (`release`); the box is read-only meanwhile (`readOnly`, and its changes are ignored). A Send that fails without a clear refusal (no answer, or a 5xx) after the reply carrying the words went out is read back: the thread is read for a reply with that idempotency key. Found, it went: the Send is finished as if its answer had come (the box closes, the files it carried leave it, the draft is done with, "Your reply went." in the live region). Not there: the words are saved again and the next Send is an ordinary new Send. Not known (the read failed too, e.g. the Inbox is down): the draft stays as it is on the server, the box keeps the words, and the key, the words and what the Send carried (uploads, comments, picks) are kept for that thread (`unconfirmed`). It holds only while the box keeps exactly those words: it is forgotten when any thread read shows the reply landed (and, the box still holding those words, the Send is finished then: the box closes, "Your reply went."), when the words change or the box empties, when the person leaves the thread, and after 10 minutes. The next Send of those words first reads the thread for that key: found, the words' Send is finished and nothing goes again, and anything added since (a comment, a pick, a file it did not carry) stays and is named ("Your reply went. Not sent yet: 1 pick. Press Send to send it."), for an ordinary Send; not there, an ordinary new Send; still unreadable, nothing is sent; the thread deleted (404), "This thread was deleted, so nothing was sent." When the words change or empty, or the box closes, while such a Send is remembered, the thread is read for it and the line says where it is ("Your earlier reply went; Send sends your edited words as another reply.", or "may have gone"; a closed box's draft copy is read again, so no stale "Draft · Your reply" foot stays), and the draft this window's own Send may have cleared is expected (`expectOwnClear`): a save refused for that reason saves the edited words as the new draft, never a conflict line about "another window". Nothing is ever replayed from memory: a later Send always carries what is in the box and the thread now, to the message it answers now. Words a conflict left unsaved are kept per thread at module level (`conflictWords`), so closing or switching the thread never loses them: they come back in the box, with the line, when it reopens. The Send names the draft its words were saved as in `clear_draft` (none after a conflict, so the other window's draft stays and the foot shows it after the Send). The foot's Send (box closed) reads the draft again and carries it as it is now. The page's save as it goes sends `base_body`, and none while a Send holds the thread or after a conflict. The restart guard (`unsentReply`, `unsent.ts`) and a `beforeunload` question ask while files pasted into the box, a save on its way, or a conflict's words would be lost (`replyDraftUnsaved`); a restart the person already confirmed is not asked again. The `beforeunload` listener is registered only while something would be lost (a page with one runs it before every navigation, and some browsers keep it out of the back/forward cache). Files pasted into the reply box are not kept in the draft (pending uploads).
- **"Draft" replaces "Not sent" everywhere**: the question card's tag "Draft" and footer "Picked 4:35 PM · in your draft"; the folded line's "1 pick in your draft"; the thread's foot "Draft · 2 picks" (or "Draft · Your reply, 1 comment") before Send and Edit draft (the foot's Send carries kept words too); above the open box a soft "Draft" pill, whom it goes to (cut with "…"), "Saved 4:43 PM" and Discard (a 44 px hit area on a phone). A replaced question's pick keeps "Not sent": it is never sent, not a draft.
- **The list row** carries the additive `unsent: { reply_at, picks, comments } | null` (`InboxRowUnsent`, `inboxHasUnsent` in `@plannotator/core/inbox-types`): the count slot reads "Draft · Your reply" / "Draft · 2 picks" / "Draft · Your reply, 1 comment" ("Draft" in the accent colour, the rest muted; real spaces, so a screen reader reads words) on wide, two-line and phone rows; an older Inbox's row keeps "Answered, not sent". The section rule is the list's rule 9 above. Mark read on a thread holding words or comments keeps it in New, and its toast says "Your draft keeps it in New".
- **Drafts**: the sidebar's Drafts row counts message drafts plus open threads holding unsent work; `GET /api/inbox/drafts` adds `replies` (those rows, each with `reply_preview`, the words' first 160 characters), and the Drafts page lists them under "Replies not sent" above the messages; a row opens its thread.
- **Phones**: the row's `unsent` rides the list; the door reads a draft (`GET threads/:id/draft`, contract 7.62) and writes none in v1 (the phone composes its own reply).
- Tests: `packages/shared/inbox/store.test.ts` (the thread-state model draws `draft` ops and checks rule 9 and invariant 9 after every step; `adr/implementation/inbox-thread-state.md`), `packages/server/inbox-reply-drafts.test.ts` (routes, guards, conflict, restart, the agent never sees it, `event: drafts`, the compare-and-set clear, `base_body`, the agent's section, search's status filter), the 7.62 case in `inbox-devices.test.ts`, the DOM test `packages/inbox/replyDrafts.test.tsx` (including a Send pressed before the save whose answer is 800 ms late: the draft never comes back; typing during a Send held 1.5 s: the box is read-only and no draft comes back; a failed Send saving the words again; another window sending the words, then this window's refused save adopting the server state with Keep mine; `event: drafts` emitted as the stream does: sent elsewhere closes a box with no edits and refuses one with edits (the conflict, its live-region line and aria-describedby, the restart guard), another window's words replace a box with no edits and stay on the server against one with edits (Discard drops only mine, focus back to the box); an empty box refused shows nothing; a Send after a conflict leaving the other window's draft showing; a Send whose answer is lost after it went read back and closed, comments included; the same words sent later to a new question going to it; a comment made after a Send the Inbox never got riding the next Send; a Send that landed while the thread could not be read found by the next Send, nothing sent again; the foot's Send carrying another window's newer words; an `event: drafts` refreshing the open thread's copy), and `tests/e2e/inbox-reply-drafts.spec.ts` on the compiled binary (type, leave, come back, reload, restart; a picks-only thread stays out of Quiet; desktop, beside a thread, phone, dark).

**Mark read and the Send that skips** (design record "inbox-mark-read", not in this repo; approved 2026-10-11, with the owner's later rulings that Mark read closes the questions it leaves and that Sent sits below New). Two ways to get a thread out of the top without answering every question.
- **A Send skips a question only when the person presses a Skip** (owner approval "inbox-explicit-skip", 2026-10-21, design brief "explicit-skip", option A "never skip on its own"; it replaces the rule of 2026-10-11 that every Send skips what it leaves unanswered, and the 2026-10-13 amendment that skipped once a Send answered one question: on 2026-10-21 the owner answered 1 of 11 questions in one session's 8 messages, and that rule skipped the other 10 in 8 replies). Sending an answer never skips anything else. The reply box (and the foot while picks or annotations wait) shows the chip "N questions stay open · Skip them", always, whatever the Send carries; "Skip them" (or "Skip it") turns it into "↷ N questions will be skipped · Keep open" for that one Send, and is the only way a Send skips. The window remembers exactly the questions the chip counted when it was pressed (`skipArmed` in `Thread.tsx`, ids `<message id>/<key>`), so a question that lands while the person types is never skipped; at Send it passes them to `sendTargetsOf`, which keeps those still open (a pick saved meanwhile is sent as the pick), and the reply names them in `skip` (see "Questions and Send" for one reply per session). Keep open, the thread changing, or the Send going clears the choice. Skip on a card, Mark read and Re-ask work as before. The server takes only the explicit list: `skip: [key | { message_id?, key }]` (`InboxReplyInput.skip`, checked by `planSkips` in the store: a list, each entry a question of a message `sendMessageOf` accepts, else `422 validation_error` / `404 question_not_found`, nothing written; a listed question that is no longer open, answered, picked, closed or replaced, is left alone so a race never refuses a Send). The old `skip_unanswered` flag is ignored by the reply route and gone from the store (the iPhone app never shipped it; contract 7.11 is rewritten): an older client that sends it skips nothing. A skip-only Send whose listed questions all closed meanwhile answers `{ reply: null, nothing_to_send: true }`, a no-op, so the rest of a Send to several sessions still goes. Each skip is a sent skip, `answer: { skipped: true, by_reply: true }` (`inboxSkipAnswer`; `by_reply` is additive on `QuestionAnswer`, kept by `parseQuestionAnswer` only beside `skipped`), so the card says "Skipped · <time>"; the reply's first line counts it ("Skipped 3 questions.", "Answered 1 question, skipped 2."), and each reads "Skipped by the person" in the answers section (a skip is always the person's choice now, so the old "not answered in this reply; treat them as skipped" sentence is gone; a Skip on the card still reads "Skipped"). read_thread's one-line answers say "skipped by the person". Core's `inboxDefaultSkip` (the list row's delivery reads it for which session asked) now always answers false. A Stopped question a Send skipped no longer blocks: the agent has its answer; an unskipped one stays open, so the agent stays stopped and the row stays in Stopped on you or Holding up work (Skip on the card, Skip them, or Mark read free it without deciding). A note on a card (with Skip, or alone) is a pick like any other and goes with the Send as `Skipped` / `Note: …`; each saved pick also updates the pane's `threadRef` at once, so a Send pressed while a note is still saving sends its saved revision instead of a stale one (`question_revision_conflict`) or leaving the note out (`packages/inbox/skipNote.test.tsx`). Tests: `packages/shared/inbox/store-explicit-skip.test.ts` (the owner's case: 11 questions in 8 messages, 1 answered, one reply, 10 open and the line says 10; answers on 3 messages as one reply; Skip them across messages; a question that lands after the press; another session's or thread's message refused; a stale revision on one message refuses all; a replay; a reopen), `packages/shared/inbox/store-mark-read.test.ts` (the skip list, `skip_unanswered` ignored, refusals), `packages/server/inbox-mark-read.test.ts` (the route), the door's 7.11 in `packages/server/inbox-devices.test.ts`, `packages/inbox/sendTargets.test.ts`, the DOM tests `packages/inbox/markRead.test.tsx`, `wordsOnlyTwoAsks.test.tsx` (one reply with answers on both messages; Skip them for the other one) and `skipNote.test.tsx`, and `tests/e2e/inbox-mark-read.spec.ts`.
- **Mark read** (`POST /api/inbox/threads/:id/read`; Undo `…/unread`). Offered where something waits on the person (Stopped, Holding, Waiting, or New with news or picks; `canToggleRead`, `packages/inbox/markRead.ts`) and never on an archived thread (`409 thread_resolved`). The store (`markRead`) writes the root with `person_read_seq` (the seq of that line) and `person_read_at`, counts it as a look, and closes every question still waiting on the person (open, or picked and not sent): each gets a skip answer and `set_aside: { at, read_seq, previous }` (`InboxQuestionRecord`, additive; `read_seq` is that Mark read's `person_read_seq`), so it reads `state: "closed"` with `set_aside_at` on the wire, and refuses a pick (`409 question_set_aside`). The row is Quiet ("Read") while no message but its set-aside note came after the Mark read (`readAt`, derived: an agent's next message, or the person's own reply, ends it with no write; the closed questions stay closed). Undo reopens only the questions that Mark read closed (owner ruling 2026-10-12), exactly as they were, a saved pick included (revision + 1), and clears the root's fields; a question an earlier Mark read closed (and told the agent about) stays closed, so Mark read again then Undo no longer reopens it. A record older than `read_seq` is matched by `set_aside.at` = the root's `person_read_at`. With no Mark read on the root (after an Undo, or an Unarchive that dropped it) Undo writes nothing. On a thread that came back from the archive, a Mark read made after the agent's latest message sends it back to Archived at once, even while the person's earlier reply there waits on the agent (`back_from_archive` reads past that reply while the Mark read stands); a reply the person sends after it brings the thread back as Sent.
- **The agent is told once.** After the Undo window (`INBOX_SET_ASIDE_DELAY_MS`, 10 s: the 7 s toast with 3 s to spare; the server option `setAsideDelayMs`), while the questions are still closed, the server writes one person note per asking message (`tellSetAside`): a reply to that message, `set_aside: [<question ids>]` on it, body "Set aside for now; don't wait on these:" (`INBOX_SET_ASIDE_HEADING`) and the questions as `- Q<n>. <prompt>` (`composeInboxSetAsideBody`). It reaches the agent like any reply (the wake, `wait_for_reply`, `read_thread`), never pushes to a phone (`pushFor` pushes agent messages only), and never ends the read. It is not the person's reply and not a look: the row's `sent`, `unseen`, `waiting_on_person` and "came back", the window's look boundary (`lookBoundary` in `packages/inbox/folding.ts`), its "Saved for / Delivered to" line and the held list's agent activity (the row's additive `last_agent_at`) all read past it, so news the agent wrote inside the Undo window stays New after the note goes. Each question is named once, across Mark reads; an Undo inside the window tells nothing. An Undo after the note went sends one more person note per asking message, for the questions that Undo reopened only, "The person reopened these:" (`INBOX_REOPENED_HEADING`, `composeInboxReopenedBody`, `reopened: [<question ids>]` on it), so the agent does not go on believing it need not wait; a later Mark read may then tell it again. A timer per Mark read, one on Unarchive (an archive holds the note back), and a sweep at start (`setAsideDue`) for a note a stop interrupted.
- **The window.** The thread header (owner, 2026-10-16: Archive beside the close, Mark read furthest from it): **Mark read** leads (after `‹ Inbox` and its divider when that shows), with its `E` key; pressed it reads **Read** (`aria-pressed`) and moves it back; disabled ("Nothing here waits on you") in Sent or Quiet. The Archive icon sits at the right, beside the thread's × with no separator between them, and ends the header where no × shows (stacked, a file beside the thread, a phone); the tab order follows (`tests/e2e/inbox-thread-header.spec.ts`). Under the subject while read: "Read 3:14 PM. It stays out of the top until <agent> writes again." and how many questions it closed, with **Move back**. The list row's hover action (and keyboard focus, `:focus-visible`) shows **Mark read** on rows that wait on the person, without opening the thread. `E` marks the open thread (or the row with keyboard focus) and again moves it back; `Z` undoes while the toast is up; neither runs while typing or with a modifier, inside the open file's viewer (`.ib-view`, its stepping guard row) or with a file open unless aimed at the thread or the list, in a guided review, or while the sound dialog is up. The toast (`components/Toast.tsx`, 7 s, `MARK_READ_UNDO_MS`; design record "inbox-toast", approved 2026-10-14): a 40 px line at most 520 px wide (with `--ib-soft-float` a pill on the popover's colour with Soft's floating shadow, its border kept transparent; same size and place) in the look of plan and code review's Sonner toasts (card, 1 px border, 8 px radius, 13 px): an icon, a bold lead, a muted detail, Undo as a filled button with a `Z` hint, and a × at its end. **Closing it early** (owner, 2026-10-20, amending the design's "no close": "a way to grab toasts to swipe remove them or way to clear a toast manually"): the × (`data-toast-dismiss`, named "Dismiss", after Undo / Reply / Open; 24 px drawn, muted until hovered, the Soft hover and pill radius; on a phone a 44 px target from its `::after`; Undo and the × are 8 px apart and their targets meet in the middle of the gap without overlapping, so a tap just past the Undo pill is still Undo) or a swipe: a horizontal drag (touch, pen or mouse; pointer events in `useSwipeAway`, `Toast.tsx`) moves the toast with the pointer through the CSS `translate` property (it composes with the desktop toast's centering `transform`) and fades it; let go past 40% of its width (`SWIPE_DISMISS_SHARE`), or flick it (0.5 px/ms over the last 100 ms, at least 16 px), and it slides out that way (180 ms, played on an inert, `aria-hidden` copy, `data-toast-ghost`, so the window drops the toast at once); short of that it springs back (260 ms, a slight overshoot). While a drag is in progress the 7 s timer is paused (`onHold`, `holdToast` in `App.tsx`) and a spring-back resumes it with what was left (at least 1.5 s); once a drag starts the entrance animation is turned off inline, so a spring-back never replays it. A drag that starts vertical is the page's (`touch-action: pan-y`), one that starts on a button is the button's, and a cancelled one (the browser took a scroll) springs back. Under `prefers-reduced-motion` the toast still follows the pointer but nothing slides: it goes, or snaps back. No library: plain pointer events and WAAPI. Closing it, either way, is `dismissToast` in `App.tsx`: the 7 s timer is cancelled and the toast's Undo goes with it, so `Z` no longer undoes once it is closed, and closing never performs the undo. When a toast leaves by any route (the ×, a swipe, Undo, its timer, a new toast) with focus inside it (a person Tabbed onto Undo or the ×), focus goes back to the element it came from (the `focusin`'s `relatedTarget`), else to the open pane's visible header (the thread's `‹ Inbox`, else its subject), else the page's `.ib-main h1` (or `main.ib-main`), never the body; each is tried until one actually takes focus (on a phone the list's heading is hidden while a thread is open). No key closes it (Escape belongs to the thread), and the live region says nothing about a close. The ×'s room comes from the toast's edges and gaps (`ib-toast-closable`: on a desktop 4 px less padding at its end and none before the actions, and where the words would still take a second line, Undo's `Z` hint is not drawn and the gaps close by 2 px (`data-tight`, decided before paint and on each resize by `useRoomForClose` in `Toast.tsx`; `Z` still undoes and Undo still names its key), which frees more than the × takes (a toast with no Undo has no hint to give up, so its copy keeps room for the ×); on a phone 8 px gaps, 12 px at its start and 9 px inside Undo), so a toast that fit one line without it still does, on a desktop at 520 px and on a phone down to an iPhone SE (`tests/e2e/inbox-mark-read.spec.ts` measures the widest desktop copies both ways). Its words always show whole (owner, 2026-10-18): nothing in a toast is cut with "…"; a lead and detail that do not fit one line wrap to a second (the toast grows from 40 px; the actions keep their line), so copy is kept short enough for one line at 520 px with Undo, `Z` and the ×. "Marked read · Moves to Quiet" from inside a thread (the list holds still until it closes; "Marked read · Goes back to Archived" for a thread that came back from the archive), "Moved to Quiet · “<subject>”" / "Back in Archived · “<subject>”" from the row's hover action with no thread open, and "Marked read · “<subject>”" (phone "Read · “<subject>”") for a row that is not the open thread while one is open (`markReadToast`'s `place`: `open`, `held`, `list`), so it never reads as the open thread; a thread an agent was stopped or held up on gets the warning icon, "Marked read · <agent> was stopped" / "Marked read · Held up N things", and **Reply** (moves it back and opens the reply box). Archive: "Archived" with Undo; Settings' Unarchive: "Back in your Inbox · “<subject>”"; the sound: "Sound off" / "Sound setting not saved" (4.2 s); a failed write: its message, which may wrap. Placement (desktop): always centered on the window, never on a pane (owner, 2026-10-15), 16 px from the window's bottom edge, at most 520 px wide and 16 px from each side, whatever is open (owner, 2026-10-18: a toast is brief, so covering Reply, the reply box or a file's stepping strip for a moment is fine; it no longer measures a pane's or a file's foot and never waits for a loading pane). It is CSS alone (`position: fixed` in `inbox.css`, z-index 41, above a full-screen file's 40); nothing in `Toast.tsx` measures the page on a desktop. A phone keeps its own placement (below). The toast is not a live region: the window's live region (`[data-inbox-live]`) says it once as sentences, with how to undo when it can be (`toastSpeech`: "Marked read. Moves to Quiet. Press Z to undo."; a phone: "Undo is available."). The window has ONE toast (`showToast` in `App.tsx`): a new toast replaces the last so two never stack, and none shows while the sound dialog is open.
- **Archive** is the window's name for resolve (tooltip "Archive: the thread ends; the next message starts a new one"; the foot "Archived. The next message from <agent> starts a new thread." · **Unarchive**). Agents keep `resolve_message`; its description says the person sees the thread as Archived. An archived thread leaves the window's list and is listed in Settings' Archived block, which also unarchives it; an agent's `reply_to` after the archive brings it back while something there waits, answerable without unarchiving, and Mark read sends it back (see "Archived" under "The list").
- The phone door allows `threads/:id/read` and `threads/:id/unread` (`inbox-devices.ts` ALLOWLIST); the list row's `read_at` and the question's `set_aside_at` are additive. The surface draws no list or thread, so it is unchanged.
- Tests: `packages/shared/inbox/store-mark-read.test.ts` (the rules, the note, a replay, a store older than Mark read), `packages/shared/inbox/store-words-only-reply.test.ts` and `packages/core/inbox-reply-sentence.test.ts` (a reply with no answers: the exact agent text, words, annotations, one question, an earlier answer; partial replies unchanged), `packages/core/question-answer-by-reply.test.ts`, `packages/server/inbox-mark-read.test.ts` (the routes and guards, the note through `wait_for_reply`, a words-only reply through `wait_for_reply`), the DOM test `packages/inbox/markRead.test.tsx` (the whole window over a real Inbox run by `tests/helpers/inbox-dom-server.ts`; the chip's default with and without a pick; it includes the one-session thread whose words-only Send switched to skip is one reply), and `tests/e2e/inbox-mark-read.spec.ts` on the compiled binary.

**👍 Looks good** (approval "inbox-acknowledge", 2026-10-15, amended 2026-10-16; not in this repo). "Cool, looks good": the thread goes to Quiet, and after the Undo window the 👍 is sent to the agent that wrote the message as one short turn. The amendment, the owner verbatim: "I replied with looks good, but I realized that doesn't send through. I think we just need to send looks good through, honestly." Before it the 👍 was silent (agents saw it only on their next read).
- The thread's foot is `[↩ Reply] [👍 Looks good]` side by side (44 px each on a phone); 👍 is hidden while any question in the thread is open or picked (and while picks or annotations wait to be sent), once the person wrote back (the last message, the Inbox's notes read past, is theirs), on an archived thread, and with no agent message. No new key; the toast's `Z` undoes.
- `POST /api/inbox/messages/:id/ack` (`{ serverSession?, ack? }`, `ack: false` takes it back; the window's same-origin and `serverSession` guards) → `InboxStore.ackMessage`: an additive `ack: { label: "Looks good", at, read_seq, made_read, settled_seq, settled_at, seen_at }` snapshot line on the agent's message, plus Mark read (`read_seq` = the Mark read it stands on, `made_read` = the 👍 made it). Undo removes the ack and undoes the Mark read only when the 👍 made it. Move back (`/unread`, `E`) on that Mark read withdraws the ack too, so the agent never sees a 👍 on a thread the person moved back. Refused: `422 ack_not_allowed` (a person's message), `409 ack_stale` (not the thread's latest agent message), `409 ack_after_reply` (a person message, not an Inbox note, follows it: the reply is the answer and keeps its Sent / Delivered state), `409 question_open`, `409 thread_resolved`. A second 👍 writes nothing. In a one-message thread the root is the agent message, so `markRead` re-reads the root after withdrawing.
- Inside the Undo window (`setAsideDelayMs`, the set-aside note's 10 s) nothing is sent: the toast's Undo (or `Z`) takes it back with nothing written for the agent. After it, `settleAcks` (swept at start too) writes two lines: the ack with `settled_seq`/`settled_at` and `note_id`, then the note it names, a person's message with `ack_of: <message id>`, `reply_to` that message and body `inboxAckLine(<message id>)` ("The person marked your message 👍 Looks good (<message id>). No reply needed unless you have a question."; `packages/shared/inbox/connection.ts`, the mod's copy too). The note rides the reply machinery unchanged, so delivery is exactly once by the existing claim, lease and `delivered` event: `pendingReplies` hands it to the session that wrote the message (`isFor`), and the bridge command is a `reply` with `ack_of`, whose wake (`inboxWakeText`) is `Plannotator Inbox: <subject> (<note id>)` and the ack line alone (an older connection words it as a reply with the line as the person's words). The note is an Inbox note (`isInboxNote` includes `ack_of`): the list's `sent`, `unseen`, the look and "came back" read past it, `readAt` keeps the thread read, and `thread()` (so the window, `read_thread`, search's thread reads and `threadSummary`'s count and `last_at`) leaves it out; the ack on the message says it. Delivered only while the ack still names it (`ackNoteLive`): a 👍 taken back after it settled (the pressed button, Move back) and before delivery is never delivered, and a later 👍 is a new note. At settle `ackMessage`'s conditions are checked again (`ackNotSentReason`): when the agent wrote again after the message inside the window (the 👍 would read as the answer to the newer one) or the person sent a reply after it (their reply is the answer; the 👍 button is hidden by then, so they could not take it back), the ack settles with `not_sent: "replied" | "wrote_again"` and no note, no agent ever sees it (`agentThread`, `markAcksSeen`, `wait_for_reply`), and the line reads "👍 Looks good · not sent: you replied" / "… not sent: <agent> wrote again". Agents also see it in `read_thread` (`ack: { label, at }`, `store.agentThread`) and `wait_for_reply` returns `{ status: "acknowledged", acks: [{ message_id, label, at }], cursor }` for an ack on the caller's latest message (replies first; the note line itself never answers as a reply), which records the note's delivery, so the wake never hands it again; a delivery through the wake marks the ack seen, so neither hands it twice. A wait across every thread the caller asked (no thread id, no cursor) skips an ack already seen; a wait on one named thread keeps answering it. A store from before the amendment replays unchanged: its settled acks have no `note_id`, were never sent, and are not sent now.
- The window: the button pressed (`aria-pressed`, success tint; a click takes it back), a line under the message (`AckPill`, `ackPillLine` in `packages/inbox/components/Thread.tsx`, `data-ack-pill`): "👍 Looks good · You, <time> · goes to <agent> in a few seconds" inside the Undo window (`pending`), then, for a message from a waking connection (`message.wakes`), the reply line's honest words from that session's connection now (`deliveryLine`; the thread reads `asker.connection` for the acked message's session every 3 s while the 👍 waits): "… Queued · <agent> is working; it gets this when its turn ends." (`queued`), "… Sending to <agent>…" while idle (`sending`), "… when its session is back." when it does not poll, "… Queued for <agent>; it gets this as its next turn." when the connection does not say; never a Send now (a 👍 asks nothing of the agent) and it never goes into a running turn by itself (owner's decision 2026-10-21, `INBOX_AUTO_SEND_ACK_NOTES` false; see "Undelivered replies go in by themselves"): while it waits on a busy session it reads "… Undelivered 3 min · <agent> is working · it gets this when its turn ends", with no countdown; or "… Saved for <agent>. It sees it when it next reads this thread." otherwise and for an older settled ack (`saved`), then "👍 Looks good · Delivered to <agent>, <time>" (`delivered`) from the window thread's additive `ack.delivered_at` (the note's delivery, else `seen_at`); the wording follows the reply's delivery line (#1968). The row's `ack` (additive, while the Mark read it made holds) reads "👍 Looks good" in place of "Read"; the one toast "👍 Looks good · Goes to <agent> in 10 s · Moves to Quiet" with Undo (shortened 2026-10-18 so it reads whole on one line). Held order as for Mark read.
- The thread-state model has an `ack` op (property runs only; the trace fixtures are unchanged). Phone door: `POST messages/:id/ack` (contract 7.56). Tests: `packages/shared/inbox/store-ack-delivery.test.ts` (the two lines, once, taken back before delivery, Move back, replay, a store from before the amendment), `packages/server/inbox-ack.test.ts` (the routes, the bridge command and wake text, a held poll, Undo inside the window, `acknowledged` as the delivery, a restart, and the Pi and OpenCode `InboxWake` with stand-in targets), the mod against a real Inbox (`apps/hook/hooks/mod/inbox.test.ts` 12: one turn after the window, the exact text, Delivered), the DOM test `packages/inbox/ack.test.tsx` (every line state; the DOM server takes `INBOX_DOM_SET_ASIDE_MS` and a `deliver` stdin command), `tests/e2e/inbox-ack.spec.ts`.

**The project menu** (design record "inbox-project-menu", approved 2026-10-14; not in this repo). Each sidebar project has a menu: **Mark all as read** and **Archive all**, with one Undo per batch.
- Opening it: the row's **⋯** (`components/ProjectRow.tsx`), a real button beside the row (`.ib-projrow` > `.ib-proj` + `.ib-pmore`, the Settings row's pattern, never one inside the other; named "<project> options", `aria-haspopup="menu"`), shown on hover, on keyboard focus (`:has(:focus-visible)`) and while its menu is open, in place of the count (hidden for the eye only, so the row button's accessible name keeps it: "pando 1"); or a right-click on the row (at the pointer). Both are Base UI (`Menu`, `ContextMenu`): arrows, Home/End, type-ahead, Escape and Tab close, focus back to ⋯. The menu is the Inbox's dropdown look (`.ib-pm`, the search chips' `.ib-sp-menu` values), portaled into `.pn-inbox`; the row whose menu is open keeps a muted background (`data-menu`). No new shortcut (the platform's context-menu key reaches the row by itself; the toast's `Z` undoes). On a phone (`PHONE_QUERY`) ⋯ is always shown (44 px, after the count), there is no right-click or long-press, and the menu is a sheet from the bottom edge titled by the project (`aria-hidden`: the popup's `aria-label` names it; `.ib-pm-pos[data-phone]`, `Menu.Backdrop` scrim), 48 px items; an action closes the navigation sheet.
- **Mark all as read**: single Mark read on every thread of the project it is offered on (`inboxRowOffersMarkRead` in `@plannotator/core/inbox-types`, shared with the row's hover action: Stopped, Holding, Waiting, New with news or picks, and a thread that came back from the archive, which goes back to it). Greyed out (`data-disabled`) when nothing in the project waits on the person. Each thread's waiting questions close as skips, and each thread's own set-aside note goes after the 10 s Undo window (`scheduleSetAside` per thread; notes are not batched). No confirm.
- **Archive all**: every thread the window's list holds for the project. An open thread is resolved; a thread that came back from the archive gets Mark read instead (resolving it again would do nothing). Open questions close (`closedByArchive`) with no confirm, even when an agent is stopped: the toast warns instead.
- **Undo** (the toast's button and `Z`, 7 s) reverses exactly the threads the batch answered with: `markRead(false)` for each marked read, `resolveThread(false)` for each resolved (which schedules any held-back set-aside note, as a single Unarchive does). An Undo inside the 10 s window means no agent hears anything; a later one sends the usual reopened notes.
- **The toast** (`projectBatchToast` in `packages/inbox/projectMenu.ts`), the window's one-line toast (`InboxToast`, design record "inbox-toast"), short enough for one line: a bold lead and a muted detail that is the warning or the questions closed when there is one, else the project. "**Marked 3 threads read** · pando", "**Archived 5 threads** · ux-meeting" (the archive icon), "**Marked 3 threads read** · Closed 2 questions". The warning variant (the warning icon, no Reply: several threads) says "<agent> was stopped", "N agents were stopped" or "Held up N things", and leaves the project out. The live region hears the whole of it through the toast's `speech`: "Marked 3 threads read in pando. Back when an agent writes." (Archive all: "… writes there."; a warning or the questions closed in place of that sentence). A phone's lead: "3 threads read" / "Archived 5 threads". Undo says "Moved back." in the live region.
- **Held order**: the batch is the person's own write. With a thread open the rows show their new state in place (Archive all marks each taken row archived in place, `markHeldRowArchived`) and the list settles when the thread closes; with none open the rows slide to their places.
- **Hiding is automatic and derived** (`shownProjects`): a project whose threads are all archived (none came back) leaves PROJECTS, however it got there (Archive all, or archiving the last thread by hand). Nothing is stored; it comes back with the next thread that puts it in the list (a new message, a `reply_to` that brings a thread back, Unarchive). The project the list is filtered to (`#project=`) stays, dimmed (`data-held`), until the person leaves it, and the list says "Everything in <project> is archived." with "See archived threads" (`#settings/archived`). When every project is hidden the sidebar says "Nothing open. Archived projects are in Settings → Archived." (only "Nothing open." when nothing is archived, e.g. the threads were deleted). A hidden project stays reachable from Settings → Archived, search and a `#project=` link. A folder from an Inbox older than `listed` is always drawn.
- **Server** (`packages/shared/inbox/project-batch.ts`, routes in `packages/server/inbox.ts`): `POST /api/inbox/projects/:id/read`, `/unread` and `/resolve` (see "Inbox Server"), each a loop over the store's per-thread `markRead` / `resolveThread`, so the store stays append-only and gets no new record kind; one synchronous loop, nothing interleaved. The window's guards (same origin, `serverSession`). An optional `batch_id` (1 to 128 of `[A-Za-z0-9_-]`) replays the first answer on a retry (in memory, the last 50; the same id on another project or action is `409 batch_id_reused`); a repeat without one finds nothing eligible and writes nothing. An Undo names its threads; one that is not this project's, or that the store now refuses, is skipped and listed in `skipped`. A write that fails partway stops the loop: the threads already changed get their set-aside notes and are answered (200) with `error: { code: "batch_incomplete", message }` (the cause goes to stderr), the answer is remembered for the `batch_id`, and the window shows the toast as a warning with Undo for what did apply. The toast counts the threads the server's answer names. Also on the phone's door (contract 7.43 to 7.45), whose idempotency log replays a batch's answer. `GET /api/inbox/projects` and the list model's `projects` carry the additive `listed` (threads the window's list holds) and `archived`.
- Tests: `packages/server/inbox-project-menu.test.ts` (routes, Undo, `batch_id`, guards, set-aside notes, `listed`), the batches in the thread-state model (`store.test.ts`, "the project menu's batches": generated histories with batches and Undo between the steps, and a batch undone back to back giving the project back exactly), `packages/inbox/projectMenuModel.test.ts`, the DOM test `packages/inbox/projectMenu.test.tsx` (⋯, right-click, both items, the warning toast, `Z`, hiding and the held project, coming back, the held list with a thread open, the phone sheet), and `tests/e2e/inbox-project-menu.spec.ts` on the compiled binary (the keyboard, focus after the project hides, a reply bringing it back, a phone).

**The thread row's menu** (the owner's ask, 2026-10-20: "right click on a thread row and … copy the thread URL"; `components/RowMenu.tsx`, the rules in `packages/inbox/rowMenu.ts`). A right-click on a list row (wide, two-line or the phone row's DOM), or the platform's context-menu key or Shift+F10 on a focused row (the list sends the row a `contextmenu` for them, since Chromium on macOS and Safari send none; the keydown is cancelled so a browser that would send its own does not open a second), opens **Copy link** (`threadLink`: the settings' `url`, the Inbox's one address `http://localhost:<port>/`, plus `#thread=<id>`, the form the MCP tools hand agents; a page opened over the tailnet copies its own origin), **Copy thread ID** (`msg_…`), a separator, then **Mark read** where the row's hover action offers it (`offersRowMarkRead`) or **Move back** on a row marked read (`canToggleRead`), and **Archive** on a row not archived (`rowMenuActions`). Copies go through `copyTextToClipboard` (its execCommand fallback) and say "Link copied" / "Thread ID copied" with the subject, or "Couldn't copy", in the one toast; Mark read, Move back and Archive are the hover action's and header's handlers and toasts (`rowAction` in `App.tsx`; Archive from a row that is not the open thread names it in the toast's detail and, with a thread open, shows it archived in place like the project menu's Archive all). ONE Base UI `ContextMenu` for the whole list: `.ib-lbody` is its trigger and the menu aims at the row the event names (`[data-row]` or `.ib-mrow`); anywhere else (a band, the Show line, the empty list's link) the event is stopped at the list so the browser's own menu shows (Base UI would otherwise cancel every `contextmenu` inside its trigger from a document listener). It never opens the thread or moves the selection; the row keeps a muted background while its menu is open (`data-menu` on `.ib-rw` or `.ib-mrow`). Escape, Tab and an item put focus ON THE ROW, wherever focus was before the right-click (a mouse right-click never focuses the row itself, in Safari at all): `finalFocus` reads the row's id from a ref kept after the close (`focusId`), and Tab is closed by the list, since Base UI keeps focus in a context menu. A write that then takes the row off the rows on screen (Archive with no thread open, Mark read into folded Quiet) puts focus that fell to the page on the row now in its slot (`rowInSlot`), else the first band. The items are read from the row as it is now (`rowOf(targetId)` every render); a row that leaves the list while its menu is open closes it. Rows carry `aria-keyshortcuts="Shift+F10"` (never `aria-haspopup`: a click opens the thread). Chromium on Windows sends the context-menu key's `contextmenu` on keyup, after ours opened on keydown: one window capture listener, set only when the key opened our menu, cancels that one event while the menu is open, gone after it or a second. No touch: Base UI's long press is turned off (`preventBaseUIHandler` on `touchstart`), and a `contextmenu` from a touch (its `pointerType`, or within 1.5 s of a touch `pointerdown`: Android's long press) shows nothing of ours, so phones have no row menu while a narrow desktop window does. The search palette's rows have none. No new shortcut. The look is the project menu's (`.ib-pm`, `.ib-pmi`, `.ib-pm-sep`). Tests: the DOM test `packages/inbox/rowMenu.test.tsx` (focus held elsewhere then Escape, Copy and Tab; Archive's slot; the keyup guard; Archive in place with a thread open, its toast and Undo) and `tests/e2e/inbox-row-menu.spec.ts` (compiled binary; reads the clipboard; screenshots at 1440, light and dark, in `/tmp/row-menu-shots/` or `PLANNOTATOR_ROW_MENU_SHOTS`).

**Folding a thread** (design record, not in this repo; variant "Land"; `packages/inbox/folding.ts`, drawn by `components/Thread.tsx`).
- What is new: the agent messages after the person's last look or their own last reply, whichever is later (`lookBoundary`, the list's rule). The window reads it from the thread payload BEFORE it records the look: `GET /api/inbox/threads/:id` carries each message's `seq` (its first line's) and, on a person's reply, `sent_annotations` (`InboxStore.windowThread`; additive, absent from an older Inbox, not on the MCP tools). `App.tsx` keeps the boundary per open thread (`look`, from the first read of that thread) and passes it to `ThreadPane` as `lookSeq`, so the "New" marks last until the person leaves the thread. A reply the person sends during the visit is a look too: the pane's effective boundary is the later of `lookSeq` and the highest seq of any person message in the thread now, so what the reply answers stops being new at once (the fold plan is not re-decided). A guided review opens as an overlay (`GuidePane`), so the pane and its fold state stay mounted under it. A payload without seqs folds nothing and marks nothing new.
- When the thread opens, a message is open if it is new, holds a pick not sent, or is the last one (and the last real one, when the Inbox's set-aside or reopened notes trail it: it carries the reply's "Saved for / Delivered to" line, which never sits under a note); every other message, the person's own included, folds to one line (`planFolds`). A message that arrives while the thread is open shows open, new, at the bottom. The fold state is in memory per open thread; nothing is saved.
- A message's head is one row, folded or open (design record "inbox-polish", item 5; the owner chose a 24 px mark): the mark, the name, a third column, what the message holds, the time, in the same cells, so opening a message moves nothing the person clicked; only the third column changes and the body appears below, indented 34 px to the name (`.ib-msg`). Folded, the whole row is the fold button. Open (`[data-open-head]`, `.ib-fline.ib-is-open`), the third column is "in <project>" (`.ib-fl-in`, which gives way first with "…"), "· to you" with the session-ended mark (`.ib-fl-to`) and the attachments count (`.ib-fl-files`), neither of which ever shrinks: the column wraps instead and the row grows downward, its mark and name staying put; the time column holds New, the time (its tooltip the whole moment) and Reply; the fold button (`.ib-fl-hit`) lies under the row as its hit area, since the row holds buttons of its own, and the row's text is `aria-hidden` there (the button's label says it). Search's landing highlight and the skill highlight skip the head row, folded or open (`[data-fold-head], [data-open-head]`). A one-message thread draws the same open row with no fold button. Opening with the head fades the body in (160 ms, a 4 px rise, `data-revealed`) and the third column with it; folding is instant, and so is everything under reduced motion; nothing else that opens messages (the first draw, Expand all, a jump) animates. In a thread with under 560 px of text (a container query on `.ib-pbody`, `ib-thread`: beside a file, a thread of about 568 px, a phone; a 1280 or 1366 px window beside the list keeps one row) every head row, folded or open, takes two lines, the snippet or the third column on the second (`tests/e2e/head-row.ts`: the count and "session ended" are drawn whole at 440 and about 568 px).
- A folded line: the sender's mark and name, a snippet, what the message holds (`holdingsOf`: "2 answered" / "1 open question" / "1 pick, not sent", a paperclip with the file count, a guided review, the annotations a reply sent, "Delivered" on a reply the agent read or a connection delivered), and the time. The snippet (`foldSnippet`) of an agent message is the person's answers (`<prompt> → <answer>`) when every live question in it was sent, the prompt plain and cut at a word near 40 characters (`SNIPPET_PROMPT_MAX`) so the answer stays on the line, the whole prompt in the line's `title` and label; else its first words (`firstWords`: question blocks, fences, tables and images out; `cleanInline` drops only paired emphasis marks at word boundaries, so `snake_case` survives, and keeps inline code's text); a message that is only a question block shows its first live question's prompt. A person's reply shows its own words (`replyWords`: without the store's first line ("Answered N questions." and its skip forms) and everything from the "Answers to your questions" heading on); with none, the answers it sent.
- A run of 4 or more folded messages keeps its first and last two; the rest hide behind "N earlier messages" (decided once when the thread opens, so opening a message never makes others appear or disappear).
- The thread opens scrolled to the "New since you looked" divider with the last read line above it; with nothing new (or when the first message is the first new one) it opens at the top. A meta line under the subject says `N messages · <span> · N new since you looked`. The subject moves into the header once it scrolls away, and "↓ N new" floats above the reply foot while new messages the person has not seen are below the view: it counts, and a click goes to the first of, the arrivals below the view not yet seen on sight (`data-arrival`); only when none waits there, the messages that were new when the thread opened and are below the view (`newBelow` in `components/Thread.tsx`; before 2026-10-12 it printed every message new this visit, wherever it was, and went to the first new one below, often an older one). A message the person has had on screen this visit (its top in the view, or the view past it, the tab visible and nothing over the thread) never counts again, seen on sight or not, so scrolling back up never brings the pill back; scrolled to the end, nothing is below (`passed` in `ThreadPane`; before 2026-10-16 a read message came back into the count whenever it was below the view, and a short last message whose top sat in the pill's band kept the pill up and, under the band, was never seen). The header subject, the pill and the keep-in-place correction are measured only when the fold, the thread or the file beside it changes, never on a keystroke in the reply box; a `ResizeObserver` on the thread's scroll box re-measures the subject and the pill when the foot grows (the reply box, the stale guard, the New-message composer).
- Opening or folding keeps the message acted on in place and keeps focus on it; "Expand all" / "Fold all" in the header keeps the first message in view in place. Keys in the thread pane (never while typing, never in a dialog or the open file): `j` / `k` between messages and the fold, `n` to the first new one; each line and open head's hit area is a button with `aria-expanded`. A jump to a card in a folded message (a replaced question's link, the stale guard) opens the message first.
- A one-message thread has no fold button, no "New", no meta line, no "Expand all". The phone apps draw their own threads; the surface is unchanged.

**Seen on sight: a new message in the thread you have open** (design record "inbox-new-in-open-thread", variant A, approved 2026-10-12; not in this repo; `packages/inbox/seenOnSight.ts`, wired in `components/Thread.tsx` and `App.tsx`).
- An agent message that arrives while its thread is open (its seq is past what this visit's looks covered, and past the person's own last reply) counts as seen once its first lines (the sender row and 96 px of the body, or the whole message when shorter; `firstLines`) have been wholly inside the thread's view, above the pill's 56 px band while the pill shows, for 1 s without a break (`SEEN_DWELL_MS`), while the tab is visible and the window has focus (`pageInFront`) and nothing covers the thread: a file over it (full screen, a phone, a stacked window; a file beside the thread does not cover it), an open `<dialog>` (the update and sound dialogs), or a guided review (`covered` from `App.tsx`). The first lines must also be on top: `document.elementFromPoint` at two points inside them (`samplePoints`: the middle of the visible width, near their top and halfway down) must hit the message itself, so a phone's bottom sheet (New message's sessions or "not running", the annotations list), a desktop popover or the Mark read toast over them hides them. A view too short for the first lines above the pill's band needs only the first line (the sender row; `requiredLines`). Positions are measured without the arrival's entrance shift. One `IntersectionObserver` per run (root the thread's scroll box) plus the body's scroll, `resize`, `focus`, `blur`, `visibilitychange` and `focusin`, and a 250 ms recheck while there is something to see (`RECHECK_MS`: a sheet or toast opening or closing raises no event), decide again; the dwell is checked once more when it ends. A message folded by the person is not on screen and is not seen.
- Then the window records the look up to it: `POST /api/inbox/threads/:id/seen { through_seq }`, through the last arrival such that it and every arrival before it were seen (`lookThrough`: the store keeps one mark per thread, so the look never passes a message the person was not shown), and reads the list again, which unbolds the row in place. The window's record of the look (`look.through` in `App.tsx`) rises only once the server took it; a look that failed is sent again up to 5 times (1 s, 2 s, 4 s… apart) unless a later one covers it. The "New" tag and the divider stay for the visit, as for messages new when the thread opened.
- The open-time look carries `through_seq` too (the newest agent message of the read the thread opened with, `latestAgentSeq`), which closes a race: a message that landed between the window's read and the look used to be marked seen without being shown.
- At the end of the thread (within 24 px of the bottom, `AT_END_PX`, measured on scroll before the arrival renders) the view scrolls down just far enough to show the arrival's first lines (`followBy`, never upward; smooth, instant under reduced motion); anywhere else nothing moves and the pill counts it. The arrival enters with a 200 ms ease-out fade and 6 px rise (`data-arrived`; none under reduced motion), and the thread's polite live region says "New message from <agent>" (", with a question" when it asks; "N new messages" for a batch).
- The list: see Held order (the row bolds and unbolds in place, never moves while the thread is open, never in "N new"; closed unseen it settles unread). Notifications and the question sound are unchanged (`pageInFront` already keeps them quiet while the window is in front).
- A phone in the web window follows the same rule (the file screen covers the thread). The phone apps are asked to do the same; the door's `seen` takes `through_seq` (`adr/implementation/inbox-mobile.md`, 7.8).
- Proofs: `packages/inbox/seenOnSight.test.tsx` (DOM, with a stand-in IntersectionObserver: the dwell, a hidden tab, a window without focus, a blur mid-dwell, a file over the thread on a phone, a cover from the window, a sheet or toast drawn over the first lines (and one mid-dwell), scrolled up and the pill's count and target, arrivals counted before what was new at the open, first lines under the pill, the entrance shift, the look never passing an unseen arrival, a folded arrival, following at the end; and the rules alone), `held.test.ts` ("the open thread", including a thread archived while open that the agent's unseen reply brings back before the close), `openStaysPut.test.tsx` (the open-time look's `through_seq` is the read's newest agent message, and an arrival after it stays unseen), `packages/server/inbox-seen-through.test.ts` (the cap, the race, behind and past the look, refusals) and the door case in `inbox-devices.test.ts`, the thread-state model (`seen` with `through` in the property runs and `hand-18-look-capped-by-through`), and `tests/e2e/inbox-seen-on-sight.spec.ts` on the compiled binary (Chromium desktop and WebKit iPhone 15, including the pill landing on the arrival in one click and an arrival under New message's sheet staying unseen until the sheet closes).

**Replaced questions** (design record, not in this repo; direction A "Quiet"; model agreed with Workspaces).
- An agent supersedes an earlier question of the SAME thread: `supersedes: ["<message id>"]` (every open question of that message) or `["<message id>/<key>"]` on `send_message` (and `submit_guide`, through `SEND_ROUTING_FIELDS`), or a `Replaces: <message id>/<key>` line in a newer block. Core's parser reads that line (`ParsedQuestion.replaces`) only when EVERY token of its value is id-shaped (`msg_` + a 26-character ULID, optionally `/q-` + 8 hex, or a bare `q-` + 8 hex key; one trailing `.` per token dropped), wherever it sits: it is then never the prompt and never context, and it does not change the key. Any other `Replaces:` line is prose (`Replaces: q-learning with PPO`, `Replaces: msg_ queue drain`), so plan review never hides a sentence.
- What replaces it (`superseded_by.key`): the block whose `Replaces:` line named it; through the argument, the new message's only question when it asks exactly one, else null. Null reads "No longer applies"; a key reads "Replaced". Both are `state: "superseded"` on the wire.
- Checked before anything is written (`InboxStore.planSupersede`): every id must name an agent message of the thread the new message lands in (`reply_to`'s, or the routed one) and a question there that is open or picked (not sent, not already superseded, not closed). Two blocks naming the same old question with `Replaces:` is refused too ("named by two questions"). Otherwise the whole send is refused with `invalid_supersedes: …` naming each bad id and listing the thread's open questions (`<message id>/<key> (<prompt>)`, also as `open_questions` in the error's details); a message that would start a new thread can supersede nothing. The message records the argument as given (`InboxMessage.supersedes`, additive), so an idempotent retry with another list is `idempotency_key_reused`. The send's result lists `superseded`.
- Append-only: the message and its questions first, then one more line per superseded question with `superseded_by`. Old stores replay unchanged; routing determinism holds (the generated op model in `store.test.ts` includes supersedes).
- Picks and Send: answering a superseded question (`POST …/picks` or `…/reply` naming its key) are refused `422 question_superseded` (with `superseded_by`). A pick saved on it stays on the record, shown on the card as "Your pick: … Not sent", and is never sent: it is not `picked`, so it never counts as "Answered, not sent", never brings back the "Not sent · Send" foot and never adds to "N picks". A reply's "Answers to your questions" section leaves superseded questions out (neither answered nor "Unanswered"); the others keep their numbers.
- The list: it leaves Stopped / Holding / Waiting (only open questions count). Replaced by a stopped question, the row stays in Stopped on the new one; withdrawn with nothing open, the superseding agent message makes it "New since you looked" (behind the held "N new", like any agent activity), then Quiet once opened. A supersede raises no browser notification by itself (a new question in the same message does, as any question). The phone push does go for any message that superseded a question, even one that asks nothing new (`question: null`, so no lock-screen answers): pushes collapse per thread, so it replaces the older notification and its answer actions; the push's question is only ever an open one (`pushFor`, `packages/server/inbox-relay-push.test.ts`). A pick that meets `422 question_superseded` sets no error in the window; reading the thread again redraws the card as Replaced.
- The window (`packages/inbox/components/ReplacedQuestion.tsx`, drawn through ui's `Viewer` seams `renderQuestionCard` and `renderQuestionBelowPrompt`): the old card keeps "Question N of M", the tag "Replaced" or "No longer applies" (neutral grey), the dimmed prompt, the row "Replaced at <time> by <new prompt ↓>" or "<agent> said at <time> that this no longer applies. Read why ↓" (to the agent's message), "Your pick: <label> Not sent", and the context and options folded behind "Show the old options"; no answer controls. The newer card says "Replaces <old prompt ↑>. Your pick there was not sent." under its prompt. A link scrolls to, focuses and briefly rings its target (no motion under reduced motion).
- The stale guard (`StaleGuard`, `ChangedNotice`): a pick superseded while the thread is open (one already superseded when it opened is read on its card) shows "<agent> replaced question N at <time>. Your pick on it won't be sent. See the new question." above the reply box, the pick chip becomes a struck "1 pick on a replaced question", and Send sends nothing: a panel takes the place of the actions ("Question N changed before you sent", the old prompt and the pick that will not go, a warning that the words were written for the old question) with **Answer the new question** (keeps the draft and jumps there; "Read why" for a withdrawal), **Send your words only** (only when something else is in the reply) and **Keep editing**. Esc is Keep editing; focus moves into the panel and comes back to Send. A `422 question_superseded` at Send (the race) reads the thread again and shows the same panel. It shows once per replacement: after the person acts on it, Send behaves normally.
- The phone: the shell draws message bodies and cards natively (the surface has no question cards), so a superseded card is locked there like any card that is not open or picked; the wire is additive (`state: "superseded"`, `superseded_by`, `supersedes`, `subject_question`), and the door's picks and reply answer the same 422.
- Re-ask (see "Questions and Send") is how the person asks for this: its note lists the open ids and asks for a `Replaces:` line per question asked again and `supersedes` for the rest.
- Tests: `packages/shared/inbox/store-supersede.test.ts`, `packages/server/inbox-supersede.test.ts`, the DOM test `packages/inbox/replaced.test.tsx`, and `tests/e2e/inbox-replaced.spec.ts` on the compiled binary.

**Open questions in a thread** (approval `.product/approved/inbox-thread-open-questions/`, option A "Button in the foot", 2026-10-22; `packages/inbox/openQuestions.ts` pure, `packages/inbox/components/OpenQuestions.tsx`, wired in `Thread.tsx`). A long thread spreads its questions over many messages, some folded; this lists them without leaving the thread.
- The button: "N open questions" (`data-open-questions`, the question-circle icon and a chevron) in the closed foot's button row, right after Re-ask (or after Reply / Edit draft when Re-ask is not offered). Not in the open reply box, the route choice or the stale guard. Counts the questions of live agent messages (`liveMessage`: not closed by an archive) that are `open` or `picked` (not sent); `superseded` ones are left out and counted apart; action items are not questions and are left out (`threadOpenQuestions`). The "N questions stay open · Skip them" chip is unchanged beside it.
- When it shows (`openQuestionsShown`, the decision the approval left to the build): never with none open; always with two or more; with one only where its card may be out of sight, i.e. its message is folded or hidden in the middle fold, or the thread has 4 or more messages (`OPEN_QUESTIONS_LONG_THREAD`, where the fold starts folding and a card scrolls away). One open question in a short, unfolded thread is on screen already, so the button would only repeat it.
- The list (Base UI `Menu`: `aria-haspopup="menu"` / `aria-expanded` on the button, `role="menu"` named "N open questions in this thread", rows `menuitem`; arrows, Home/End, type-ahead by prompt; Escape and Tab close it with focus back on the button): the heading, a muted "1 in your draft · 1 replaced, left out" (each part only when non-zero), one row per question in thread order (a number, the prompt clamped to two lines, then the state: "Draft · <pick>" (the card's pick words) first, else a Stopped badge, else "Holds up N"; then the message's time (`whenTime`) and its place: "in a folded message", else "above" or "below" from the card's middle against the middle of the thread's view (`placeOf`, measured when the list opens), and a foot "Choose one to go to it. Folded messages open." ("Choose one to go to it." when none is folded). Choosing a row closes the list and runs the thread's `jumpTo` (the one the stale guard and replaced-question links use): a folded or hidden message opens first, the card scrolls to the centre, takes focus and is ringed (`ib-q-target`); focus does not go back to the button (`finalFocus` false after a pick). Answering stays on the real card.
- A phone (`phone`): the button reads "N open" with the full count as its `aria-label`; the list is a bottom sheet (`.ib-oq-pos[data-phone]`, full width, 16 px top corners, over a scrim, at most 75vh and scrolling) with a 44 px Close, 56 px rows and 15 px prompts. Component tooltips only (none on these parts); no native `title`. No keyboard shortcut.
- Tests: `packages/inbox/openQuestions.test.tsx` (the rules; DOM: the count with a replaced question and an action item, the menu, states and places, a middle-fold and a folded-line question opened and ringed, arrows and Escape, the phone sheet, no button with nothing open or one in a short thread), `tests/e2e/inbox-open-questions.spec.ts` (compiled binary; desktop Chromium and an iPhone 15 in WebKit, light and dark, PNGs to `PLANNOTATOR_OPEN_Q_SHOTS` or `.local/proof/open-questions/`).

**Action items an agent needs you to go do** (approval `.product/approved/inbox-next-actions/`, 2026-10-21, direction "In the thread": the action item is a card in its thread and nothing else; the owner rejected a list section, a Action item page and a top strip: "Not yet convinced we need a higher level surface". `packages/core/inbox-actions.ts`, `packages/inbox/components/ActionChecklist.tsx`, `packages/inbox/actions.ts`; the card redrawn as a checklist by approval `.product/approved/action-items-checklist/`, option A, 2026-10-22).
- The block: an Inbox-only `:::action` (plan review's question grammar is unchanged: `:::action` is not a question kind, `findQuestionBlocks` and `parseInboxQuestionBlocks` never see it). The first non-empty line is what to do (an order, plain: a heading mark, list marker or emphasis around the whole line dropped, cut at 400); every other line is the why, except `Where:` (a URL, `[name](url)` or `name url` becomes an "Open" button, http(s) only; else a place in words), `Run:` (a command to copy; backticks around it dropped), `Stopped:` / `Holds up:` (read as for questions, with the same negative-word guard), `Watching:` (what the agent watches, to notice it done by itself) and `Replaces:` (only when every token is a `msg_…[/q-…|/a-…]` id). The first of each label wins. Found with core's `findDirectiveBlocks` (the directive scanner `findQuestionBlocks` now uses too, so code fences and HTML blocks hide it the same way). Key `a-` + hash8 (`blockKeyHash8`) of `action\n` + the normalized first line (`inboxActionKey`), `-2`, `-3` for repeats.
- Stored as a question record of kind `"action"` (`InboxQuestionKind = QuestionKind | "action"`; read it with `readInboxQuestionKind`, which answers `"unknown"` for a kind it does not know, never answerable) in `questions.jsonl`, numbered on its own (`position`: A1 is 0, beside Q1 at 0), with additive `action` (`{ where, where_url, run, watching }`) and `action_result` (`{ outcome: "done" | "cant", note, at, by: "person" | "agent", message_id? }`; the record's `answer` stays null). State (`inboxQuestionState`): open; `picked` while the person's Done is inside its Undo window; `sent` once the reply carrying it is written; `closed` when the agent saw it done (`by: "agent"`), a Mark read set it aside, or the archive closed it; `superseded` as for a question (`supersedes` and `Replaces:` take `a-` keys; a question is replaced only by a question and an action item only by an action item: `supersedes` names the new message's only question, or only action item, of the old record's kind as its replacement, and a `:::action` block's `Replaces:` reads only `a-` ids; an action item the person marked inside its Undo window is never superseded: refused by its own id with "the person already marked it", left out of a message-wide id, so their answer goes as they said; send_message's result names a superseded action item as one, ", superseding 1 earlier action item"). The wire lists a message's action items in `questions` after its questions; the window moves them into `actions` as it reads a thread (`splitThreadActions` in `api.ts`, and picks', Send's and Re-ask's answers through `questionsOnly`), so the picks, the Send, the skip chip and Re-ask's picks never meet one. The store refuses an action item's key in a pick, a Send's answers or its `skip` (`validation_error: … is an action item, not a question`), the reply's question sections (`composeInboxReplyBody`: the answers section, the still-open lines) leave action items out, and Re-ask (owner, #2059) asks for the session's open action items together with its open questions: the note lists each as `- <id>: (action item) …` and tells the agent to ask a still-needed one again in a `:::action` block with a `Replaces: <id>` line, put one that no longer applies in `supersedes`, and one it saw done in `done` (`composeInboxReaskBody`; the question-only wording is unchanged); an action item the person marked inside its Undo window is not open and is left out. The window counts open action items for the button (`reaskOffered`, `reaskTargets`' `actions`), its tooltip and the note's line name both ("the 1 open question and 1 action item"), and rule 2a (`reask_pending`) covers them, since they are listed in the note. The wake names only what the note lists: the bridge command carries `reask_items` (`actions` or `both`, from `inboxReaskItemsOf`; absent for questions only, so that wake stays `INBOX_REASK_INSTRUCTION` byte for byte), read by `inboxReaskInstruction` and `inboxReaskRedirectedLine`. `nothing_to_reask` says "No open question or action item is left to ask again."
- The list: no new section, page, strip, notification kind or tab-count change. An open action item counts like an open question for every list rule (`summarizeInboxQuestions`: `open` counts both; `Stopped:` puts the thread in Stopped on you, `Holds up:` in Holding up work, neither in Waiting on you), for the notification ("<agent> stopped on you", word for word; the event stream's question line) and the question sound. An action item inside its Undo window waits on nobody's Send: it is not `picked` in the summary, so never "Answered, not sent". The summary's additive `actions` (open action items among `open`) makes the row's count read "1 action item" or "1 question, 1 action item" (`waitCount` in `format.ts`; plain text, an action item always named, "2 questions" unchanged). A message that asks nothing but carries an action item is named by it (`deriveInboxSubject` over the action items, `subject_question` its id). The folded line's holdings add "1 action item". 👍 Looks good stays hidden while an action item waits (the store's `question_open` covers it).
- The card (a checklist, approval "action-items-checklist", option A): ONE card per run of adjacent `:::action` blocks (only blank lines between them; prose between two blocks makes two cards, each where the agent put it), drawn through ui `Viewer`'s `renderDirectiveBlock` seam with no ui change: `MessageBody`'s `renderActions` (`recordFor`, matching a block to its record by its opening line with `actionForBlock`, and `render`) groups `Viewer`'s blocks into runs, draws the whole run in place of its first block and returns `null` for the others (their empty wrapper is hidden by `inbox.css`, `[data-block-type="directive"]:empty`); a block with no record stays text and ends the run. Header: the checkbox icon, "N things only you can do" ("1 thing…"), "x of N done" (done = done, the agent saw it, or Done inside its Undo window), with replaced items counted apart so the header never contradicts the rows ("· 1 replaced" after the count; a card whose items are all replaced, routine after a Re-ask, reads "2 action items, replaced" with no count), and one badge for the open items (Stopped wins, else Holds up with their hold-ups summed). One row per item (`<li data-action-card data-action-state>`): a round tick (a real button with the stable name "Done: <task>"; inside the Undo window it is `aria-pressed` and a click undoes, but never the second click of a double-click or a click within 500 ms of Done; while a mark is saving it is `aria-disabled`, never `disabled`, so keyboard focus stays on it; a settled row's tick is a plain mark: a check, an ✕ for Can't do it, a dashed empty dot when set aside, closed or replaced), the task, a chip once it is not open (Done, Can't do it, Set aside, Closed, Replaced), a chevron. Rows are disclosures (`aria-expanded` / `aria-controls`, the panel `hidden`), one open at a time, the first open item open to start with. The open row: the why, "Stopped <words>" / "Holds up <words>", **Open <where> ↗** for a link (`target="_blank" rel="noopener noreferrer"`), a place in words, the command whole (wrapped, never cut; `$` before it on a desktop, a "Command" label on a phone) with Copy (its result said in a polite live region; Open and the command both show when an item has both), then **Done**, **Can't do it…** (a reason box: "Why can't you? <agent> gets this word for word."; its Send is disabled while empty) and **Add note…** (a note box, then Done); the note and reason boxes stop at 2,000 characters; Escape in a box closes it. Once per card at its foot: "<agent> is watching: …" (the distinct watching lines of the items still open or inside their Undo window; none once every item is settled or replaced) and, while an item is open and the card takes Done, "Done reaches <agent> after 10 s, so you can undo.". After Done (the tick or the row's button) the next open item opens; from the row's button focus goes to that row's toggle (else the row's own). Inside the window the row is struck through with "Done 3:12 PM. Goes to <agent> in a few seconds. Undo" under it (Can't do it: its reason, the same way); the Undo puts focus on the row's toggle. Settled, opening the row says "You marked it done, 3:12 PM. Sent to <agent>.", "<agent> saw it done, 3:14 PM.", "Set aside when you marked the thread read. <agent> was told not to wait.", "<agent> replaced this action item." or "Closed when the thread was archived."; a sent Can't do it keeps its reason under the task. No keyboard shortcut. 44 px targets on a phone (tick, toggle, Open, the buttons, Undo). The window's toast on Done / Can't do it: "Done · Goes to <agent> in 10 s" with Undo (`Z`), as 👍's.
- Done and Can't do it (`POST /api/inbox/messages/:id/actions/:key`, `{ serverSession?, outcome: "done" | "cant" | null, note? }`, the window's guards; `store.markAction`): recorded at once (`picked`), sent to the agent once the Undo window (`setAsideDelayMs`, 10 s) passes; `outcome: null` inside the window is the Undo (nothing is ever sent); a second mark inside the window replaces the first and starts the window again. Refused: `action_already_sent` (409) once sent, `action_closed` (409) on an action item no longer open, `validation_error` (422) for a question's key, a bad outcome, or Can't do it without a reason (a note is at most 2,000 characters). On the device door as 7.63.
- What the agent gets (`store.settleActions`, timers like 👍's plus a sweep at start): ONE person reply per asking message, sent once EVERY action item the person marked on that message is past its window (two Done clicks seconds apart go in one reply). Archive holds a pending Done back (the message's action items read closed); Unarchive (the thread's, or a project batch's Undo) sends it at once, or when its window passes. The reply answers that message (`reply_to`), the action items marked sent with it first (`sent_reply_id`; `repairUnsentAnswers` re-sends one whose reply never landed), the reply's additive `action_report` naming them. It is the person's reply for delivery (`sent`, Send now, the wake), but never a look (`isInboxActionReport`: `lastPersonSeq`, `markSeen`, the window's `lookBoundary` and seen-on-sight read past it), so agent news that landed inside the window stays new, and a row whose report follows unseen news is placed by the news (New), not Sent. It is delivered by the reply machinery (the wake, Send now, `wait_for_reply`, claims), so its wake is the plain reply wake (`INBOX_WAKE_INSTRUCTION`). Body (`composeInboxActionsReply`): `Did 1 action item.` (`Couldn't do 1 action item.`, `Did 1 action item, couldn't do 1.`), then `## Action items you asked for`, `x of y done.` (y the message's action items not superseded; the agent's own `done` counts), then per action item `### A1. <what to do>` and `Done, 3:12 PM.` (the Inbox's local time) plus `Note: …`, or `Can't do it: <reason>`, and, when that message's questions or action items still wait on the person, one last line naming them (`inboxActionsStillOpenLine`: "Still open: A2. Approve the 2FA prompt for the npm org — the person will do it in the Inbox; don't ask again."). wait_for_reply's closing line reads `questions and action items of <id>` only when an action item is there (a question-only one is unchanged) and names an action item's result in short (`done`, `can't do it`, `you saw it done`). Mark read sets an open action item aside exactly as a question (`set_aside`, no skip answer; Undo puts `action_result` back), and its note lists it as `- A1. …` after the questions (`numberedLines`); an action item inside its Undo window is left on its way.
- The agent's own `done` (send_message's and submit_guide's `done`, `SEND_ROUTING_FIELDS`, `INBOX_DONE_DESCRIPTION`): `<message id>/<a-key>` or `<message id>` for all its open action items, validated like `supersedes` before anything is written (`planDone`: the thread the message lands in, an action item the CALLING session wrote, or one a still-waiting Re-ask note sent to the calling session (`to`: the asker ended) lists (`reaskGrants`, until that session writes in the thread again), still open: one the person marked inside its Undo window is refused, their answer goes as they said; else `invalid_done`, 422, listing the thread's open action items), kept on the message (`done`, part of the idempotency check), recorded on the action item as `action_result` by the agent. Nothing is sent to the person or back; the result says "marking 1 action item done" and carries `done`. read_thread and wait_for_reply number action items A1, A2… (`questionWords`) with what came of them (`result`: `done, note: "…"`, `can't do it: "…"`, `you saw it done`, "(not sent yet …)" inside the window); the transcript's "Waiting on the person" lists an action item as `(A1) action item, open`. Search labels an action item hit "Action item" (its key starts with `a-`). A folded action item-only message reads "Action item: <line>", and its holding chip is its own kind (`todo`).
- What models are told (the owner: "update the instructions that the models get … they need to not overdo it. It's only when there's like a true blocker like a user actually has to do some shit"): `INBOX_ACTION_GUIDE` and `INBOX_ACTION_EXAMPLE` (`packages/core/inbox-actions.ts`) ride send_message's `body` description (`SEND_BODY_DESCRIPTION`) and `plannotator inbox --help` ("Action items only the person can do", plus a When to use / Do not use line each, the `done` argument and the reply's section under "Where replies go"); the connection's short `body` wording (`INBOX_AGENT_FIELD_DESCRIPTIONS`) has a one-paragraph version and its own `done`; never in `QUESTION_AUTHORING_GUIDE` (plan review shares it). The tool entry grew by 861 bytes (+221 o200k tokens): `INBOX_TOOL_COST` 8,189 bytes, "about 8 KB, roughly 2,300 tokens".
- Not built: the phone app's native card (the door and the wire carry everything; contract 7.63 and the action item notes in `adr/implementation/inbox-mobile.md`), a lock-screen Done, a Board link.
- Tests: `packages/core/inbox-actions.test.ts` (the reader, the negative-word guard, plan review's grammar unchanged, the reply body exactly), `packages/shared/inbox/store-actions.test.ts`, the generic op model in `store.test.ts` (action item bodies, `todo` / `settle` / `agentDone` ops in the round trip; the thread-state model knows an action item is never picked or skipped), `packages/server/inbox-actions.test.ts` (MCP send, the route and its guards, the exact wake text, `wait_for_reply`, `done` and `invalid_done`), the door case 7.62 in `inbox-devices.test.ts`, the DOM test `packages/inbox/actionChecklist.test.tsx`, and `tests/e2e/inbox-actions.spec.ts` on the compiled binary (light and dark, desktop and phone).

**New message** (`packages/server/inbox-sessions.ts`, `packages/inbox/components/NewMessage.tsx`; record 5.1 to 5.3; owner Q4: "just another button next to reply", built as a try, not a chat product).
- **The in-thread button is off** since 👍 Looks good (approval "inbox-acknowledge", 2026-10-15: Reply, the ended-asker choice and compose cover it). The route, the door row and the code stay; `SHOW_NEW_MESSAGE_BUTTON` in `packages/inbox/components/Thread.tsx` brings it back. `tests/e2e/inbox-new-message.spec.ts` sends through the route and proves the window still draws it (to, queued, Delivered); the sheet case in `inbox-seen-on-sight.spec.ts` uses the reply box's annotations list, `inbox-worst-case.spec.ts` the compose To picker, and `skillReferences.test.tsx` compose.
- The thread's New message button writes the person's words to one LIVE agent session of the thread's project, through the same wake path as a reply.
- A New message belongs only to the session it names. The store keeps it as a person message with `reply_to: null` and `to: { host, session }` (`InboxAddressee`), and `InboxStore.isFor` hands it to that session only:
  - `pendingReplies` gives it to that session's poll (command `type: "message"`), and `recordDelivery` refuses any other session.
  - Another session's `wait_for_reply` never returns it (`forCaller` in `inbox-mcp.ts`).
  - Another agent reading the thread through `read_thread` sees its text but does not settle it. It is settled only by its delivery: the named session's wake, or that session's own `wait_for_reply`, which records the delivery.
- Live sessions are kept in memory only. Every bridge poll can carry `project_path`, `started_at`, `busy` and `idle_since`, and `POST /api/inbox/bridge/event` `{ type: "state", busy }` says when a turn starts or ends.
  - A session is live while it polled within `INBOX_SESSION_LIVE_MS` (30 s, `connection.ts`) or holds a poll now.
  - It is in a project when its `project_path` resolves to the project's root (the send resolution: realpath, then the repository root, a linked worktree counting as its main repository; the shared project-root cache). A connection that sends no `project_path` is in a project when it wrote there.
  - All three connections send all four: the Claude Code mod, and Pi and OpenCode through the shared `InboxWake` (`project_path` from the target's `projectPath()`: Pi's `ctx.cwd`, OpenCode's session `location.directory`; `started_at` the wake's start in ms; `busy`/`idle_since` from `isBusy()`, asked every tick while a reply waits and every 5 ticks otherwise, with a `state` event when it flips). So every live session is listed under its real project from its first poll, even one that never wrote. On Pi and OpenCode the wake (and so the poll) runs only where the Inbox tool is on.
- Routes: `GET /api/inbox/threads/:id/sessions` and `POST /api/inbox/threads/:id/message` (see "Inbox Server"). A session that is no longer live is `409 session_not_live` and nothing is written. A replayed key answers the message it wrote.
- The wake is `inboxWakeText` with `INBOX_MESSAGE_INSTRUCTION` as its second line: the person wrote to you; answer with `reply_to` the id in the first line. Its subject is the thread's, and there is no MCP tool for it.
- The window:
  - The button reads the live sessions when the thread opens, every 10 s, and on press.
  - None: the button greys but stays pressable and opens "<agent> is not running in <project>" with Reply instead (5.3).
  - One: the box opens addressed to it, "New message to <host> in <project> (live session, idle|working)" (5.1).
  - Several: one row each, with when it started and whether it wrote this thread, is idle or is working (5.2).
  - The thread shows the message "to <host>", then the queued or sending line (see "Questions and Send": "Queued · <host> is working …" with Send now, or "Sending to <host>…") until delivered, then "Delivered to <host>, <time>".
- Tests: `apps/hook/hooks/mod/inbox.test.ts` 09 and `tests/e2e/inbox-new-message.spec.ts`.

**Compose: a new message to a connected agent** (approval record "inbox-compose-to-agent", 2026-10-14, not in this repo: variant Compose; the owner's answers "close asks Keep draft / Discard", "no send without a live agent", "any file, keep uploads simple"). The person starts a NEW thread with one live agent session in any project. Server: `packages/server/inbox-compose.ts` (routes), `packages/server/inbox-sessions.ts` (`allLive`, `composeTarget`, `isSessionLive`), `packages/shared/inbox/drafts.ts`, `packages/shared/inbox/uploads.ts`, `InboxStore.startPersonThread` / `readdressMessage`.
- The thread: a root PERSON message (`started_by_person: true`, `reply_to: null`, `to: { host, session }`, `subject_question: null`), written by `startPersonThread`. Its subject is a SHORT name, not the first 120 characters of the first line an agent's derived subject is: `derivePersonThreadSubject` (`packages/core/inbox-thread-subject.ts`, re-exported by `@plannotator/core/inbox-questions` beside `deriveInboxSubject`), which compose's subject preview (`subjectPreview` in `packages/inbox/compose/model.ts`, also the Drafts page's rows) calls too, so the preview is what the store writes. The rule: the first line with words, plain (markdown marks, link targets, images, HTML, list/quote/heading marks dropped; fenced code and `:::` blocks skipped); a greeting or filler at its start dropped ("Hey Claude,", "So,", "Okay so", "Um,"; "so" only before a comma, another filler or a request word, so "So many tests…" keeps it; a dash ends one only with spaces around it, so "Right-click", "Hi-DPI", "Well-known" and "So-called" stay whole; an agent's name may follow a greeting without a comma, but "there", "team", "all" and the like only before punctuation, so "Hey there is a bug" keeps "There is a bug"; when dropping would leave only a name or nothing, "Hey Claude" alone, the line is kept as it is) and the next letter capitalized; a URL shortened to its host and last path part, a long path to its last two parts; then the first sentence when it fits 60 columns (`PERSON_THREAD_SUBJECT_COLUMNS`; CJK, Hangul, full-width and emoji count two; a sentence never ends at an abbreviation, a lone initial or single letters with dots such as "U.S."), whole, final "." dropped, "?" and "!" kept, no "…"; else its last clause boundary (comma, semicolon, colon, dash; at least 24 columns) plus "…"; else the last whole word that fits (a dangling "and", "the"… dropped) plus "…", and text without spaces is cut between characters (never inside one). A body with no words is named by its first image's alt text or file name, else the first attached file's name ("spec.md and 2 more files"), else "Image", else its first line of code, else its first question's prompt (a body that is only a `:::question` block), else its first line with anything on it (an unclosed directive), so a body with anything on it always gets a subject. Bidi controls are stripped from the subject. Stored once, at send; threads already written keep their subject. Agents' subjects keep `deriveInboxSubject`. Question blocks in it are text: no question records. It is no session's default thread (`indexRoot` gives only agent roots a session's default thread; a person root is indexed only by a name it has), so only a `reply_to` answer (or a send naming its `thread_name`) lands in it; the session's next message without `reply_to` joins its own thread. It is handed to that session alone (`isFor` by `to`), settled only by delivery, and the list places it by the existing rules: Sent until delivered (the delivery is the agent's read), then Quiet; New once the agent answers. The row carries the additive `addressee` (the root's current `to`), so the window draws the agent's mark and "To <agent>" instead of the person's. Idempotent on its key (`personThreadByKey`); another body under it is `idempotency_key_reused`. Two Sends racing with one key both answer the one message; the one the store replays answers `replayed: true` and its copied files are removed, as they are when the store refuses the message.
- The wake: the bridge command stays `type: "message"` and adds `new_thread: true` for such a root; `inboxWakeText` then takes `INBOX_NEW_THREAD_INSTRUCTION` (a new fixed constant in the connection contract, copied into the mod's `inbox-contract.ts`): the person's own idea or request, possibly unrelated; say how you will handle it before you start; answer with `reply_to`. An older connection ignores `new_thread` and uses `INBOX_MESSAGE_INSTRUCTION`, which stays true. Files the person attached ride the command's `body` as `Attached: <name> (<path>)` lines (`inboxBodyForAgent` in `uploads.ts`, used by `replyCommand` and by `wait_for_reply`'s result alike).
- No live session, no send: `POST /api/inbox/messages` answers `409 session_not_live` and writes nothing (`composeTarget`: live within `INBOX_SESSION_LIVE_MS` or holding a poll, any project; the host, when given, must match). The window saves a draft instead.
- Where the thread goes: the session's root (its `project_path`, resolved through `resolveProject`, which creates a project new to the Inbox; a linked worktree folds into its main repository's project, as a send does), else the project it last wrote in (`lastThreadsBySession`). When git does not answer in time and no existing repository project holds the folder, the Send answers `503 project_unresolved` ("…try the same call again") and writes nothing; the pending uploads stay, so the same Send goes once git answers. `GET /api/inbox/sessions` groups the live sessions the same way (a folder the Inbox has not seen yet has `id: null` and its folder name); a session with neither is not listed.
- Send to another session (`POST /api/inbox/messages/:id/to`): re-addresses a person message that no session took yet (a thread the person started, a New message, a redirected reply, or a reply in a thread the person started) to a live session of its thread's project (`replyTarget`). A new snapshot of the same message (the last line wins); `409 already_delivered` once delivered, `409 thread_resolved` on an archived thread, `422 not_addressed` for anything else. A reply in a thread the person started, moved to a session that has seen nothing of that thread (it never took the root, the root is not addressed to it, and it never wrote there), wakes it with `continues_thread: true`, and `inboxWakeText` adds `inboxContinuesLine` (read the thread first with `read_thread`, then answer with `reply_to`). The window offers it after the asker grace (`GET /api/inbox/sessions?session=<id>` or the thread route's `?asker=`).
- A reply in a thread the person started, written before the agent answered, is stamped with the `to` of the message it answers (the root's current `to`) when it is written (`sendReply`), so like any addressed message it is handed only to that session and settled only by its delivery: another agent's `read_thread` or `wait_for_reply` never settles it.
- The thread's name (its chip, `thread_name`): the person may give one in compose (`thread_name` on `POST /api/inbox/messages`, checked by `checkInboxThreadName`: one line, 1 to 120 visible characters, no control or bidi characters; `422 validation_error` otherwise; refused with `409 thread_name_taken`, nothing written, while another OPEN thread of the project has the name (compared by `inboxThreadNameKey`; a resolved one does not hold it); empty means none; part of the Send's idempotency). Compose sends its own suggestion the same way with `thread_name_auto: true` (the chip the person left following the message): best effort, so one that is not a valid name or that another open thread has is dropped without refusing the Send, and it is stored with `named_by: { kind: "auto", at }`, which still lets the agent name the thread (`threadNamers` ignores it) and is replaced, once, by the agent's name; a retry compares only a name the person typed. Otherwise the agent names it ("Naming a thread the person started" under "Agent connections and the knob"). The root carries `named_by` (`{ kind: "person" | "auto", at }` or `{ kind: "agent", host, session, message_id, at }`); a name the person typed or an agent gave never changes. Routing (review of #1956): a compose name, typed or suggested, routes NOTHING. Another session's `send_message` with that `thread` starts its own thread; only the addressed session's `reply_to` replies land in the person's thread, and only an AGENT's name (given once, never changed after) indexes it in `namedThreads`, from which point named sends join it as for any agent-named thread. Compose names live in `personNamed`, read only by `threadNameTaken` (with the root's current name, since an agent may replace a suggestion), so two open threads never share a name. Proved by an independent model, `packages/shared/inbox/store-routing-model.test.ts` (built from the operations alone, with readdress, delete and reopen; it asserts a named send lands in a person's thread only when an agent named it so), beside the line-walk oracle in `store.test.ts`. A retried agent reply compares its `thread` only when the stored reply kept `thread_naming` (anywhere else `thread` with `reply_to` is ignored, and older stores never recorded `reply_thread`). The bold subject stays the short name above. A thread an AGENT named is indexed under its name (`namedThreads`), so later sends with that `thread` join it; a compose name never is (see "Routing" above).
- Drafts: one file per draft, `inbox/drafts/<drf_id>.json` (0600, folder 0700, temp then rename), `{ v: 1, id, created_at, updated_at, body, to: { host, session, project_root, project_name, started_at } | null, project, files: [upload], thread_name? }` (`thread_name` as the person typed it in the chip, at most 500 characters; absent while the chip follows the message; the Send checks it). Never in the event log, so never seen by agents, the MCP, phones, the relay or search. A save is a compare-and-set on `updated_at` (`base`: the `updated_at` the writer read, null to create; a mismatch is `409 draft_conflict` with the newer draft); `updated_at` always moves forward. `GET /api/inbox/drafts` adds each draft's chip, `status: live | ended | none` (its session live now, gone, or none chosen). Sending with `draft_id` deletes the draft. A draft never sends itself and is never re-addressed on its own. Storage in Settings counts the drafts' bytes; `uninstall --purge` removes them with `inbox/`.
- Uploads (`POST /api/inbox/uploads?name=<name>&serverSession=<s>`, the raw body): streamed to a temp file in `blobs/` (never whole in memory), refused past `INBOX_UPLOAD_MAX_BYTES` (100 MB, under the 128 MiB request bound; `413 upload_too_large`), hashed and renamed to `blobs/<sha256>`, the kind decided by `decideInboxAttachmentKind`, and recorded as `inbox/uploads/pending/<upl_id>.json`. The name must be a plain file name (no `/` or `\`, none of the thread name's refused characters: C0 and C1 controls, U+2028/U+2029, bidi controls; at most 255 bytes) outside the dotenv family (`422 upload_refused`, "Not attached: .env files often hold secrets."). At send each upload becomes an ordinary `InboxAttachment` (`inboxUploadAttachments`): the blob copied (a clone where the filesystem has them; never a hard link, so an agent writing to its file cannot change the stored blob), read-only outside Windows (where a read-only file could not be swept), at `inbox/uploads/<att_id>/<name>`, its realpath the record's `path`, `named_path` null, so the tiles, viewers, download route and phone door carry it unchanged, and it never reads as changed since sent. The store's blob sweep after a deletion keeps the pending uploads' blobs and removes the `uploads/<att_id>/` files of deleted messages; an hourly sweep (and one at start) forgets pending uploads older than a day that no draft names, and the blobs only they held (`sweepInboxUploads`).
- Guards: every route is a window route (same origin; `serverSession` in the body, or the upload's query); the owner's page over the tailnet may compose and upload; the phone's door carries the sessions, a new thread, Send to another session and uploads (contract 7.39 to 7.41, 7.48; uploads never through the relay), never drafts.
- The window (`packages/inbox/compose/`: `ComposeDialog.tsx`, `ToPicker.tsx`, `ComposeFiles.tsx`, `DraftsPage.tsx`, `SendToAnotherSession.tsx`, the pure rules in `model.ts`, the session read in `useComposeSessions.ts`):
  - Entry points: a 32 px compose icon beside the sidebar's Search entry (`data-open-compose`, "New message"), a 44 px icon in a phone's list header and on the Drafts page, a 32 px icon at the far right of the list column's header ("Inbox" or the project's name) on a wider window while the main sidebar is closed, with or without a thread open (`InboxList`: rendered only when `useSidebar().open` is false off a phone, marked `data-sidebar-closed`; the hover peek does not count as open; the owner, 2026-10-18), and the ⌘K palette's **Actions** group (`actions` / `onAction` props on `SearchPalette`; `composeActions`): an empty query offers "New message…" and "Message <host> in <project>" for the session last sent to while it is live; typed words offer "New message…" when a word is new, message, idea, ask or send, or 3 letters or more of one's start (so "re", "co", "me" never do), and each live session whose host or project matches. The group sits above everything with no words, when nothing matched, or when a word names an action whole (`namesActionWord`); below the search results otherwise. It shows while the index is still building, above the skeletons. The existing ⌘K is the only key; no new shortcut.
  - The dialog: a native modal `<dialog>` pinned like the palette (`top: max(16px, 12vh)`, 680 px), a full-screen sheet on a phone (top bar Cancel · New message or Draft · Send, or Save draft when nothing can be sent). To is a button (`aria-haspopup="listbox"`) reading "<agent> · <project>"; the picker (approval "inbox-compose-to-picker") is a filter combobox over one listbox with one ~36 px line per live session (44 px on a phone): the agent's mark and name, the project, its folder (muted, cut in the middle, `splitPath`), a check on the chosen one, no group headers, status chip or "Last:" line; a start time (`· 6:33 PM`) only on rows whose project has two or more live sessions (`pickerRows`, counted before the filter). The session last sent to first while it is live (cookie `plannotator-inbox-compose-last`, its project leading), then the current project (the list's filter, else the open thread's), then the most recently active (`composeGroups`); ↓ ↑ wrapping, Enter picks, Escape closes the picker only (focus back on To while To is empty, else the message). With To empty the picker opens with NO row highlighted (its first row is the last session, so Enter, Enter must not bring the auto-fill back): Enter picks nothing until typing or an arrow key highlights the first row. **To starts empty** (the owner, 2026-10-22: "I keep sending messages to the wrong agent in inbox, i think we need to leave the to: field empty"; `composeOpening`): a plain New message (the sidebar, list-header, phone and Drafts page icons, ⌘K "New message…") opens with nobody in To and keyboard focus on the To button, so the person picks first; nothing ever fills To by itself, not the last session sent to (the cookie only orders the picker and the palette's "Message <host>"), not the current project's. Send stays `aria-disabled` with "Choose an agent to send it." and ⌘↵ only says "Nothing sent: choose a live agent first."; on a phone the top bar offers Save draft until one is picked once something is written. An empty compose (no words, no files, no typed thread name) is never kept: no Save draft is offered (a phone's top bar shows the disabled Send), Save does nothing, and closing asks nothing, a reopened draft emptied this way included (its saved copy stays as it was). To is filled only where the person already chose: ⌘K "Message <host> in <project>", the first-run screen's "Message <host>", and a reopened draft (its saved session, an ended one included; a draft saved with nobody in To reopens empty like a plain one); focus then starts in the message. When the first read finds no live agent, To is a line of text and focus moves to the message. Sessions are read every 5 s while it is open; the picker's highlight stays on its session across a re-read. While the first read is out, To reads "Looking for live agents…" (focusable, `aria-disabled`), the status line says the same, and neither Save draft nor a Send refusal shows. The message field takes ⌘↵ / Ctrl+Enter; the subject the thread will get is previewed with core's `deriveInboxSubject`.
  - No live agent: To reads "No agent is running", a note says nothing can be sent and to save a draft; Send stays visible with `aria-disabled` and ⌘↵ only says "Nothing sent: no live agent is chosen. Save it as a draft." (one `role="alert"`, said once); Save draft is offered once something is written. Agents live but none chosen: "Choose an agent to send it."
  - Closing (Escape, Cancel, the backdrop) with words or files that differ from what was saved asks "Keep this message as a draft?" with Keep writing, Discard and Keep draft (the owner's answer: every time); Escape on the question goes back to writing; an empty compose closes asking nothing (`isDirty`). Nothing is saved without the person's choice (no autosave). A reopened draft offers Delete draft.
  - Files: the paperclip (a file input), a drop on the dialog ("Drop files to attach"), or a paste anywhere in the dialog (see "Paste to attach" below); each file uploads at once through XHR (`uploadFile`, for progress) with a bar, can be removed while it uploads (the request aborts), and a refusal stays in its own red tile ("Not attached: .env files often hold secrets.").
  - After Send: the dialog closes, the one toast says "Sent to <host> · in <project>" with Open, on one line (the thread's own line says Queued / Sending / Delivered; the live region still says "Sent to <host> in <project>. It takes it as its next turn.", the toast's `speech`); the new row shows in Sent at once: with no thread open the list adopts what it reads; with one open the held list takes only that row (`addOwnThreads` in `held.ts`: the person's own action, put at its place in its section, the other rows keeping their order; agent news still waits behind "N new"). Focus goes back to what opened compose; when that is gone (the row of a draft just sent or discarded) it goes to the next draft row, else the Drafts heading, else a New message button, never the page (`pendingFocus` + `focusFallback` in `App.tsx`, run after the render that closed it). Deleting a draft from its row's trash button moves focus the same way.
  - Drafts: a "Drafts N" sidebar row under Inbox only while drafts exist; `#drafts` is a page of its own (`.ib-dpage`), rows newest saved first with the chip ("<host> is live", "That session ended", "No agent chosen"), a trash button (32 px, 44 px on a phone) that deletes at once with the toast's Undo (the window re-creates the draft from what it holds). A row reopens compose; a draft whose session ended keeps it in To struck through with "· ended", a warning note and Pick a session, and Send is unavailable until a live session is picked; it is never re-addressed on its own. The page reads the drafts every 10 s for the chips.
  - The thread: a thread the person started says "You started this thread · to <host> in <project>" under its subject (`data-started-by`); the person's files show in the same tiles and viewers, read-only (no comments on one's own upload); the list row draws the addressee's mark and "To <host>" in Sent (`rowAgent` in `InboxList.tsx`). Delivery: queued, delivered, or **Not delivered** ("That <host> session stopped before it took this. If it is resumed, it still gets it.") once the thread route's `?asker=` says the addressed session ended (the 60 s grace), with **Send to another session**: it opens in place as the ended-session reply's radio rows (`ib-route` / `ib-opt`, one radio group of the project's other live sessions, the first selected and focused; arrows move, Enter or "Send to <host>" moves the message, Esc or Cancel closes it), not a menu. "Not delivered" is the warning treatment: the amber icon, the text in the foreground colour.
  - The thread chip (`ThreadNameChip`, `packages/inbox/compose/ThreadNameChip.tsx`; the owner's 2026-10-16 note on #1956, "why can't I just type in the little chip?"): a "Thread" row right under To, its chip the list's grey `ib-key` and a real text field. There is no "New thread: <subject>" preview any more. While the person has not typed in it, it follows the message: `suggestPersonThreadName` (`packages/core/inbox-thread-subject.ts`, re-exported by `@plannotator/core/inbox-questions`), run 250 ms after typing stops: one to three words naming the topic (`PERSON_THREAD_NAME_WORDS`), at most 24 columns (`PERSON_THREAD_NAME_COLUMNS`, CJK two), never cut in a word, no end punctuation; greeting, filler, request verbs ("can you", "fix", "explore"), vague nouns and function words (English plus the commonest Spanish, French, German, Portuguese, Italian) dropped; the first run of two or more remaining words, else the first one; "X specifically" in the next sentence prepended ("Kanban board"); GitHub, GitLab and Bitbucket links named "PR 1934" / "Issue 12"; Japanese split at particles (first part), Chinese at function words (longest part), Korean particles and verb endings dropped; else an image's alt or file name, else an attached file's name. Nothing good (a bare question, filler, code): "", and the chip shows its placeholder "Name this thread" with a dashed border instead of a made-up name. The table of cases is `packages/core/inbox-thread-name-suggest.test.ts`. Typing in it makes it the person's (`ThreadNameState.edited`, `typeThreadName` in `compose/model.ts`): the message no longer moves it. Emptied, it follows the message again, but only once focus leaves it, so it never refills under the caret. A draft keeps only a typed name (`draftThreadName`), so a reopened draft is in the state it was saved in. The Send carries a typed name as `thread_name` (checked first by `composeThreadName`) or the suggestion as `thread_name_auto` (`sendThreadName`). While it follows the message its words are italic and muted with a small "auto" mark (`data-auto`), and aria-describedby says "Named from your message until you type here." ("Your name for the thread." once typed); no `title`. Text pasted into the chip (dictation pastes there when it has focus) that is not a name, with a line break, longer than 120 characters once added, or a sentence of 8 words or more, is never cut short: it goes to the end of the message, focus moves to the message, and the chip says "Too long for a name, so it went into your message." (`pasteOverflows`, `THREAD_NAME_PASTE_WORDS`, `onOverflow`). The suggestion's markdown rules read at most the first 4096 characters of a line (`PLAIN_LINE_MAX`; the link and tag patterns backtracked quadratically on repeated unclosed `![a](b`, minutes for 1 MB), code-like words (`alert(1)`, `a=b`) and invisible characters never reach a name, a second pass keeps every word but function words when the first finds nothing (two words at least: "So I want to make the thing work better" → "Thing work better"), and text without spaces prefers the sentence that asks for something. A refusal (not a valid name, or `409 thread_name_taken`) is said beside the chip (`data-compose-thread-name-error`, `role="alert"`, the chip `data-invalid` / `aria-invalid`) until it changes. Enter in the chip goes to the message; Escape and ⌘↵ are the dialog's. At most 120 characters counted as code points. On a phone the row is 52 px, the chip 34 px with a 44 px hit area and 16 px text (no iOS zoom). Room left for later: joining an existing thread would be a ⌄ after the chip, as To has.
  - The message field is `InboxComposerField` (#1914, `destination="your message"`, inside `.ib-cp-field`, which sets compose's metrics on `.ib-rtext` and its mirror): `/` and `$` open the skill picker AT THE CARET (`caretMenu`: `CaretSkillMenu` in `components/ComposerField.tsx` portals the menu into the dialog itself, since a modal dialog is the top layer, and hangs it off a box laid over the caret's line, measured by `caretLineRect` in `packages/inbox/caretMenu.ts` and held inside the visible field; it opens below the line and flips above when there is no room; on a desktop it floats over everything in the dialog, the footer included, and past the dialog's bottom edge when it needs to (the dialog is `overflow: visible`), up to the reply box's 256 px list and kept inside the visual viewport (`bounds`); on a phone (a full-screen sheet) it stays below the top bar and above the footer and the keyboard, tries above first, full field width, 44 px rows, 198 px list. Before, it hung off the whole 150 px field inside `.ib-cp-body`, a scroll container, so it opened under the field where the footer covered it), and Escape closes the picker before the dialog, even on a bare `/` (`escapeClosesMenu`; the dialog's own keys skip a key the picker took). The reply box keeps the picker against its own (two-line) box. Proof: `tests/e2e/inbox-compose-skill-picker.spec.ts` (1440 and 1024 in Chromium, empty, two attachments, a scrolled field; an iPhone in WebKit: fully on screen, on top at its first and last visible rows, at least min(6, matches) rows, four on a phone). At Send the skills the words reference go as one block at the end of the body (`inboxSkillsBlock(..., INBOX_MESSAGE_SKILL_AUDIENCE)` + `withSkillsBlock`, as New message does); a draft keeps the plain words. The new thread folds the block behind one "Skills: …" line like any person's message.
  - Not built: a history entry for the phone's picker sheet (its Back is the sheet's own); image thumbnails for a reopened draft's files (an icon instead).
- Window tests: `packages/inbox/composeModel.test.ts` (the rules), `packages/inbox/listHeaderCompose.test.tsx` (DOM: the list header's New message absent beside an open sidebar, present with it closed, with and without a thread open, opening compose and taking focus back), `packages/inbox/compose.test.tsx` (DOM, the whole window over a real Inbox: no agent, Escape and Keep draft / Discard, Drafts and Undo, To empty with focus on it and Send refused until picked, a draft and "Message <host>" keeping their session, Send), `packages/inbox/composeThread.test.tsx` (DOM: the thread's lines, Not delivered and Send to another session), and `tests/e2e/inbox-compose.spec.ts` on the compiled binary (no agent to draft, attach and a refused dotenv file, the draft sent to a live session with the new-thread wake and the file named, Delivered and the agent's answer in the thread, ⌘K Actions, a phone, Not delivered and Send to another session, the ended draft; PNGs in `.local/proof/compose/`).
- Tests: `packages/shared/inbox/store-person-thread.test.ts`, `packages/shared/inbox/uploads.test.ts`, the thread-state model's `personStart` and `deliver` ops (`store.test.ts`, the routing-determinism oracle included, and trace `hand-19-person-started-thread`), `packages/server/inbox-compose.test.ts` (the routes, drafts, uploads, and the shared `InboxWake`'s poll fields and new-thread wake), `apps/hook/hooks/mod/inbox.test.ts` 11, `apps/pi-extension/inbox.test.ts` 02b (the real Pi), `apps/opencode-plugin/inbox-v2-wake.test.ts` (poll fields).

**Skill references in what the person sends** (approval "inbox-skill-references", 2026-10-14, Option B as amended, the Quiet look; design record not in this repo). The reply box, New message and comments on attached files take Plannotator's `/` and `$` skill picker, unchanged: a trigger at the start of a word, the same filter, no row active until arrowed onto, so Enter, Tab and Mod+Enter keep their meaning and Escape closes the menu first only once a query was typed (`useSkillReferenceAutocomplete`). No new shortcut.
- The field: `InboxComposerField` (`packages/inbox/components/ComposerField.tsx`), ui's `ComposerTokenTextarea` (the comment composer's textarea and highlight mirror, moved out of `CommentPopover` and exported; metrics in `.ib-rtext` / `.ib-rmirror`), `SkillReferenceMenu` and `HumanOnlySkillNotice` (`destination` "your reply" / "your message"). The message-an-agent dialog is to render the same field. A human-only skill (`disable-model-invocation: true`) is underlined dotted, with "Includes skill instructions" under the box.
- The catalog: `GET /api/inbox/skills` (`packages/server/inbox-skills.ts`), plan review's `handleReferenceSkills`: the global skill folders only, read fresh. The window installs it as ui's `skillCatalogTransport`, so the comment composers on attached files list it too, and sets `skillInstructionsDestination: 'your reply'` (their human-only line says the instructions go with the reply).
- At Send the window composes ONE block at the end of the message (`packages/inbox/skills.ts`, Option B: the client composes the body, as plan review composes its feedback): references are read from the words and every comment on an attached file the Send carries (not a guided review's diff comments), once each; `renderSkillReferencesBlock` (ui) writes Plannotator's block in "the person … this reply / this message" wording (`@plannotator/core/skill-reference-block`): a model-invocable skill by name, a human-only skill's SKILL.md (read then from `GET /api/inbox/skills/content`, 20,000-character cap, truncation notice, marker lines neutralized) between BEGIN/END markers with `Skill directory:` naming its folder. At most 40,000 characters of instructions per message (`INBOX_SKILL_INSTRUCTIONS_BUDGET`); past it, or unreadable, a skill is named with "read SKILL.md in <dir>". A reply carries the block in its `feedback` (after the annotations' feedback, so it is the body's end; the server is unchanged); a New message appends it to `body`. The per-comment "Skills referenced" list is off in the Inbox (`configurePlannotatorUI({ skillReferenceExport: false })`), so a comment's `$name` stays plain text and the block covers it.
- Trust: only the person's Send composes a block; MCP has no skills field, and an agent's `$readback` is plain text. The window folds a block only under the person's own messages: `MessageBody` splits it off with `splitInboxSkillsBlock`, which takes the LAST Inbox heading (after a blank line) whose tail is exactly the shape the window composes: list lines, then nothing but blank lines and closed BEGIN/END sections for skills the list includes, to the end of the body. The real block is always last, so agent text a reply quotes (a guided-review comment's diff lines, an attached-file comment's `Feedback on:` quote) can never fold the person's feedback, not even with a fake unterminated BEGIN running on to the real END; fence parity is not read, since the agent controls it. Both code exporters (the review app's `exportFeedback.ts` and the Inbox's `guideCommentEntry`) also fence quoted code with more backticks than any run in it (`codeFenceFor`, `@plannotator/core/markdown-structure`; unchanged bytes for code without a backtick run). It draws `SkillsLine` (`components/SkillsLine.tsx`): "Skills: readback, write-better · readback's instructions went with this reply (0.4 KB) · Show", a `<details>` that opens on the block as the agent got it. The references in the sent words are painted as the composer painted them (`skillHighlight.ts`: the CSS Custom Highlight API, `::highlight(ib-skill-ref)` / `ib-skill-ref-human` with the dotted underline, matched against the skills the block names, never the live catalog, only in the person's own words (before the answers or feedback headings), at a priority below search's landing highlight; nothing painted where the API is missing). An agent's message is shown whole.
- Snippets and search read the person's words: `replyWords` and the folded line's snippet (`folding.ts`), and search's `inboxSearchReplyText`, drop the block (the `$name` stays in the words, so search still finds the reply by the skill's name; the SKILL.md text is not indexed for that reply). The stored body, `read_thread`, `wait_for_reply`, the wake and the phone carry the whole text (the accepted cost of Option B).
- Phone (`PHONE_QUERY`): the picker opens full width directly above the reply box (no sheet, so the keyboard stays up and a tap inserts on pointerdown), 44 px rows with the description under the name, at most about 4½ rows.
- On the phone's device door (contract 7.46, 7.47). Tests: `packages/server/inbox-skills.test.ts`, `packages/inbox/skills.test.ts`, the DOM test `packages/inbox/skillReferences.test.tsx` (the whole window over a real Inbox; the DOM server pins the skill folders under the test's scratch HOME).

**Replying when the asking session has ended** (`packages/inbox/components/ReplyRoute.tsx`, `packages/server/inbox-sessions.ts`; design record "replying when the asking agent's session has ended", not in this repo; owner approval 2026-10-11, "build it as mocked"). A reply wakes only the session that asked. When that session is gone, the window says so before the person replies, and at Send the person picks where the reply goes. The choice is always manual; nothing routes on its own.
- The asking session is the session of the message a Send's words answer (the last message with picks waiting, else the last agent message). It is said to have ended only on evidence that it wakes: its message came through a connection that wakes its session (the `INBOX_WAKES_META_KEY` meta on `send_message` / `submit_guide`, `callerWakes`, recorded on the message as `wakes: true`: the Claude Code mod, Pi, OpenCode 2). A message without it (an MCP-only agent, OpenCode 1, the mod off, Windows, an older connection) is never "ended", whatever host it names, because such an agent may be blocked in `wait_for_reply` right now. For a `wakes` message the window asks `GET /api/inbox/threads/:id/sessions?asker=<session>`, which adds `asker: { session, live }`. `live` has a grace (`INBOX_ASKER_GRACE_MS`, 60 s) and counts every sign of the session: it holds a bridge poll or an open MCP `wait_for_reply` (`holdOverMcp`), or it polled or called any MCP tool naming that `agent_session` within 60 s (`seenOverMcp`, read from each `/mcp` POST), or the Inbox itself started less than 60 s ago (all of this is kept in memory only). MCP presence never makes a session live for New message. An older Inbox without `asker` reads as live.
- Ended, before replying: the asking message's sender row reads `to you · session ended`, and the foot carries a note (`role="status"`, the reply box's `aria-describedby`): "The <agent> session that asked has ended. When you send, you can pick a live session in <project> to take your reply." With no other live session: "…has ended, and no agent is running in <project> now. Your reply will wait here until an agent reads this thread." The note is for before replying: once the person's reply is the last message (and nothing waits), its own line says where it went.
- The note lives in one always-mounted `role="status"` region at the top of the foot (`data-asker-note`), whose text changes, so a screen reader announces it.
- At Send, with another live session: Send sends nothing and the actions row is replaced in place by one radio group ("Where should this reply go?"): the project's live sessions in New message's order and rows (the asking session, if it comes back, on top as "the session that asked", selected), then "Leave it for the next agent". Five rows, then "Show N more". The primary button names the result ("Send to <host>" or "Leave it for the next agent"). Send or Mod+Enter in the box moves focus to the selected radio; arrows move the selection; Enter submits; Esc (from any control in the choice: the form's `onKeyDown` marks it `defaultPrevented`, and the window's Esc-closes-the-thread handler in `App.tsx` skips a used Escape) or "Back to the reply" closes the choice with the text kept and focus at its end, and the choice is remembered for that draft. A selected row past the first five shows in its place, and stays there when "Show N more" opens the rest. A session that leaves the live list while the choice is open greys ("Ended just now.") and cannot be picked.
- Nothing live: Send sends at once (there is one outcome), and the line under the reply reads "Saved for <agent>. The session that asked has ended, so it waits here until an agent reads this thread."
- The server: `POST /api/inbox/messages/:id/reply` takes an optional `to: { host?, session }`. The route checks it against the thread project's live sessions exactly as New message does (`replyTarget`; a host that does not match counts as not live). Not live is `409 session_not_live` and nothing is written (questions stay unsent); a replayed idempotency key answers the reply it wrote. The message's own refusals come first (unknown message 404, resolved thread `thread_resolved`). A Send that answers several messages posts one reply each and puts `to` only on the ended asker's messages; an answer to another session's message still goes to that session. When a later post is refused after an earlier one went, the error says how many went ("Your answers to 1 of 2 messages were sent; the rest was not."), never "Nothing was sent". The reply is stored with `reply_to` AND `to`, so `InboxStore.isFor`, `pendingReplies`, `recordDelivery` and `wait_for_reply`'s `forCaller` treat it like a New message: only that session is handed it, the asking session (back with the same id) never is, and another agent's read does not settle it.
- The wake: the bridge command stays `type: "reply"` and adds `redirected_from`, the asking agent named from its HOST (`Claude Code`; `agent` without one), never from the name or host string the agent gave itself, since the line enters another session's prompt: the server maps the host through `INBOX_HOST_NAMES` only, and `inboxWakeText` takes only a name in `INBOX_WAKE_AGENT_NAMES` (Claude Code, Pi, OpenCode, Codex, Cursor), `agent` for anything else. `inboxWakeText` then puts one line under `INBOX_WAKE_INSTRUCTION` (`inboxRedirectedLine`): "This reply was written to another <agent> session that has ended. Read the thread with read_thread to see what it asked, then answer with reply_to <id>." It lives in the connection contract, so the mod's copy (`inbox-contract.ts`), Pi and OpenCode (`agent-link.ts`) all word it the same.
- After delivery: the person's message reads "to <host> (another session)" and its line "Delivered to <host> (another session), <time>". "(another session)" is added only when the host is the asker's own host; otherwise the host alone ("Delivered to Pi, …"). Before delivery: the queued or sending line naming "<host> (another session)" (see "Questions and Send").
- Not built (owner questions left as recommended): no memory of the chosen session for the next reply (the next Send asks again until the new session writes in the thread); no marker on the list row (follow-up: the Sent row's own sub-line still says "Queued for <agent>"). A relay or phone that cannot show the choice sends without `to`, which is "Leave it for the next agent". A message addressed to a session that ended before taking it (a New message, a redirected reply, a thread the person started) can be re-addressed with compose's `POST /api/inbox/messages/:id/to` (see "Compose").
- Tests: `packages/server/inbox-ended-reply.test.ts` (the route, 409 and replay, 404 and `thread_resolved` first, wait_for_reply, `wakes` recorded only from a waking send, MCP presence (an open wait holds), the asker grace, the host-named and capped `redirected_from`, Pi/OpenCode's `InboxWake` delivering the redirected line), `apps/hook/hooks/mod/inbox.test.ts` 10 (the mod), `packages/inbox/endedSession.test.tsx` (DOM: the states and the keyboard), `tests/e2e/inbox-ended-session.spec.ts` (compiled binary: two sessions, choose, delivered; nothing live).

**Tagging agents in a reply or a comment** (approval "inbox-tag-agents", 2026-10-20, Lines variant; design record not in this repo; `packages/server/inbox-tags.ts`, `packages/inbox/tags.ts`, `packages/inbox/components/TagPicker.tsx`). The person tags other agent sessions with `@` in the reply box, or in a comment on a markdown, text or HTML file, and the reply goes to each of them as well as its owner.
- The wire: ONE person reply carries an additive `tags: InboxTag[]` (`packages/core/inbox-types.ts`: `{ host, session, name?, label?, wakes, delivery?, deliver_now_at?, read_at? }`), in the order typed, at most `INBOX_TAGS_MAX` (8), never the owner (the session the reply goes to anyway: `InboxStore.recipientOf`, now also `isOwner`). Not a copy per agent. The reply route takes `tags: [{ host?, session, label? }]` and resolves each with `tagTargets` (`packages/server/inbox-sessions.ts`) before anything is written: a live session whose poll says it understands tags (`INBOX_TAGS_POLL_FIELD`, `tags: true`) is `wakes: true`; an MCP agent the Inbox knows (`mcpAgents`: a session whose latest message did not come through a waking connection, or one an MCP tool call named with its `agent_host` / `agent_name`, within 14 days, at most 30) is `wakes: false`. A live session on an older Plannotator is `409 tag_needs_update`; a session the Inbox knows under another host than the tag names `409 tag_host_mismatch`; anything else `409 session_not_live`; a malformed list `422`; the store shape-checks it again fail-closed (`normalizeInboxTags`). A replayed key answers the reply it wrote, tags as they were. Tags work across projects; the answer lands in this thread.
- Who is handed it: the owner, always, and every tagged session (`InboxStore.isFor`). Each records its own delivery: the owner's in `delivery`, each tag's in its own entry (`recordDelivery` by the session). **The bug fix that came with it:** a reply without `to` used to count as read when ANY agent read the thread (`agent_checked_seq`), so a tagged agent told to read the thread first could swallow the owner's wake. A reply with tags is settled for each recipient only by its own delivery or its own `wait_for_reply`, like a message `to` one session (`pendingReplies`); a tagged session's delivery marks nothing for the owner. Proved by `packages/server/inbox-tags.test.ts` (the read before the owner's poll) and the property in `packages/shared/inbox/store.test.ts` ("settled for each recipient only by its own delivery"; the op model sends tagged replies and tagged deliveries, and routing determinism and the round trip hold).
- The wake (`packages/shared/inbox/connection.ts`, the mod's byte copy in `apps/hook/hooks/mod/inbox-contract.ts`): a tagged session's command carries `tagged: { owner }` (the owner's agent named from its host) and `inboxWakeText` gives `INBOX_TAGGED_INSTRUCTION` and `inboxTaggedLine` (read the thread first with read_thread, answer only what is addressed to you, with reply_to). The owner's command carries `also_tagged: [names]` and its wake adds `inboxAlsoTaggedLine` after its instruction. Names are hosts' own names only (they go into another session's prompt, and an MCP agent chooses its own `agent_host`): the server maps each host through `INBOX_HOST_NAMES`, and `inboxWakeText` keeps only a name in `INBOX_WAKE_AGENT_NAMES`; anything else reads "another agent". The tags of one Send (the words' and every comment it carries) ride its LAST reply only, once each (`sendTagsByTarget` in `packages/inbox/tags.ts`), so a tagged agent gets one reply and one wake per Send. An older connection would word a tag as "the person replied to you", which is false, so a session is handed what it was only tagged in only when its poll says `tags: true` (`pendingReplies(session, { tags })`); the Claude Code mod, Pi and OpenCode (`InboxWake`) send it. The window offers an older one as "Update Plannotator to tag this session". On Pi and OpenCode, sessions share `inbox/claims/`: a tagged command's claim is `<reply id>.<session>` (`claimDirOf`), so each session is delivered once.
- MCP-only agents: any MCP agent may be tagged. It is never woken: `wait_for_reply` without a thread also waits on every thread it was tagged in, in any project (`taggedThreadsOf`), and in a thread it never wrote in only what tags it answers; its result says `tagged_you: true` and records that agent's own delivery. `read_thread` shows `tagged: [{ agent, session }]` and `tagged_you` on the message (never the delivery state), lists tagged threads with `tagged_you` and `unread`, and records `read_at` on that agent's own tag (the window: "<agent> read this thread, <time>"). Agents do not tag each other (not built).
- Who can be tagged: `GET /api/inbox/threads/:id/taggable` (`inbox-tags.ts`): every live session in any project, the owner first (the latest agent writer, else a thread the person started's `to`), then the thread's writers, the same project, the rest; then the MCP agents (`kind: "mcp"`). `taggable: false` for a live session without the capability. On the device door (contract 7.60).
- The window: `@` at a word start in the reply box (`InboxComposerField`'s `tags`, ui's `useMentionAutocomplete` with `kinds: ['agent']` and `matchDetail: false`) opens TagPicker: a listbox of `role="group"`s labelled by their headings (the owner's agent first with "Owns this thread", then each agent, "Reads the Inbox, not woken" last with "Not woken"), the skill picker's rules (nothing active until arrowed onto; Enter, Tab and Mod+Enter keep their meaning; Escape closes it before the reply box; no new shortcut; the field's `aria-autocomplete`, `aria-controls`, `aria-activedescendant`). Labels never collide in the text (`tagOptions`): "Claude Code (another session)" in this project, "Claude Code (<project>)" in another, then "(…, another session)". A pick inserts the readable `@Label` (painted as a chip, `TAG_TOKEN_CLASS`) and a polite live region says what it means; an older Plannotator's row inserts nothing and says to update. Under the field, `TagNotes` (described by the field): "Goes to" with the owner's chip ("owns this thread") and each tag's, and one heads-up per tag that does not own the thread, another for one that cannot be woken. Send puts `tags` (with each `label`) on the reply that carries the words, plus the tags of the comments each reply carries; the owner is never sent as a tag. An untagged next reply goes to the agent that wrote last (`sendTargetsOf`, unchanged).
- File comments: `AttachmentPane` passes `mentionSource` to `Viewer` (markdown, text) and `HtmlViewer`; ui's comment composer offers the agents grouped (`MentionPerson.group`) and draws `TagNotes` under the field (`MentionSource.renderNotice`); the ids ride the annotation (`Annotation.mentions`), the Send tags those agents, and the export marks the comment ("Tagged Pi: this comment sends the reply to it too.", `attachmentFeedback`'s `tagNames`). The image, video, code and diagram comment boxes take no tags yet.
- The sent reply (Lines): its head reads "to <owner> · tagged Pi, Codex", the `@` tokens painted from the stored labels (`tagHighlight.ts`, CSS Custom Highlight API), and one line per recipient (`[data-tag-lines]`): the owner's line as before, then each tag's (`tagDeliveryLine`): delivered, queued or sending with its own Send now (`POST …/send-now` `{ session }`, `deliver_now_at` on the tag, the command's `now`), "Saved for <agent>. It sees it the next time it reads this thread." for an MCP agent. Each tag's connection is read from the sessions route's `?recipients=a,b` (`recipients: { <session>: connection | null }`). The list row's `sent.recipients` gives "1 of 3 delivered · Pi queued"; a reply with tags stays Sent until every recipient a connection wakes has it. The row's `participants` and the thread head (`threadParticipants`) draw the agents' marks overlapping (`TagStack`, "Claude Code and Pi").
- Tests: `packages/server/inbox-tags.test.ts` (the delivery rule and the bug, capability, refusals, MCP tags, cross-project answers, Send now, recipients; Pi and OpenCode `InboxWake` sharing one claims folder), `packages/shared/inbox/connection-tags.test.ts`, `packages/inbox/tags.test.ts`, the mod against a real Inbox (`apps/hook/hooks/mod/inbox.test.ts` 10b), the door's 7.60 in `inbox-devices.test.ts`, the ui seams in `CommentPopover.mentionSource.test.tsx` and `mentions.test.ts`, the DOM test `packages/inbox/tagAgents.test.tsx` (over `inbox-dom-server.ts`'s `tags` mode, seeded by `tests/helpers/inbox-tag-world.ts`), and `tests/e2e/inbox-tags.spec.ts` on the compiled binary (PNGs in `.local/proof/tag-agents/`, or `PLANNOTATOR_TAG_SHOTS`).

**Attachments and annotation** (record 2.1 to 2.8; files shown as they are now, versioned; any kind and from anywhere since the owner's 2026-10-10 ruling, design record not in this repo: "make it very accessible and ergonomic for an agent to point out a file so it shows").
- `send_message` takes `attachments: [path]`: absolute (anywhere the agent's user can read) or relative to `project_path`.
- At send time, `recordInboxAttachments` (`packages/shared/inbox/attachments.ts`) resolves each path to its realpath and checks every file before committing anything, with no size bound. It refuses only:
  - a path that is not a regular file (a folder answers "attach the files in it, or a zip of them"; a FIFO or device is refused without blocking)
  - the dotenv family, by the named path's name and by its target's (`inboxAttachmentNameRefusal`, annotate's rule: `.env` and any name ending in `.env` such as `prod.env`, `.envrc`, and any `.env.` name outside the annotatable doc set, so `.env.example` stays)
- Bytes are streamed with async reads (1 MiB chunks, one `O_NOFOLLOW|O_NONBLOCK` handle checked against the stat by dev/ino, so a 3 GB send blocks no other route) through the sha256 into a temp blob, renamed to `inbox/blobs/<sha256>` (the sent version) once every file read, so a file of any size never sits in memory. The send primes the current-file hash cache. A `.send.*.tmp` a crash left is swept at start and on delete once older than 10 minutes.
- The kind (`decideInboxAttachmentKind`): Plannotator's documents keep their viewer by extension while their bytes are text (markdown, text, html, mermaid, graphviz; a document whose bytes are not text is `file`); everything else is read from the bytes: `image` by `sniffImageContentType` (PNG/APNG, JPEG, GIF, WebP, AVIF, BMP, ICO by magic bytes, SVG by its first element; the extension is ignored, so an HTML page named `.svg` is not an image, and an LFS pointer never is), `pdf` by `%PDF-` in the first 1024 bytes, `video` by its container (`sniffInboxVideo`, `packages/shared/inbox/video.ts`, run after the image check so an AVIF stays an image: an MP4/MOV `ftyp` at offset 4 whose major or compatible brand is a video one (`isom`, `iso2`..`iso9`, `mp41`, `mp42`, `avc1`, `M4V `, `qt  `, `dash`, …) and whose MAJOR brand is not an image or audio one (`avif`, `heic`, `mif1`, `M4A `, `M4B `, …); a WebM by its EBML magic and DocType `webm`, while Matroska stays `file`), `code` for any other UTF-8 text with no NUL (`.mjs`, `Makefile`, an unknown extension), and `file` for the rest (zip, Matroska, binaries). A text or code file over `INBOX_VIEW_MAX_BYTES` (16 MB, the most the window reads whole) is a `file`, a download; that bounds memory, it is not an attach cap. The record: `att_` id, realpath, `named_path` for a symlink, `kind`, `sent_sha256`, `size`, `sent_at`, `sent_mtime`, plus additive `media_type` (images, PDF, and video: `video/mp4`, `video/quicktime` when the major brand is `qt  `, `video/webm`), `width` / `height` (images, from the header; an MP4/MOV's first video track) and `duration_ms` (MP4/MOV). An MP4/MOV's length and size come from `readMp4VideoMetadata`, a walk of the top-level boxes by seeking through the send's own descriptor (a few small reads: `moov` may sit after a 461 MB `mdat`; `mvhd` for the length, each `trak`'s `tkhd` + `mdia/hdlr` for the first `vide` track; at most 4,096 boxes, and a box size past the file ends the walk); a `moov` whose tracks hold no video (audio named `.mp4`) keeps the file a `file`, and a header that does not walk records no metadata but stays `video` by its brands. WebM records no metadata.
- Kinds are strictly additive: every reader (window, phone surface, server) reads `kind` through `readInboxAttachmentKind`, so a value it does not know is `file`, a download. The MCP description tells agents the same.
- Access: a file is reached only by its id, and no route takes a path. Reading the current file requires the recorded realpath to still be that path, a regular file, outside the dotenv family (one check, `checkCurrent`, for every route and so for the phone's door), and for `image` / `pdf` / `video` still that kind by its bytes. Otherwise the answer is `409 attachment_changed_type` or `404 attachment_missing`, and the sent version still opens. The current file's hash is cached per (dev, ino, size, mtime, ctime) and read asynchronously; listing a thread (`/threads/:id/attachments`) hashes a changed file only up to 8 MB and judges a larger one by its stat (unchanged when size and mtime are the sent ones), so a growing log is not re-read on every listing.
- Serving (`packages/server/inbox-attachments.ts`; every byte answer carries nosniff and `Cross-Origin-Resource-Policy: same-origin`, and a `Sec-Fetch-Site: cross-site` / `same-site` request is `403` before anything is read):
  - Text kinds: `GET /api/inbox/attachments/:id` as `text/plain` with CSP `sandbox`, and `/view` (JSON). Both answer `415 attachment_not_text` for image, pdf, file and unknown kinds, and check the open handle's size first: a file over 16 MB (one that grew after it was sent) is `413 attachment_too_large`, which the pane shows as its Download card (the phone's `attachments/<id>/view` is the same route).
  - `GET /api/inbox/attachments/:id/image[?version=sent]`: kind `image` only (`415 attachment_not_image` otherwise), `Content-Type` re-sniffed from the bytes served (never the record's or the name's), CSP `sandbox; default-src 'none'; style-src 'unsafe-inline'` (the message-images policy), `inline`, `ETag` = sha256 (`304`), `Cache-Control: private, no-cache`, `X-Image-Width/Height`. The window draws images only by `<img src>`, so an SVG never runs.
  - `GET /api/inbox/attachments/:id/video[?version=sent]` (design record "inbox-video", approved 2026-10-15; not in this repo): kind `video` only (`415 attachment_not_video` otherwise), GET only (`405`), `Content-Type` re-sniffed from the bytes served (`video/mp4`, `video/quicktime`, `video/webm`), `inline`, the message-images CSP, `Cache-Control: private, no-cache`, and HTTP Range (below). The window plays it in `<video src>`; a phone's player streams it through the door.
  - `GET /api/inbox/attachments/:id/download[?version=sent]`: any kind, `Content-Disposition: attachment` with an ASCII `filename` and `filename*=UTF-8''…` (`contentDisposition`), `application/pdf` for a PDF and `application/octet-stream` otherwise, CSP `sandbox`, `Cache-Control: no-store`; streamed from the descriptor, and with HTTP Range (below), so a native player can stream any file.
  - HTTP Range on `video` and `download` (`packages/server/inbox-byte-range.ts`, built by hand from the descriptor the one check opened: `new Response(Bun.file(path))` answers Range by itself but reopens the file by its path, losing the `O_NOFOLLOW` + dev/ino check). Every answer has `Accept-Ranges: bytes` and an `ETag`: the sent version's `"<sent_sha256>"`, the current file's `"<dev>-<ino>-<size>-<mtime µs>"` from the opened descriptor's stat (`inboxStatEtag`; strong, as nginx's stat tag is, because `If-Range` compares strongly; never a hash per request, since every seek is one). One range (`bytes=a-b`, `a-`, `-n`; an end past the file is its last byte) is a `206` with `Content-Range: bytes a-b/size`, never more than `BYTE_RANGE_MAX_ANSWER` (8 MiB): an open-ended or longer range is answered from its start for 8 MiB and the client asks again from where `Content-Range` says it ended (RFC 9110 lets a 206 cover less than was asked; Chromium, AVPlayer and ExoPlayer do ask again). The cap exists because Bun 1.3.14 pulls a streamed body as fast as the file reads, whatever the client's socket takes (every stream form it offers: measured, a client at 400 KB/s on `bytes=0-` of a 200 MB film had all 200 MB read into memory in 0.1 s), so an uncapped range cost the whole range in memory per slow viewer; no range, a header that is not a byte range we read, or several ranges is the full `200`; a start at or past the end, `-0`, or any range of an empty file is `416` with `Content-Range: bytes */size`; an `If-Range` that is not exactly this version's ETag (a date included) is the full `200`, so a player resuming a film the agent re-rendered starts over. An answer up to `BYTE_RANGE_WHOLE_MAX` (1 MiB: a player's `bytes=0-1` probe, most seeks) is read whole and carries `Content-Length`; a longer one streams in 1 MiB reads, and Bun then sends it chunked and drops `Content-Length` (checked on 1.3.14: a stream that does not finish at once loses it), so its size is in `Content-Range` (206) or the record (200). HEAD is answered on `download` (with `Content-Length`), not on `video`. File handles (`handleRangeStream`, also behind the image route and every streamed attachment answer): measured on Bun 1.3.14 with `lsof`, an aborting client does get `cancel`, but a read is usually in flight then and `FileHandle.close()` during a read never closes the descriptor, so a close asked for mid-read is done when that read returns; and a client gone before the answer starts (it closed while the handler was still opening the file) gets a stream Bun neither reads nor cancels, so a body not pulled for `STREAM_IDLE_CLOSE_MS` (30 s) closes its handle and errors (a paused player asks again with a Range). `server.timeout` and `idleTimeout` end sockets, not the stream's handle, and the handler is async, so there is no cleaner Bun mechanism. `startInboxServer`'s `streamIdleMs` shortens it for tests; `packages/server/inbox-video.test.ts` counts the process's open descriptors (`/proc/self/fd`, else `lsof -p`) back to baseline after both kinds of disconnect.
  - HTML is drawn through annotate's serving path: a `<base href>` at `/api/html-assets/<token>/`, one unguessable token per folder, inside `HtmlViewer`'s sandboxed srcdoc frame. Relative images and frames load from the file's folder. The page cannot read the Inbox API, and a frame never draws the Inbox. The Inbox opts into `createHtmlAssetRegistry({ refuseAssetPath, documentCsp })` (annotate passes none): since a page may be attached from a home folder, any path segment starting with `.` and the dotenv family are `404`, judged as requested and by the realpath under the folder (`inboxRefusesAssetPath`), and nested documents get `sandbox allow-scripts allow-modals; connect-src 'none'`.
  - No pixel or size cap (owner, 2026-10-10). The phone's door forwards `attachments/:id/image`, `attachments/:id/video`, `attachments/:id/download` and `markups/:name` to these same routes, so its headers and refusals are the window's; of the phone's request headers it forwards three, a GET's `Range` and `If-Range` and the image routes' `If-None-Match` (plus the event stream's `Last-Event-ID`), and returns the window's `206`, `Content-Range`, `Accept-Ranges` and `ETag` unchanged.
- The window (`packages/inbox/components/AttachmentTiles.tsx`, `ImageAttachmentView.tsx`, `AttachmentPane.tsx`, `AnnotationsChip.tsx`):
  - A message's images show in it like an email's (`ImageGallery`: one justified row at most ~230 px tall, a tall screenshot cropped at its top with a fade, a panorama wider than 4:1 (`WIDE_IMAGE_RATIO`) cropped from its left with a fade on the right, an image smaller than its frame drawn at its own size (`object-fit: scale-down`; a thumbnail marks one no larger than itself `data-small`, `imageFitsWithin`), caption "1280 × 800, 79 KB" or the changed line) AND as tiles with a thumbnail. Every tile, image and chip is one control. Tiles sit in a grid at the foot ("Markdown, 0.9 KB, 2 annotations", or "Changed since it was sent, edited 11:05 AM"); a PDF, a plain file and an unknown kind are one Download link (`<a download>`), never opened in the window.
  - The header says so too (design record `.product/approved/inbox-attachments-header/`, variant Count, approved 2026-10-11, not in this repo). Every agent message with files, short ones included, has a quiet disclosure in its "to you" line: `📎 3 attachments · 1 changed ⌄` (`AttachmentsCount` in `AttachmentTiles.tsx`; "· N changed" only while a file's changed line shows, `changedCount`; accessible name "3 attachments, 1 changed", `aria-expanded` + `aria-controls`). It opens a soft band under the sender row (`.ib-hatts`, `role="region"`) holding the SAME `AttachmentTiles` (`placement="header"`: no heading, no gallery, detail ids prefixed so both sets coexist) and "Also at the end of the message." A tile there opens the file exactly as the foot's does (`openFromMessage`: same route, stepping order, focus into the pane). The band always starts closed: its state lives in ThreadPane per thread, is never saved, and closes when its message folds. The tiles render only while it is open, so by default the foot tiles are the page's only `[data-attachment-id]`. Escape on the count or inside the band closes it and puts focus back on the count (`preventDefault`, so the window's Escape does not close the thread). The count sits in the open head row's third column, above the fold button that lies under the row (see "Folding a thread"). On a phone the count wraps under "to you" and takes a 44 px hit area. Proof: `packages/inbox/attachmentsHeader.test.tsx` (over `inbox-dom-server.ts`'s opt-in `header-files` seed) and the header test in `tests/e2e/inbox-attachments.spec.ts`.
  - Open puts the file beside the thread, with Full screen and Download in the header. HTML (and an image a message's text shows) opens full screen by default, its toolbar showing (see "Full screen", below).
  - "Open in": the file in its own app (design record `.product/approved/inbox-open-in/`, mock-v2, approved 2026-10-14; not in this repo). Builds on #1915 (no implicit OS-default fallback in `/api/open-in`).
    - The control (`packages/inbox/components/OpenIn.tsx`): a compact split button before Download in the pane header beside the thread (the app's icon and "Open", the label gone once the pane is under 780 px; a caret opens the list). Full screen has no header: the same list, Download and the other version sit in its toolbar's ⋯ (`FullScreenMore`, `data-full-view-menu`; through the tailnet or on a phone, "Open in new tab" there). The list is plain icons and names: Browser (HTML), the editors this computer has (VS Code, Cursor, Zed, …), Default app where allowed, Finder (Explorer, Files), then Copy path; the current choice is checked. Picking an app remembers it (the `plannotator-open-in-app` cookie code review uses, through `useRememberedOpenInApp` / `useOpenInApps` in `packages/ui/hooks/useOpenInApps.ts`, which `OpenInAppButton` now uses too) and opens at once. The primary: Browser for HTML; the default app for images and PDFs; otherwise the remembered app, else the first editor (`openInMenu` in `packages/inbox/openIn.ts`). Each tile (foot and header band) gets a ⋯ (`OpenInTileMenu`, `.ib-att-w` wrapper) with the same list: a SIBLING of the tile's button or download link, never inside it, shown on hover, keyboard focus or open, always under `(hover: none)`; its name is "Open in…, <file>". No keyboard shortcut. A launch failure shows its reason under the control for 4 s.
    - Per kind (`inboxOpenInPolicy` in `packages/core/inbox-open-in.ts`, re-exported by `inbox-types`; the window builds the menu from it and the server refuses anything it does not allow): HTML gets Browser (a new tab of the page, a link in the window, never a launch), editors, Finder, never the OS default (it would load `file://` unsandboxed); markdown, text, code, Mermaid and Graphviz get editors; the OS default only for images (png apng jpg jpeg gif webp avif bmp ico; never SVG), PDFs and videos (mp4 m4v mov webm) whose extension agrees, plus md, markdown, txt, json, yaml, yml, toml and log on macOS and Windows (never Linux, never code, csv or HTML); everything else (archives, executables) gets Finder and Copy path only. Apps open the file AS IT IS NOW; the sent version stays in the window, the new tab (`?version=sent`) and Download (owner's recommendation 1, no temp copy).
    - Missing (the current file gone or changed type): the apps are disabled and say "Missing" (or "Changed"); Copy path works; Browser on HTML opens the sent version.
    - Through the tailnet (`settings.via`) and on a phone: only an "Open in new tab" icon (`data-open-in-tab`, the page route for HTML, the image route for an image), nothing for other kinds and no tile ⋯. A server whose app list does not answer (an older Inbox) also gets the icon.
    - The launch: `POST /api/inbox/open-in` `{ attachment_id, app_id, serverSession }` (`packages/server/inbox-open-in.ts`), never a path. Order: `403 local_only` through the tailnet; the global same-origin POST guard (`403 cross_origin`, an attached page's `Origin: null` included); `409 session_mismatch`; `422 validation_error`; `404 attachment_not_found`; the app (`422 open_not_allowed` for an id the policy refuses, a terminal, `browser` or an unknown id; `422 app_not_available` for an editor not installed); then the file again (`checkInboxAttachmentForLaunch` in `packages/shared/inbox/attachments.ts`: the exported `checkCurrent` (realpath, named symlink, regular file, dotenv), plus the head bytes for an image or PDF: `404 attachment_missing` / `409 attachment_changed_type`). It launches the record's realpath through `revealFile`, `openWithApp` or the explicit `openWithSystemDefault` seam (`packages/server/open-in.ts`: `open <file>`, `explorer <file>`, `xdg-open <file>`; only this route calls it) and answers `{ ok, error? }` with 200, as `/api/open-in` does. `GET /api/inbox/open-in/apps` answers `{ available: true, platform, apps }` (the file manager and the editors, never terminals; detected once per process), local only too. Neither is on the device door's allowlist. The launcher is the `openInLauncher` seam of `startInboxServer` (default `systemOpenInLauncher()`); tests pass a recording one.
    - The new tab: `GET /api/inbox/attachments/:id/page[?version=sent]` (HTML only, `415 attachment_not_html` otherwise; cross-site `403`; read only, so the owner opens it over the tailnet). Now: `checkCurrent`, then `303` to the page at its own folder's asset URL (`htmlAssets.documentUrl`, `/api/html-assets/<token>/<name>`), so relative assets, `#anchors` and frames resolve natively under `INBOX_HTML_DOCUMENT_CSP` (`sandbox allow-scripts allow-modals; connect-src 'none'`: opaque origin, no fetch, no storage). Top-level, that response CSP is the page's only sandbox, and the page can navigate its own tab to a sibling file of its folder, so EVERY non-HTML asset the route serves carries its own `HTML_ASSET_SUBRESOURCE_CSP` (`sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:`, plus nosniff; `htmlAssetHeaders` in `packages/shared/html-assets.ts`, used by the Bun registry and Pi's mirror, so annotate's asset route gets it too): an SVG or XHTML `.xml` opened as a document runs no script on the Inbox's origin. A response CSP does not apply to a subresource load, so `<img>`, CSS, fonts and scripts load as before. A name the asset route refuses (a hidden page), a realpath that is not `.html`/`.htm`, or a page over 2 MB is served directly instead, as is the sent version: the bytes with a `<base href>` at the folder, the same CSP, nosniff, CORP, `no-referrer`. Not on the device door.
    - Tests: `packages/server/inbox-open-in.test.ts` (every refusal, the per-kind table on macOS and Linux, the launch-time re-check, a failed launch, the real launcher with only stubs on PATH, the page route, the tailnet), the door refusals in `inbox-devices.test.ts`, the DOM test `packages/inbox/openIn.test.tsx` (over `inbox-dom-server.ts`'s `open-in` mode: a recording launcher and a scripted tailnet), and the new-tab step in `tests/e2e/inbox-attachments.spec.ts` (no app is launched).
  - The way back to the list (design record `inbox-file-back-to-list`, variant 1, approved 2026-10-12; not in this repo). A file beside the thread hides the list and the sidebar (`fileOpen` in `App.tsx`), so on a desktop (not a phone, not stacked, not `stack.file`) the thread header leads with `‹ Inbox` (or the filtered project's name, `backLabel`), ahead of Mark read with a divider (`data-file-back`, named "Back to Inbox"), the same `ib-pback` the stacked layout draws; the thread's own × is hidden while it shows. A click closes the file exactly as the file's × does (through the pane's unsaved-comment question, `AttachmentPaneHandle.leave`, then `closeTo`), so the sidebar returns to the person's saved choice and the list returns with the thread still open; focus goes to this thread's row (`backFromFile` in `App.tsx`) and the live region says "Inbox list shown. <file> closed.". It always ends with the list beside the thread: where the window has room for the list and the thread but not the sidebar too (about 920 to 1050 px at the default sidebar width), the sidebar stays closed on screen (`sidebarHeld`, never written to the person's cookie) and comes back once there is room, when the thread closes, or when the person opens it. Should the list still be covered, focus goes to the thread's `‹ Inbox` and the live region says only that the file closed (decided after the layout is measured, so it never claims a list that is not shown). The thread's subject heading takes `tabIndex={-1}` as the focus fallback. Leaving full screen keeps the file beside the thread with `‹ Inbox` in view. No key binding (the owner declined ⌘B changes until the Inbox has a proper shortcut system). Tests: `packages/inbox/fileBack.test.tsx`, and the full-screen-then-back case in `tests/e2e/inbox-attachments.spec.ts`.
  - Stepping through a thread's files without leaving the viewer (design record `inbox-attachment-stepping`, v2; one viewer and the peek: approval `inbox-image-viewer`, 2026-10-15; neither in this repo). With two or more files, beside the thread a bar under the file (a row of the pane's grid, never over the file) holds `AttachmentStepper`; full screen has no bar and steps from its toolbar's `N/M ⌄` and the keys (`packages/inbox/components/AttachmentStepper.tsx`): `‹ 3 of 9 · name ⌄ ›`. The order is everything the thread opens in the viewer, in reading order: per message, the images its text shows (`inline_images`, see "Images in a message") in text order, then its attached files tile by tile (`attachmentSequence(messages, attachments, inlineImages)`, `packages/inbox/stepping.ts`), PDFs and other downloads included (they show the pane's Download card); guided reviews keep their reader. It stops at the ends: the button greys with `aria-disabled` (focus stays on it) and "Last file in this thread" shows for a moment. The label (or Enter, Space or ↓ on it) opens the peek (`ImagePeek`, `packages/ui/components/ImagePeek.tsx`), which replaced the ⌄ list: a picture list floating above the bar over the file (nothing under it moves), a `grid` with one row per message (its time as the `rowheader`), each file a thumbnail (images) or a type tile ("MD", "PDF") with its name under it, the open file ringed (`aria-selected`), a count badge for files with comments, a paperclip on attached files; keys only while open: ← → along the items, ↑ ↓ between rows (the nearest column), Home / End, Enter or Space opens and focus returns to the pill, Esc or Tab closes (focus back to the pill); a press outside closes it. On a phone (always full screen) the toolbar's ⋯ ("N of M · Every file in this thread") and the comments sheet's position open the same rows as a bottom sheet, three across, portaled into `.pn-inbox`; its backdrop closes it and focus returns to what opened it. Keys (`stepKeyIntent`): `]` / `[` everywhere except while typing, with ⌘ / Ctrl / Alt, on auto-repeat, mid-composition, or while the peek or the question row is open; `→` / `←` the same and also not with Shift, not on an element that uses arrows (the diagram canvas, a focused video, `data-claims-arrows`, a menu, listbox, tab list, radio group or slider; an image never claims them, zoomed or at its own size: ← → always step from it), not with a text selection, not when a handler already used the key. Beside the thread the keys work only from inside the file. Inside an HTML page the bridge forwards a plain `]` / `[` as `step` only while armed (Annotate) and not from the page's text fields (`HtmlViewer`'s optional `onStep`; Interact forwards nothing, and the page still gets the key). Because the page could post `step` itself, `HtmlViewer` honors it only while its iframe holds focus, at most once per `STEP_MESSAGE_MIN_INTERVAL_MS` (150 ms), and the pane ignores it while the question row or the peek is open. The arrows also stand down in a block that scrolls sideways (the key's `composedPath`, through Pierre's shadow root). A step keeps the frame (full screen stays full screen) and REPLACES the route (`writeRoute(..., { replace: true })`), so one Back returns to the thread; opening from a tile still pushes. A typed comment that a step, the peek, a panel card for another file, a tile or Close would lose raises the question row above the bar ("Save it and go on" / "Discard and go to <name>" / "Keep writing"; Esc keeps writing); the pane finds the composer by its textarea (the comment popover, the diagram's, the image box, or an existing comment being edited in the panel or under a code line whose words differ from the saved ones) and saves it with ⌘/Ctrl+Enter, then waits for that save to answer: nothing saved keeps the row open over the words, a failed save stays on the file with the error, and only a saved comment moves on. The pane remembers per file, until it closes, the version chosen, the scroll position and the image's Fit / Actual size; each HTML file opens armed. The header drops the file name when the thread has more than one file (a one-file thread keeps today's header and has no bar beside the thread). Each step is announced once in a polite live region ("3 of 9, checkout-c-drawer.png, PNG image, in Claude's 11:22 AM message" for an image in the text, "… attached to Claude's 11:31 AM message" for an attached file); the pane is named "<name>, file 4 of 9". The open file's tile says "Open beside" (`aria-current`). The image view is keyed by attachment, so its comment box never carries over. Under 768 px (where Plannotator's annotation panel becomes an overlay) the file is always full screen (the one mode, below: no bar under the file, the end note in the step chip), the comments open as the bottom sheet from the toolbar's count, and a horizontal swipe of one finger steps only on an image shown at Fit (and not a panorama); zoomed, one finger pans and two pinch.
  - Full screen, one mode (approval `inbox-one-fullscreen`, variant Drawer, 2026-10-16; not in this repo; it replaced the earlier "full view" and the old full screen that only hid the thread). The pane header's switch (below) takes the file to the whole window with its **Full screen** part (`data-full-screen-toggle`); there is no eye and no second mode. `Thread.tsx` reads the view from the route (see "Side by side, remembered"; a phone and a stacked window are always full screen, `fullLocked`), and `AttachmentPane` draws, when `full` (`.ib-full.ib-fullview`, `data-full-view`), no header, no changed line and no bar under the file: the file fills the window and `FullViewBar` (`components/FullViewBar.tsx`) is what is left. Its dock (`data-full-view-dock`, `data-bar`) holds the toolbar (`role="toolbar"`, "Full screen", first in the pane's tab order; top right, bottom right with 44 px targets on a phone): Back to the thread first where the file can only be full screen (`data-full-view-exit="back"`: a phone, a stacked window), the pen (HTML that takes comments), the comment count (`data-full-view-comments`), `N/M ⌄` (desktop; the same peek as the stepper, under the toolbar), ⋯ (`FullScreenMore` in `OpenIn.tsx`: Open in, Download, the other version, and on a phone "N of M · Every file in this thread"), a labelled **Side by side** (`data-full-view-exit="exit"`, a pick: remembered; focus goes to the header switch's Side by side, the live region says "Side by side: the file is beside the thread."), and » **Hide tools** (`data-full-view-hide`). Entering by the button puts focus on the toolbar's first button ("Full screen. Side by side is in the toolbar."). **Every opening of full screen starts with the toolbar showing** (`pinned`); a step keeps its state. Hide tucks it (`tucked`): it slides off to the right (220 ms; none under reduced motion) and becomes `inert`, and a handle (`data-full-view-handle`, a real button named "Show tools, N comments[, file changed since sent]") is left flush with the corner: ‹, the count, an amber dot when the file changed since it was sent or is gone. A pointer in the corner (`.ib-fvzone`, 96 × 64 px, the handle in it) reveals the toolbar after `REVEAL_DELAY_MS` (120 ms) (`revealed`); leaving tucks it again after `TUCK_DELAY_MS` (450 ms) unless a popover is open or the keyboard is in it; while revealed the last button is a pin ("Keep tools out") that pins it. A press outside, focus leaving the toolbar, or Escape (with no popover open; focus back on the handle) tucks a revealed toolbar. Enter on the handle reveals it with focus on its first button; Hide by keyboard puts focus on the handle; focus is never left on something going inert (it moves between handle and toolbar). On a phone the handle is a 44 × 52 px tab you tap (no corner), and the toolbar's buttons carry no tooltips (no hover there; a tooltip opened by focus would only take the next Escape). The Inbox no longer reads or writes plan review's shared `toolsHidden` (`plannotator-html-chrome`): owner's choice. ⌘⇧X (the html-annotate `toggleTools` chord, through the Inbox's `inbox-file-viewer` scope) tucks or shows the toolbar on an HTML file in full screen only (not while typing or under a modal dialog; `HtmlViewer`'s `onToolsToggle` from inside the page); nothing else gained a key. **Comments: the drawer.** The count opens the docked comments panel (`.ib-drawer`, `data-comments-drawer`) beside the page, 320 px: the page narrows (no width animation), the dock and the step chip move left of it. Its own title and close, the panel's scope toggle, and its foot (`data-full-view-foot`): "N annotations ride your next Send to <agent>. M are on other files." and **Write the reply**. Open or closed is remembered (cookie `plannotator-inbox-file-comments`, `COMMENTS_DRAWER_COOKIE`), and it **never opens by itself**: a comment saved while it is closed bumps the count (`.ib-bump`, on the handle too; none under reduced motion); a card selected in it stays beside the page. Escape inside it, or its close, shuts it with focus back on the count (or the handle when tucked). On a phone it is the bottom sheet (`.ib-panel-open`, the toolbar hidden under it), its foot also holding the position. A step keeps full screen, and a chip (`data-full-view-chip`) names the new file for `FULL_VIEW_CHIP_MS` (1.6 s, fades 150 ms, none under reduced motion), with "Last file in this thread" at the ends; a one-file thread's chip names the file once as full screen starts. The changed line is a persistent chip at the top left (`data-full-view-changed`: "Changed since sent · Open the version it sent", "Showing the sent version · Open the file as it is now", "The file is gone; showing the sent copy"; the full sentence in its tooltip): a fact about the file, it does not tuck; the markdown toolstrip and the image's size bar move down under it. An image's or a film's comment row stays at the foot: the chip and a phone's toolbar sit above it (`--ib-fvfoot`, measured by the pane); a desktop toast keeps its place 16 px from the window's bottom, over the row for its few seconds. The question row comes back as an overlay at the foot. **Escape, one thing per press, then out** (the owner's note on PR #1958; the order is pure in `packages/inbox/escapeLadder.ts`, the pane reads its state into `escapeRung` and acts in `climb`): (1) ⋯ or the file list closes; (2) a comment being written closes: a comment popover (text, HTML pinpoint, a code line's new comment) or a diagram's composer, and **typed words are never lost**: Escape on a composer holding words (or an edit box whose words differ from the saved ones) is caught in the capture phase before the composer's own Escape and raises the question row with **Save it** / **Discard it** / **Keep writing** (Discard sends the composer its own Escape, marked so nothing else acts on it), while an empty one just closes; (3) in an image's or a film's comment row, focus leaves the row (its words stay; "Left the comment box."); (4) the comments drawer (a phone's sheet) closes ("Comments closed.", focus on the count); (5) an HTML file in Annotate goes to Interact ("Interact: clicks reach the page."); (6) the question row goes away (keep writing); (7) full screen ends: the file goes back beside the thread with focus on the header switch's Side by side ("Side by side: the file is beside the thread."; never saved as the choice), or, where it can only be full screen (a phone, a stacked window), back to the thread through the usual unsaved-comment question. The pane's own controls keep their Escape first (the peek, ⋯, the count, the revealed toolbar's tuck, a focused button's tooltip, the question row), and the ladder runs after them, on the document in the bubble phase, so the window's listeners (the HTML viewer's own Annotate rung, the selection toolbar's dismiss) see the key used; it stands down under a `dialog[open]` or the image annotator, while a selection toolbar or quick-label picker closes itself, and in a text field other than the image/film row. From inside an HTML page: Annotate's Escape (the bridge's `annotate-exit`, `onAnnotateModeExit`) is a rung of the same ladder in full screen (so the drawer closes before Annotate; beside the thread it still goes straight to Interact), and in Interact the bridge offers an Escape the page did not use as `page-escape` (`HtmlViewer`'s new optional `onPageEscape`: honored only in Interact, with the frame focused, at most once per 150 ms; the bridge sends it only after every handler of the page had its turn, when none cancelled it or stopped it on its way to the window, focus is not in one of the page's text fields and no `dialog` of the page is open), which climbs the ladder; a rung taken from inside the page leaves focus in the page. Beside the thread there is no ladder. Annotation works as beside the thread on every kind (HTML pen and pinpoint, markdown selection, the image and video comment rows, code lines, diagrams). Tests: `packages/inbox/fullView.test.tsx` (the pane: the one mode and focus, tuck / reveal / pin and focus, the corner's timing, the drawer and its remembered state, a new comment only bumping the count, the toolbar always starting out, ⌘⇧X on HTML only, ⋯, the peek and steps, the Escape ladder on markdown, HTML (from the window and from the page's messages), an image and a stacked window, typed words asked about, where it stands down, the changed chip and dot, a phone, a stacked window), `packages/inbox/escapeLadder.test.ts` (the order per kind of file), `packages/inbox/fullScreenThread.test.tsx` (the whole window over `inbox-dom-server.ts`'s `open-in` world: HTML opens with the toolbar showing whatever the shared cookie says and never writes it; the drawer comes back with the next file), `tests/e2e/inbox-full-view.spec.ts` (compiled binary, Chromium, a desktop WebKit window and an iPhone in WebKit: the whole Escape ladder, a page menu that uses Escape itself left alone; screenshots of every state, light and dark).
  - **Side by side, remembered** (approval `inbox-side-by-side`, 2026-10-22; not in this repo; `packages/inbox/fileView.ts`). The view beside the thread is named "Side by side". Beside the thread the pane header holds a two-part switch (`data-view-switch`, `role="group"` "View"): **Side by side** (`data-view-side`, pressed, `aria-pressed="true"`) | **Full screen** (`data-full-screen-toggle`); in a pane under 780 px the two parts are icons only, still named (`aria-label`); full screen's toolbar holds the labelled **Side by side** (`data-full-view-exit="exit"`). A press on either (`pickView` in `Thread.tsx`) applies now and is remembered for every file kind (a press on the switch's pressed half saves the view on screen without moving the file, `onKeepView`, so side by side can be chosen before any trip through full screen), in the cookie `plannotator-inbox-file-view` (`full` / `side`, through ui's `storage` like the comments drawer's: cookies ignore the port, so it holds when the Inbox comes back on another port); Escape's last rung and a Send are not picks and save nothing. When the remembered choice changes, the window's one toast says so ("Files open side by side now · until you choose Full screen", or the full-screen words; its `speech` for the live region) with Undo (the old choice back; the file's old view back only when the press moved it and it is still the file open, so a file opened since keeps its frame). Until the first pick, today's rule: an HTML page and an image from a message's text open full screen, everything else side by side (`kindDefaultView`). The view rides the address (`&view=full|side`, `Route.file.view`): a tile or link opening writes it (`openingView`: the choice, else the rule), a step, a version, a linked page and a comment card carry the current one (`currentView`), and opening the file already open (a comment card in the reply box, its tile again) keeps its view, so a one-off view from a tile's ⋯ stays; a reload or a shared link opens the same way. A linked page's Back finds the page's entry whatever view it names (`backTo(…, sameScreenAnyView)`, `hashWithoutView`) and, once the traversal lands, replaces that entry's view with the one on screen; a link without it (an agent's link, a search result) uses the choice, then the rule (`fileViewFor`: no room → full; else the address, else the choice, else the rule). Each tile's ⋯ (`OpenInTileMenu`, only where "Open in" offers apps) leads with **Open side by side** / **Open full screen** (`data-open-as`): that one file in that view, the choice unchanged; a tile that only downloads (`opensInWindow` false) has none. A phone and a stacked window (`fileStacked`) always show the file full screen with Back to the thread: no switch, no tile items, nothing saved (the address still carries the logical view). No keyboard shortcut. Tests: `packages/inbox/fileView.test.ts` (the order room, address, choice, rule; the cookie; the view-blind hash), `history.test.ts` (a Back that ignores the view), `packages/inbox/sideBySide.test.tsx` (DOM over a real Inbox: the switch and its pressed half, the toast and Undo bound to its file, Escape saving nothing, the tile items, a comment card keeping a one-off view, the address winning, steps keeping the view), `htmlLinks.test.tsx` (a linked page's Back after a switch), `tests/e2e/inbox-side-by-side.spec.ts` (compiled binary: an in-text image → Side by side → the next HTML page beside → a reload keeps it → a tile's Open full screen leaves the choice; an iPhone in WebKit always full screen). Specs that share one browser context and press a view button run `forgetFileViewChoice` (`tests/e2e/file-view.ts`) in `test.afterEach`, so each test starts from the rule.
  - A markdown or raw-HTML link in an agent message (body or question context) to one of THAT message's attachments opens it the same way, focus in the pane (`packages/inbox/links.ts`: matched client-side against the message's attachment records by realpath or `named_path`, relative to the message's `base_path` then the project root, a bare name when only one attachment has it, `?query`/`#fragment` ignored; through `Viewer`'s optional `resolveLocalLink` seam, `packages/ui/components/LocalLinkContext.tsx`, absent on every other host). Its tooltip names the file's path in the project, and its href is the window's deep link `#thread=<thread id>&file=<attachment id>`, so a new tab, drag or copy opens the same file. Any other local link renders as inert text titled "Not attached to this message", with no href, so nothing is fetched; http(s) links are unchanged.
  - Links INSIDE an attached HTML page (`packages/inbox/htmlLinks.ts`, wired in `AttachmentPane.tsx`). The page's bridge never lets the frame navigate and hands the raw href over on a plain click, in Annotate (the default) and Interact alike; `Cmd`-click (`Ctrl`-click off macOS) while armed pins the link for a comment instead, the one rule every HTML surface follows (see "Links between local HTML documents"). `resolveInboxHtmlLink` reads it with annotate's `resolveHtmlLinkIntent` (relative to the folder of the page it is in, root-relative to the attached page's folder, the query dropped, the fragment kept), then: a file of the thread (an attachment or a captured message image, by realpath or `named_path`) opens in the pane as a NEW history entry (`onOpenLinked` → `onOpenFile` without replace, so the browser's Back returns to the page; the frame is kept, full screen stays full screen; a typed comment asks first; a fragment rides as `initialFragment`, cleared once used); another `.html`/`.htm` in the attached page's folder that is not attached opens read-only over the page (`GET /api/inbox/attachments/:id/linked-page?path=<relative>`, the page with its own `<base href>`), after the same unsaved-comment question as any file it would leave: a band "‹ Back to <page>", "<name> is not attached, so comments are off." and Open in new tab (its asset URL), the attached page kept mounted under it (`ib-covered`, `inert`) so Back finds it as left. The page on screen is in the route (`#thread=…&file=…&linked=<path>%23<fragment>`, `Route.file.linked`), one history entry per page, so the browser's Back and a phone's swipe back step back one page (the band's Back is the browser's Back when the entry was opened from there, `onOpenFile(…, { back: true })` → `backTo`); the pane keeps the stack that follows it (per attachment, cleared when the file or version changes; a reload of a `linked=` address opens that page). Escape steps back one page: the `linked` rung of the full-screen ladder (after the drawer, before Annotate) and, beside the thread, the one rung there for a key from inside the pane or the page. In full screen the band floats top left and the page starts below it (`--ib-linkband-h`). The linked page runs in Interact (`annotateModeActive={false}`, `readOnly`), its own links follow the same rules, and a link back to the attached page is a new entry with no linked page; the pen hides while a linked page shows, the comments panel says "Off on <page>", and a card picked there goes back to the attached page first. A local image in that folder that is not attached opens in `ImageLightbox` through the attached page's own asset route. Another site opens a new tab. Anything else (another kind of file, outside the folder, a hidden path or dotenv name, another scheme, a link that cannot be read) shows a note at the page's foot for 5 s (`[data-link-note]`, `LINK_NOTE_MS`) and says it in the pane's live region; never silent. No new keys. Phone and full screen the same (the band floats top left in full screen, 44 px targets on a phone). Tests: `packages/inbox/htmlLinks.test.ts` (the mapping), `packages/server/inbox-linked-page.test.ts` (the route), the DOM test `packages/inbox/htmlLinks.test.tsx` (over `inbox-dom-server.ts`'s `html-links` mode), `tests/e2e/inbox-html-links.spec.ts` (compiled binary; light, dark, a phone; screenshots to `PLANNOTATOR_HTML_LINKS_SHOTS`).
  - Viewers: markdown and text through `Viewer` with the annotation toolstrip, diagrams through `DiagramViewer` (node comments), HTML through `HtmlViewer` (pinpoint, shift-click joining more elements to one comment as in annotate, pen, Esc to Interact), images on ui's `ImageZoomStage`, the lightbox's (`ImageAttachmentView.tsx`; the owner's ask, 2026-10-22: "trackpad finger gesture zoom"): Ctrl/⌘ + wheel and a trackpad pinch (Safari's gesture events too) zoom about the pointer, a plain wheel scrolls an image larger than the stage and zooms one that fits, a drag or one finger pans, two fingers pinch, a double click (or double tap) toggles Fit and 2× Fit, Fit to 800%, transforms only (Fit, Actual size and a double click ease 180 ms, none under reduced motion; gestures never animate). The size bar shows the scale ("152%", `data-image-zoom`) between the image's size and Fit / Actual size, which reset it. Fit leaves the stage's padding (28 px, 12 on a phone; `padding`), a tall screenshot (taller than twice its width) fits its width from the top and a panorama (wider than `WIDE_IMAGE_RATIO`) its height from the left (`fitAxis`), and either pinches out to the whole image. The focused stage pans with ↑ ↓, Page Up / Down, Home / End and Space; ← → and ] [ always step (no `data-claims-arrows`). The pane remembers Fit / Actual size per file; a gesture's zoom is not remembered, so a step (or another version) opens at Fit. Ctrl + wheel over the size bar or the chip never zooms the page. A comment box sits under the image, and code through ui's `CodeFileView` (the body of `CodeFilePopout`: Pierre's `File` with line and range comments; plain text above `CODE_HIGHLIGHT_MAX_CHARS`, 100,000 characters; lines wrapped, `overflow: 'wrap'`, when one is over `CODE_WRAP_LINE_CHARS`, 1,000, as in a minified bundle). Data and log files (`.log`, `.yaml`/`.yml`, `.json`/`.jsonc`/`.json5`, `.toml`, `.ini`, `.cfg`, `.conf`, `.properties`, `.csv`, `.tsv`, `.xml`, `.env.example`), stored as kind `text`, are drawn with the code view too (`inboxViewKind`, decided on screen, so files already sent show that way; a text comment left on one before shows as Unanchored); `.txt` keeps the text view. The phone surface keeps code as ONE read-only code block (`codeDocumentBlocks`) and draws a plain card for image, video, pdf and file, which the shell shows natively.
  - Image comments reuse ui's `ImageAnnotator`: "Mark up" draws on the image (pen, arrow, circle); the PNG is posted to `POST /api/inbox/markups` (same-origin, `?serverSession=`), kept once as `inbox/markups/<sha256>.png` (`packages/shared/inbox/markups.ts`), shown back by name at `GET /api/inbox/markups/<name>` (`inboxImageSrcResolver` maps the path), and rides the comment's `images`, so the feedback names a file the agent can open. Selecting a comment with a drawing lays the drawing over the image in the image's own transform (`overlay`, `data-zoom-overlay`), so it stays aligned at any zoom and pan and the zoom is kept; "Show the image" takes it away. A markup the deleted thread's or project's annotations named, and no remaining annotation names, is removed with it; one no annotation names yet (uploaded, the comment not saved) is left alone.
  - Videos (`packages/inbox/components/VideoAttachmentView.tsx`; design record "inbox-video", approved 2026-10-15 with the owner's answers: the frame rides each Mac comment, the phone app plays natively, v1 plays over the Wi-Fi or the tailnet only). The tile reads "MP4 video · 7:41 · 1920 × 1080 · 461.0 MB" (`inboxVideoMeta`; a WebM: "WebM video · size") with "Play", and the pane header names the length and size. The pane plays the film in a native `<video controls preload="metadata" playsInline>` from the `video` route with `#t=0.001` (the first frame as a poster), fit to the stage (`.ib-vidstage` is a size container: the box is `min(100cqw, (100cqh - rail) * aspect)`), full screen through the native button. Under it a rail: one dot per comment at its moment (a click seeks there, pauses, selects the comment), the playhead, and a dashed dot for the comment being written. Under that the comment row: the moment (`m:ss`, `h:mm:ss` from an hour), the frame, the text box, Mark up, Comment. Typing pauses the film and pins the moment (the chip turns into a button that seeks back to it; clearing the words lets it follow the film again) and grabs the paused frame, drawn from the `<video>` to a canvas (same origin, never tainted) as a full-size JPEG (`captureVideoFrame`). Mark up opens ui's `ImageAnnotator` on that frame; the drawing is kept through `/api/inbox/markups` as for images. Comment uploads the frame (or the drawing) as a markup and saves the annotation; a frame that cannot be grabbed or kept leaves a timestamp-only comment. The panel is "Comments · By time" (`AnnotationPanel`'s `title` / `titleNote`) and lists the film's comments by time (`compareAnnotations` with `compareVideoTimes`), each card topped by its time pill (a click seeks) and its frame (a pen badge on a marked-up one) through `renderCardHeader`, without the built-in quote or image row (`cardParts`); a card selected anywhere seeks too (`VideoAttachmentViewHandle.seekTo`). While the video has focus the stage claims the arrow keys (`data-claims-arrows`; the native player seeks), and `]` / `[` still step. No new keyboard shortcut. A media `error` (other than an abort) shows the Download card ("This video's format can't play here"). On a phone the film sits on top with "7:41 · 1920 × 1080 · N comments", the rail, the comments listed under it (a tap seeks), and "Comment at 1:42" at the foot, which pins the moment and opens the row (with Cancel). The phone APP plays natively (AVPlayer / ExoPlayer, the Workspaces repo); its comments are timestamp-only in v1 (the door has no upload route). Annotations on a video: `blockId: "video"`, `inboxVideo: { time }` (seconds, millisecond precision; `INBOX_VIDEO_BLOCK_ID`, `readInboxVideoTime`, `videoCommentAnnotation`), the frame as `images[0]` named "<stem> at 1:42"; `saveAnnotation` refuses another `blockId` or a missing or negative time on a video (`422 validation_error`). Open in: the OS default player for a video whose own extension is `mp4`, `m4v`, `mov` or `webm` (bytes checked again at launch), Finder otherwise. Tests: `packages/shared/inbox/video.test.ts` (sniffing and the header walk, a 461 MB film read by seeking, a real ffmpeg encode when ffmpeg is on the PATH), `packages/server/inbox-byte-range.test.ts`, `packages/server/inbox-video.test.ts` (kind, Range, If-Range, the sent version, `/download`, annotations, the door and a relay command), the DOM test `packages/inbox/videoAttachment.test.tsx`, `tests/e2e/inbox-video.spec.ts` (a VP8 WebM Playwright records, played, seeked, commented, sent) and the `export_feedback` step in `tests/e2e/surface.spec.ts`; the films are built in the tests (`tests/helpers/video-fixtures.ts`), never committed.
  - Code comments are stored as Plannotator annotations with `blockId` `code-L<start>-<end>` and `inboxCode { lineStart, lineEnd, code }` (`codeCommentAnnotation`; lines over `CODE_EXCERPT_MAX_CHARS`, 4,096, keep a cut `code` plus the whole `length` and a `hash`, matched by `codeRangeMatches`, and a record from before that keeps the whole lines still matches by its text); the export labels them "(lines 12–14)", and one whose lines changed shows Unanchored.
  - `AnnotationPanel` sits at the right. A pane narrower than `FOLD_PANEL_BELOW` (780 px; a file beside the thread at about 920 to 1220 px) folds it into the header's Comments button (`data-annotations-sheet`, the phone's) and opens it over the file's right edge with the sheet's title and close (`.ib-fold`, the panel's embedded presentation; the button names the sheet with `aria-controls`, and the close or Escape inside the sheet closes it and puts focus back on the button, on a phone too); a 1280 px window keeps it docked; full screen has its own drawer (below). A PDF, any other download, and a file too large to show have no panel and no Comments button unless other files have comments (`hasPanel`, `.ib-nopanel`).
  - Markdown, text and diagrams are always the Clean look: the document on `bg-card`, edge to edge in the pane (`Viewer`'s `gridEnabled` false). The Inbox does not read plan review's `gridEnabled` setting (its cookie `plannotator-grid-enabled`), so a Grid choice there never puts an attached file on grid paper (owner, 2026-10-22).
  - The changed line reads "Changed since <agent> sent it at 10:42 AM. Edited 11:05 AM. Open the version it sent".
- Annotations live in `annotations.jsonl`, keyed by the file's path and version (`current` or the sent sha256). A draft on `current` survives the agent's edit and re-anchors by its text. `saveAnnotation` refuses an annotation on a pdf, file or unknown kind (`422 annotation_not_allowed`); a video takes them (at a moment, above).
- Send carries the annotations as Plannotator's feedback text (`exportLinkedDocAnnotations`, under "Feedback on the attached files", one section per file and version, a file outside the project named by its absolute path) and marks them sent with the reply. A video's comments go by time, each with a line under its heading, `At 1:42 (102.4 s of 7:41)` (`videoLocationLine`; without "of …" when the length is unknown, as for a WebM), then the comment and the frame's path under "Attached images" (`attachmentFeedback` hands the exporter copies carrying ui's export-only `exportLocation`; the store drops an `exportLocation` a client posts, and the export drops one a stored record carries, so only the computed line prints). The caption counts a video's comments with the same separator: "WebM video · 81.8 KB · 2 comments". The phone surface's `export_feedback` runs the same function, so its Send keeps them too (an OLDER surface reads `video` as `file` and drops them).
- Comments other than an image's markup or a video's frame take no images.
- Delete thread rewrites the project's files without the thread's lines. Delete project removes its folder. Both then remove every blob and markup that no remaining record uses.

**Comments on the text of an agent's message** (approval `.product/approved/inbox-message-comments/`, 2026-10-19: "Build it now, the file-comment way"; `MessageBody`'s `comments` in `packages/inbox/components/Thread.tsx`, `saveMessageAnnotation` in `packages/shared/inbox/store.ts`, `messageFeedback` in `packages/inbox/attachments.ts`).
- Words selected in an agent's message (not folded, not the person's own, not a message an archive closed: `liveMessage`) open ui's selection toolbar comment-only, as on an HTML file: Comment and the one-click 👍 Looks good (no Delete, no label picker). Comment opens the same composer as a file's; ⌘↵ or Save stores it. ui's seam is `Viewer`'s `textComments` (with `answerOnly`: the selection toolbar, its composer and the highlights come back, nothing else of authoring; question cards are wrapped `annotation-exclude`, so their words are never commented on). The message keeps the passage's light highlight, drawn again from the store by its words on every mount (Unanchored in the reply box's list when the words are not found). A refused save takes its highlight away and shows the error.
- Stored like file comments: `POST /api/inbox/messages/:id/annotations` (`{ serverSession?, annotation }`, Plannotator's text-selection annotation, `type: "COMMENT"`, `originalText` the words as rendered, at most 20,000 characters, `INBOX_MESSAGE_COMMENT_QUOTE_MAX`; `text` required, at most 10,000, `INBOX_MESSAGE_COMMENT_TEXT_MAX`, a 👍 carrying its label; no `images`, `elementContext`, `pageUrl` or `inReplyTo`), a line in `annotations.jsonl` with the additive `message: { at: <the message's created_at> }`, `attachment_id: ""`, `path` the message id, `version: "current"` (so an older reader sees a record whose file it cannot find and exports it under the message id). An edit is the same id; removal is `/api/inbox/annotations/:id/remove`. Refused: the person's own message `422 annotation_not_allowed`, not a comment `422 validation_error`, an id used on a file, a guide or another message `422`, `404 message_not_found`, `409 thread_resolved` before an archive line, `409 annotation_closed` once sent or removed; the window's same-origin and `serverSession` guards.
- They wait in the reply box's "N annotations" chip with file and guide comments ("Claude Code's message, 2:58 PM", the quote, the comment; a click brings the passage into view and rings it), ride the next Send in `annotation_ids`, and are marked sent with the reply. Each goes to the session that wrote its message (`routeSendAnnotations` in `packages/inbox/sendTargets.ts`, beside `sendTargetsOf`, both moved there from Thread.tsx): a comment whose message the last reply reaches (that message, or one its session wrote) rides the last reply with the words and the file and guide comments; any other rides the reply to its session (one reply per session, approval "inbox-explicit-skip"), or, when that session has none, a reply to its own message, added to the Send's targets in thread order (a comment never rides two replies), with its own skills block and idempotency key. The feedback text leads with them (`messageFeedback`, before the files' and the guide's sections): `# Feedback on your messages`, then per message `## Feedback on your message from 2:58 PM (msg_…)` (the person's local time from `message.at`, plus the id so the agent can find it), then each comment (`### 1. Feedback on: "<the words>"` and every line of the comment as `> …`; words on several lines, which can hold a code block or a line starting with `#` since they are the rendered text, go in a fenced block sized with `codeFenceFor` under `Feedback on:`), no line numbers. The phone surface's `export_feedback` runs the same function, so a phone's Send carries them too; the door takes them as 7.59.
- While the toolbar shows it owns the keys as on a file: Escape closes it, never the thread, and a letter starts a comment (`selectionToolbarShowing` in `packages/inbox/selectionToolbar.ts`: the thread's Escape, E, Z, j, k and n stand down). Paste-follows-the-field does not: words selected in a message are an offer the person may ignore, so a dictated ⌘V still lands in the reply box (`messageSelectionPending` in `pasteTarget.ts`), and the pending highlight and toolbar close as it moves there (a mousedown dispatched on the field, which ui's toolbar takes as a press outside it). Drawing highlights moves text the search landing highlight's ranges point into, so the thread paints that highlight again (`repaintHits`). No new keyboard shortcut.
- Tests: `packages/server/inbox-message-comments.test.ts`, the door case in `inbox-devices.test.ts`, the DOM test `packages/inbox/messageComments.test.tsx` (the DOM server's new `wait` stdin command calls `wait_for_reply` through the Inbox's MCP), a case in `pasteTarget.test.ts`, and `tests/e2e/inbox-message-comments.spec.ts` on the compiled binary (desktop and a 390 px window, light and dark).

**Images in a message** (#1813; `packages/shared/inbox/message-images.ts`, `packages/server/inbox-message-images.ts`, `packages/inbox/images.ts`).
- A message body's (an agent's or the person's own) `![alt](path)` and `<img src>` load through `GET /api/inbox/messages/:id/image?path=<src as written>`. The window draws each body with `imageBaseDir` = `inbox-message:<id>` and installs `inboxImageSrcResolver`, which maps that marker to the route. There is no route that takes a bare path.
- The rules, in order: the path must appear in THAT message's body as an image reference (`inboxMessageImageRefs`: the markdown target as written, the `<img src>` value decoded), so the route cannot probe other files; an image extension (png jpg jpeg gif webp svg avif bmp ico apng) before anything is read, else `415`; a relative path resolves against the message's `base_path` (the realpath of the agent's `project_path` when it is a subfolder of the project or a linked worktree folded into it, recorded at send time, additive) else the project root; for an AGENT's message (`anywhere: message.author.kind === "agent"`, set by the route, the send-time capture and the on-open capture) the file may be anywhere the person's user can read, as an attachment may (owner ruling 2026-10-16: no project boundary; `/tmp` vs `/private/tmp` spellings work), while the PERSON's own message (which a paired phone, the relay or an allowed tailnet login can post) keeps the old boundary, the project root or its `base_path`, judged as named and by realpath (`403 outside_project`); either way it is refused when attachments and the wide asset roots would refuse it, `403 image_hidden`: a dotenv-family name anywhere (`isDotenvFileName`), and outside the project root and the `base_path` folder any segment starting with `.` (`refusesHiddenHtmlAssetPath`: `~/.ssh`, `~/.config`), judged by the realpath AND by the name in its folder's real location, so a symlink into a hidden folder, or one kept in one, is refused (hidden folders inside the project and the folder sent from stay allowed: screenshots in `.walkthrough/` or `.playwright-mcp/`, a project under `~/.claude/worktrees/`, a worktree under `.codex/worktrees/`; but a project or base that is `/`, the home folder (`HOME` and `os.homedir()`) or above it exempts nothing, so a project at `~` never serves `~/.ssh` or `~/.cache`); `EACCES`/`EPERM` is `403 image_unreadable` and an unforeseen read error `500 image_read_failed`, never `image_missing`; remote sources (`http(s):` and protocol-relative `//host/…`) are never referenced, so never read as a local path; the realpath is opened once with `O_RDONLY|O_NOFOLLOW|O_NONBLOCK` and everything after reads that descriptor (`fstat`: a regular file, so a FIFO or device is refused without blocking; at most cap + 1 bytes read; the path re-checked to lead to the same dev/ino, else `409 image_changed`); at most 10 MB and 50 megapixels (`413`), its type sniffed from magic bytes (`sniffImageContentType`, `415` when not an image). `?query` / `#fragment` are dropped and `%xx` decoded as fallbacks.
- Every answer carries `X-Content-Type-Options: nosniff`, `Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline'` and `Cross-Origin-Resource-Policy: same-origin`, no CORS, plus `X-Image-Width` / `X-Image-Height` when the header parses; GET and HEAD only (`405`); `Sec-Fetch-Site: cross-site` / `same-site` is refused (`403`).
- Remote `http(s)` images stay as written and do not load: the window's CSP is `img-src 'self' data: blob:`. Images inside an attached markdown file are not served (only message bodies). A 200 carries `ETag` (the SHA-256 of the bytes served) and `Cache-Control: private, no-cache`; `If-None-Match` naming it answers `304` with the same headers, and a changed file gets a new ETag. The device door forwards `GET messages/:id/image?path=` to this route (its `If-None-Match` too), so a paired phone gets the same bytes, headers and refusals, an image in a `:::question` block's context included (the body is the whole message); the phone apps decide how to draw it, caching by message id plus path and revalidating with `If-None-Match`. The "referenced in that message's body" rule limits what an agent's message exposes, not what the person's own clients can read: a paired device, like the window, can send a reply that references any image-type file of 10 MB or less under the project (outside its hidden-folder rules) and then read it, so a device token is as powerful as the window (revoke a lost phone), and over the relay the phone gets the image bytes with only a content type, so the app must draw an SVG as an untrusted image. Over the relay the result is the bytes base64 twice, about 16/9 of the body: an image at the 10 MB cap is a frame of about 17.8 MiB, inside the 32 MiB limit (`inbox-relay-bounds.test.ts`).
- **The send says which images won't show.** send_message and submit_guide (`sendAgentMessage` in `packages/server/inbox-mcp.ts`) turn the send-time capture's refusals (`CapturedInlineImages.failures`, the route's own codes: `image_missing`, `image_unreadable`, `image_read_failed`, `not_an_image`, `image_too_large`, `image_hidden`, `validation_error`; a transient `image_changed` or `write_failed` still shows through the route and is not named) plus the body's remote images (`inboxMessageRemoteImageRefsInOrder`: `http(s):` and `//host/…`, outside code; the window's CSP blocks them) into an additive `images_not_shown: [{ ref, reason, not_yet? }]` in `structuredContent` (absent when every image shows; at most `IMAGES_NOT_SHOWN_MAX`, 10, with `images_not_shown_more` counting the rest) and sentences appended to the result text (`imagesNotShownText`: "The message was sent, but N images will not show: <ref> (<reason>); …and N more. Save the image as a local file outside hidden folders and link that path, or attach it with attachments."). A file not on disk at all (`notYet` on the failure, `not_yet: true` on the entry) is said apart: "This image does not exist yet: <ref> (…); it shows once written there.", since the on-open capture and the route pick it up once it is written. The message is always sent. The Claude Code mod, Pi and OpenCode hand the text and the structured JSON through unchanged (`inboxToolResultText`). Images past the send's 64 are not checked. Tests: the last tests of `packages/server/inbox-message-images.test.ts`.
- **Captured as files of the thread** (approval `inbox-image-viewer`, 2026-10-15, not in this repo; `packages/shared/inbox/inline-images.ts`). When an agent's message lands (`sendAgentMessage`, send_message and submit_guide), each image its body shows (`inboxMessageImageRefsInOrder`: markdown and `<img src>`, outside fenced code and inline code spans (`blankInlineCode`, one linear pass), in text order, each once, at most 64 at send) is read under the rules above (`readInboxMessageImageAsync`: the same locate step and one-descriptor checks as the route's read, through an async file handle, returning the realpath, the named path and the mtime), copied to `inbox/blobs/<sha256>` (staged as `.send.*.tmp` until the store accepts the message, removed on a refusal or an idempotent replay; every read and write async, yielding between images), and kept on the message as the additive `inline_images: InboxInlineImage[]`: an attachment record (`att_` id, realpath, `named_path`, `kind: "image"`, sent blob, size, `media_type`, dimensions, `sent_at` = the message's time) plus `ref`, the src as written. An image that cannot be read is left out for now; it never refuses the send, but the send tells the agent (below). A body with no local image gets no field; one whose images all fail gets `[]`. Images with no record yet (a message sent before this, an image written after the send, past the send's 64, a transient refusal, the person's own messages) are captured after a read of the thread (`GET /api/inbox/threads/:id` and `…/attachments` call `imageCapture.schedule`, `createInboxImageCapture` in `packages/server/inbox-message-images.ts`), in the background: the read answers at once, one thread at a time, the copies staged as `.send.*.tmp` and moved into `blobs/` only right after the records naming them are written (so a deletion's blob sweep, which keeps only blobs a record names, never removes them; a send stages even a blob that exists for the same reason), nothing written after the server stops, a yield between messages and images, a 25 ms pause after each 32 MB read; a refusal decided before any read (not on disk yet) is tried again on the next read, one that cost a read (not an image, changed while read, too many pixels; type and pixels are judged from the first 64 KB, before the rest is read) after 60 s (remembered per message, least recently tried dropped past 10,000 messages). The records arrive as one more line for the message (`store.imageCaptureGaps` / `store.addCapturedImages`, its latest snapshot with the new records in text order; the seq, list and routing are unchanged, proved in the thread-state model), each marked `captured: "on_open"` and `captured_at`, and the event stream makes the window read the thread again. `InboxServer.imageCapture.idle()` lets tests wait. Everything else is the attachment path: `store.attachment(id)` finds them, so `attachments/:id/image`, `download`, "Open in", annotations, the door and the relay reach them by id; the image route keeps the 10 MB / 50 MP caps on an inline image's current file, and `/download` the 10 MB one (`413 image_too_large`; the sent version still opens). `GET /api/inbox/threads/:id/attachments` lists them in its additive `inline_images` (never in `attachments`, so an older phone app draws nothing extra; the contract's 7.14). Blob usage and the deletion sweeps count them. The window: the body still draws them from the message route; every image the body loads from the message route is a button (`role="button"`, Enter / Space; `MessageBody`'s `onOpenInlineImage`, through ui `Viewer`'s new `onImageClick`, and a click listener for raw-HTML blocks): a captured one opens in the file viewer full screen (`openFile`: HTML and inline images full screen, everything else as before; a step keeps the frame), one with no record yet in the plain `ImageLightbox`, so a click always opens something; one that failed to load, and a `data:` image, is not a button. An image in the person's own message reads "You · <time>" in the viewer and "image in my … message" in the export. Its header reads "<agent> · <time>". "Changed since <agent> sent it" applies as for attachments; an `on_open` copy reads "Changed since you first opened it" and "Open the version you first saw". Comments are attachment annotations; the export names it by its `ref` plus the message (`exportFileLabel`: "## design/b.png (image in your 11:22 AM message)"; the same path in another message within the same minute adds the seconds, then the message's place) and the intro then says "the files you attached and the images your messages showed". A comment whose file the caller does not list (an older phone app's `export_feedback`) is exported under the path it was made on, never dropped. Tests: `packages/server/inbox-inline-images.test.ts` (with health answering under 250 ms while 96 MB are captured), `packages/inbox/attachmentsExport.test.ts`, the door case in `inbox-devices.test.ts`, the store model in `store.test.ts`, the DOM tests `packages/inbox/inlineImages.test.tsx` and `attachmentStepping.test.tsx`, and `tests/e2e/inbox-image-viewer.spec.ts` (compiled binary; desktop Chromium, an iPhone in WebKit, and annotate's light version).

**Decisions were removed (2026-10).** The owner removed Decisions from the Inbox (and from Workspaces): no Decisions page or sidebar row, no decision tag, switch, card or "Settled" line on a question card, no `decision_recording` / `decision_draft`, no `list_decisions` or `record_decision` MCP tool, no search group, no phone door rows. What stays, for old data: an older store's `projects/<key>/decisions.jsonl` is left on disk untouched, kept only so sequence numbers are never reused (never rewritten, its records never applied; the store reads only its highest seq, so a seq is never handed out twice: `legacySeqFloor` in `store.ts`, `LEGACY_DECISIONS_FILE` in `schema.ts`), Storage still counts its bytes, and a question record an older Inbox wrote may still carry `decision_on_answer`, `decision_id`, `decision_recording` and `decision_draft`, which nothing reads (the wire never carries them). A `Decision:` line an older agent wrote in a question block is context: the Inbox parses with core's `parseQuestionBlock(kind, body, { decisionLines: false })` (the server, `parseInboxQuestionBlocks`) and draws cards with ui `Viewer`'s `questionDecisionLines={false}` (thread, attached files, the surface), so the line shows as context and no tag or row appears. The line still ends the choice, bullet or recommendation above it exactly as the default parse does, so prompt, key and choices are always the default parse's, and a record an older Inbox stored takes the label the window sends (`packages/server/inbox-legacy-decision-line.test.ts`). Plan review and other hosts keep core's default (`decisionLines: true`). Proved by `packages/shared/inbox/store-legacy-decisions.test.ts` and `packages/core/question-block.decision.test.ts`.

**Question cards in the Soft look.** The card is restyled from `inbox.css`, never in ui: a raised, borderless surface, the eyebrow in sentence case, the tags quiet pills, its accent stepped for the surface (all `--ib-soft-card`, whose `initial` gives back ui's card exactly, each tag in its own tone), and Accept recommended a soft pill (`--ib-soft-accept`, on: not a colour, so Soft by the owner's 2026-10-17 ruling). The thread's other Soft parts each have a switch too, on for the same reason: `--ib-soft-hbtns` (the header's buttons borderless; Mark read's `E` a small keycap, the text colour at 9%, 18 px wide at radius 5, reaching into the button's end padding so label and key read as one control), `--ib-soft-foot` (Reply, Looks good and Send as filled pills, the reply box's glow, pill chips) and `--ib-soft-surfaces` (attachment tiles, the read line, the route chooser and the fold as raised surfaces; a tile's Open shows on hover or focus, always on a screen without hover; while it is hidden it holds no room: on a screen with hover it is taken out of the row at rest (invisible), so the name keeps the tile's whole width and is never cut more than today's, and the moment it shows (the tile hovered or focused from the keyboard, or its ⋯) it is back in the row, so the name is cut again before it and keeps its end (date, extension) in either direction; the file open beside, and screens without hover, keep its room; a guided review's +N / -N on its tile step toward the card's ink, 50% as the Stopped badge's words do, so they read at AA on every palette in both modes).

**Guided reviews** (`packages/server/inbox-guides.ts`; code diffs only, in Plannotator's portable format).
- `get_guide_brief` answers the authoring brief in the shape Workspaces' tool gives agents: `methodology`, `output_schema`, `diff_steps`, `rules`, and an `example` that works as it is.
- `submit_guide` takes `guide` plus `patch`, or `snapshot`, plus `body` and send_message's routing fields.
- Validation is Plannotator's own (`parseGuideSnapshot`, `buildAuthoredGuideSnapshot`'s placement checks). A refusal is `invalid_guide: …` naming the file.
- The snapshot is stored as a blob only after the message lands. The message carries `guide: { sha256, input_sha256, bytes, title, sections, files, additions, deletions }`. Idempotency compares `input_sha256`.
- The window: the message shows the guide as a card. Open (`#thread=…&guide=<message id>`) takes the window: Plannotator's `GuideView` over review-editor's `AllFilesCodeView`. The reader mounts only through a `lazy()` import, guarded by `tests/entry-assets.test.ts`.
- Comments on the diffs: the person comments as in code review (click a line number, drag across line numbers, or select code; the review app's toolbar and inline comment cards). `AllFilesCodeView` runs with `commentOnly` there: line selection, the toolbar and the inline comments on, the keyboard shortcuts and the header's open-in off, as for `readOnly`. guides.show and the phone stay `readOnly`.
  - Each comment is the review app's `CodeAnnotation`, kept as an annotation record in `annotations.jsonl` (`POST /api/inbox/messages/:id/guide/annotations`, an edit is the same id, removal is the attachments' remove route): `attachment_id` empty, `path` the file as the patch names it, `version` the guide snapshot's sha256, and the additive `guide: { title, file, side, line_start, line_end }`. The store refuses a file not in the guide's patch, a bad side, a line range not inside one hunk of that file's patch (`isLineRangeInPatch`, now in `@plannotator/core/diff-files`), a message with no guide (`404 guide_not_found`), a resolved thread, and an id used on an attachment.
  - The guide pane lists them in Plannotator's `AnnotationPanel` (edit, delete, a click scrolls to the comment), folded below `GUIDE_FOLD_PANEL_BELOW` (1,200 px; the guide takes the window) into the header's Comments button (`data-guide-comments-sheet`), as the file pane's is (at 900 px and below it used to be hidden with no way to it); the thread's "N annotations" chip counts and edits them with the attachments' annotations ("src/auth.ts (guided review)", "lines 2-3"), on a thread with no attached file too; an attached file's pane lists only the files' annotations, never the guide's comments.
  - Send carries them after the attachments' feedback, under `# Feedback on the guided review` (one section per guide), in the review app's export format: `## path`, `### Line N (side)`, the comment, the commented lines as `**Highlighted text:**`, any suggestion (`guideFeedback` in `packages/inbox/attachments.ts`, kept equal to `exportReviewFeedback` by `packages/inbox/guideFeedback.test.ts`). They are marked sent with the reply. The phone's `export_feedback` uses the same function, so a phone Send carries them too; the phone's door takes a comment on the diff (`POST messages/:id/guide/annotations`, contract 7.53; removed through `annotations/:id/remove`), while the surface's guide reader itself stays read-only.
  - A resolved thread shows the guide read-only.
- Reviewed ticks are kept on the message (`POST /api/inbox/messages/:id/guide/reviewed`).
- Escape or "Thread" goes back.
- Build notes: the window's strict typecheck reads the reader's shape from `packages/inbox/guide/reader-module.d.ts`, and the reader itself is checked by `packages/inbox/tsconfig.guide.json` (review-editor carries pre-existing type errors). `apps/inbox/index.css` scans `packages/guide-viewer` and `packages/review-editor/components` for Tailwind and imports `packages/review-editor/comments.css` (the review app's comment cards, toolbar and suggestion styles, also imported by review-editor's `index.css`). The `commentOnly` prop and that stylesheet change the guides.show viewer's bytes, so its pinned manifest was regenerated.

**Search** (design record "inbox-search", not in this repo; owner approval 2026-10-13, "Approve it as mocked, with your recommendations"). The person searches everything the Inbox holds; agents get a read-only search over messages (the `search` MCP tool, below; approval "inbox-agent-search", 2026-10-19, which superseded the earlier "agents get no search tool"). Server: `packages/shared/inbox/search.ts` (the index, pure over the store), `packages/server/inbox-search.ts` (the routes), the text rules both sides share in `@plannotator/core/inbox-search`.
- What is indexed, one document each: a thread (its current subject, following a replaced question's subject, and its thread name as title fields; its project's name); an agent message (its body as text: question blocks, images and link targets dropped, code kept; each question's prompt, context, choice labels and the person's answer; the agent's name); the person's own reply words (`inboxSearchReplyText`: not the "Answered N questions." line, not the answers section); an attachment's name and the last two path segments; a guided review's title; a project's name and root. Not indexed: attachment contents, guide section text, annotation text, image alt text, the Inbox's own set-aside and reopened notes.
- Text rules (`@plannotator/core/inbox-search`, browser-safe, so the window highlights with the same ones): NFKC, default-ignorable code points dropped, case folded, Latin/Greek/Cyrillic accents dropped (U+0300 to U+036F; Japanese voicing marks stay), for matching only. Tokens: maximal letter and digit runs (an ASCII chunk by a char-code scan; any other chunk as word runs of letters, digits and marks, through `Intl.Segmenter` only when it holds a script written without spaces: Han, Hiragana, Katakana, Hangul, Thai, Lao, Khmer, Myanmar). A token under 2 characters is dropped unless CJK. A query is at most 200 characters and 8 terms; every term must match, the last as a prefix. Snippets cut about 40 characters before the first match at a word start, on grapheme boundaries, with an unbroken run over 48 characters (a URL) shortened unless it holds a match; CJK, Arabic and Hebrew runs are never shortened; a long source is windowed first. Marks are `[start, length]` in UTF-16.
- Ranking inside a group: the match tier (the terms as a phrase, then every term as a whole word, then the last as a prefix; inside a tier, every term in the title fields first), then open before archived, then the project open in the list (`current`, ties only, never a filter), then newest. Groups and first-answer caps: Threads 5, Messages 8, Files 5 (attachments and guided reviews), Projects 3; `group=` with `offset=` and `limit` (at most 50) is "Show all". A thread is listed under Threads only when its own title fields (or project name) match; a message is listed once, with the snippet from the field that holds every term (the body, else a question: then `question: { key, replaced }`, the "Question" chip). Archived means resolved and not come back (`inboxRowArchived`); archived rows say so.
- Filters (`project`, `status`, `from`) apply on the server and the totals follow. `status=waiting` is Stopped, Holding and Waiting; `new`, `sent`, `quiet` are those sections of open threads; `archived` the archived. Any status or From hides Projects. `from=me` keeps the person's replies (Files are agents', so hidden); a thread counts for a side that wrote in it. Filters with no words list the matching threads, newest first (20). An empty query with no filters answers `recent` (the 6 threads with the highest `person_seen_seq`: no new storage) and `recent_searches`.
- The index: an inverted index over numbered documents; each document's token ids as varints (0 separates fields, so a phrase never spans two; one pass finds a phrase with a bit run, no look-ahead). The vocabulary and postings (`packages/shared/inbox/search-vocabulary.ts`) are sized for text full of one-off tokens, since a distinct word costs memory however rarely it occurs: word text in one byte pool (ASCII words; others as strings), an FNV-1a open-addressing table that reads ASCII tokens straight from the text and grows incrementally (the old table stays readable while each new word moves 8 of its slots, so no insert pays for a million words), one Int32 of postings per id (a single document inline, more as delta varints in blocks of one shared arena), the last term's prefix through lists keyed by a word's first two characters, and the arrays trimmed when the build ends. About 40 bytes per distinct word. **Identifier-like tokens are not words** (`isIdLikeToken`): 8+ hex characters with digits and letters (commit hashes, UUID parts), more than 8 digits (timestamps), or 16+ letters and digits with 3+ digits switching between letters and digits 3+ times (ULIDs, base32 and base64 ids). Each is posted once under one of 65,536 shared bucket ids, made as first used: an id with a letter by the hash of its first 7 characters, a number by the hash of its whole value (timestamps share their first digits). Beside the bucket id, the document's token stream keeps the id's tail: a number's remaining 16 hash bits, or an id's first 12 characters (whole when it is no longer, else with 21 bits of its whole hash). A query confirms an id from those bytes, so an id query costs about what a word query does however many ids the store holds: an id of up to 12 characters is compared whole, and the text is read only for a number or a longer id whose kept bits all match, to confirm the exact token (`textHasToken`; rare unless the id is there, since a different id must share 32 hash bits, or 12 characters and 21 hash bits). An id with a letter is also found by any start of 7 characters or more (git's short SHA: `9fceb02` and `9fceb02d0ae5` find `9fceb02d0ae598e9…`), compared with the 12 characters kept; a start longer than 12 that is not the whole id is confirmed by reading the text of only the documents whose ids start with those 12 (`textHasPrefix`). Numbers are found by their whole value only, and nothing shorter than 7 characters finds an id. A row is drawn from at most about 8 KB of a long message: the lines around the first token a term matches, case-insensitive (the last term as a token's start, so `re` centres on `retry`, not `there`; `nearFirstHit`, for bodies over 64 KB; the whole body when a term is not plain ASCII). Built lazily on the first search (start stays as fast as before), in slices of 5 ms that yield (`setImmediate`) between messages, so health, the list, the event stream and the bridge keep answering. `store.subscribe` marks what a line touches (a message, its thread's document and facts, a project); a 50 ms timer, and every search, re-index it. A deletion re-reads the store (`store.reloadCount()` changes), and the next search rebuilds; a build that a deletion interrupts is void. Thread facts (section, archived, last time, who wrote) come from `store.listRow`, cached until a line touches the thread.
- `GET /api/inbox/search` while the index is still building waits up to 250 ms, then answers `indexing: true` with the thread count and no groups; the window asks again. `POST /api/inbox/search/recent` writes the last 6 recent searches to `inbox/recent-searches.json` (0600), only when the window opens a result (`{ q }`) or clears them (`{ clear: true }`).
- Access: the loopback window and the owner over the tailnet listener, like every read route (the listener's identity, Host and `Sec-Fetch-Site` checks first). Both routes refuse another site first (`403 cross_origin`, before anything is searched): `Sec-Fetch-Site: cross-site` or `same-site` (a page on another localhost port is the same site), and an Origin that does not name this server (`isSameOriginOrNoOrigin`), because a page that cannot read the answer could still pick the query and time it (a hit takes longer than a miss); the window's own page and a client without browser headers are answered. The recent-searches POST also takes the `serverSession` guard. The phone's door carries `GET search` (contract 7.42; it sends no Origin and forwards no fetch metadata), never the recent searches.
- Measured with `bun scripts/inbox-search-bench.ts` (4,000 threads, 30,000 messages, about 65 M characters, 40 projects, written straight into a scratch store, the client in the same process; Apple M-series laptop): first build about 1.1 to 1.4 s (target 1.5 s; 1.5 to 1.9 s with 1% to 15% of words one-off, on a machine at a load average of about 7), longest slice under 8 ms (at most one of about 250 past it), query server time p95 about 21 to 25 ms over a mix that includes queries of only common words (target 25 ms; `the an` alone is about 28 to 30 ms, because every document holding both words is read for the phrase; most queries take under 10 ms). Index memory (JSC live heap plus typed-array memory after full collections, the store loaded first) against the text it covers: 1.0x with no one-off tokens, 1.2x / 1.4x / 2.1x with 1% / 3% / 15% of words replaced by identifiers, paths and timestamps seen once (`--unique N`), 1.1x / 1.3x / 2.4x with random one-off words instead (`--unique N --unique-words`, 1.5 million distinct words at 15%, the case no identifier rule can tell from words). The memory grows with distinct words and ids, not text, so these mixes are the numbers to watch. Id-dense logs (40 MB of lines each holding a timestamp and a 12-character hash, as 200 messages of 0.2 MB or 20 of 2 MB): an id query, a short SHA, a number or an id in no document takes 1 to 5 ms (0.2 MB messages) or 7 to 14 ms (2 MB messages); one 2 MB message is tokenized in one slice of about 25 ms, since slices end between messages. `--keep DIR` keeps the seeded store, for a look in the window.
- The window (`packages/inbox/search/`): a field-shaped **Search** entry at the top of the sidebar, under the Tater mark and above Inbox (`.ib-sp-entry`, 32 px, `aria-haspopup="dialog"`, the ⌘K / Ctrl K hint at its end), and on a phone a search icon in the list header (`.ib-lhead-search`, shown only under `PHONE_QUERY`; decision D3; the desktop header has none, D2). **⌘K on macOS, Ctrl+K elsewhere, opens search**: the Inbox's one new keyboard shortcut, an owner exception (approval amendment 2026-10-14) to the rule of no Inbox shortcuts until the centralized shortcut system exists, where ⌘K is its first binding. `search/searchShortcut.ts` defines it as a registry scope (`inboxSearchShortcuts`, `Mod+K`) and holds the window's one capture-phase keydown handler (`onOpenSearchKey`, installed by `App.tsx`): only the platform's own modifier counts (`isModKeyHeld`; on macOS Ctrl+K stays the text fields' delete-to-end-of-line), never with Shift or Alt or while an IME composes; it works from the reply box or any field (a chord eats no typing) and prevents the browser's own Ctrl+K; with the palette open it goes back to its input, the words selected; another modal dialog (`dialog[open]`, `aria-modal`) keeps the keys; keys inside an attached HTML page's frame never reach the window. The Search entry shows the keycaps from the registry's formatter (`⌘K` / `Ctrl K`, `aria-hidden`, hidden on a phone) and names the chord in `aria-keyshortcuts`. No other key opens search. The palette (`search/SearchPalette.tsx`) is lazy: `components/SearchHost.tsx` is its one `lazy(() => import('#search-palette'))`, mounted on the first open with no fallback and kept mounted after (`tests/entry-assets.test.ts` keeps every other import out). It is a native modal `<dialog role="dialog">` pinned at `top: max(16px, 12vh)`, `min(680px, 100vw - 32px)` wide, a full-screen sheet with **Cancel** on a phone (`data-phone`). The input is a `role="combobox"` (`aria-expanded`, `aria-autocomplete="list"`, `aria-controls`, `aria-activedescendant`) over one `role="listbox"` ("Search results") of `role="group"`s labelled by their headings; focus stays in the input (a mouse press on a row, a heading or Show all is `preventDefault`ed, and Show all puts focus back in the input, so the arrows go on). Results announce through one live region only (the No matches and error blocks in the list carry no `role="status"`), and an option carries no `title` repeating its own text. Keys are the open palette's own, and its `keydown` never reaches the window's shortcuts (it stops propagation): ↓ ↑ move a highlight that wraps, Enter opens (never while an IME composes; an Enter while a newer query settles opens that query's first row once it lands), ⌘Enter / Ctrl+Enter (or a modified click) opens the hash in a new tab and keeps the palette open, Escape closes a chip's menu, then the palette, Tab walks the input and the chips. The highlight snaps to the first row when an answer lands, never while arrowing; `pointermove` moves it. Typing debounces 120 ms, one request in flight (`AbortController`), stale answers dropped, the last results dimmed (`data-dim`) until the next land; an `indexing` answer shows skeletons and "Indexing N threads…" and is asked again after 350 ms; a failed request shows "Search isn't answering." with **Try again**, the text kept. A visually hidden `role="status"` says "N results in M groups" (or "No matches for …") once per settled answer. Filter chips **Project** (starting on the project open in the list, removable), **Status**, **From** open `role="menu"` lists of `menuitemradio`; a set chip is primary-tinted with a ×, and **Clear filters** appears. "Show all N messages" asks for that group (`group`, `limit=50`) and expands it in place, then "Show 50 more". Rows (`search/model.ts` for groups, labels and hashes): two lines, the matched words semibold, the primary line `dir="auto"` with its full text in a tooltip while cut, the secondary line's user-written parts in `<bdi>` that truncate by themselves (46%), chips Stopped / Archived / Question / Replaced / the file kind; file names cut in the middle keeping the extension and date (`middleCutInboxName`). Every result that belongs to a thread draws the list's thread chip (`.ib-key` / `.ib-keyt`, owner request 2026-10-16: "the chip form, what I'm used to everywhere else in the app"; `MetaLine` / `ThreadChip` in `SearchPalette.tsx`, `rowThreadChip` in `search/model.ts`), first on its second line, where a phone's list row draws it: `[chip] what it is · project · section · time`. A thread row follows the list's rule (`threadChipName`, `packages/inbox/threadChip.ts`, shared with the list: its name, none when the subject starts with the name or there is no name). A message, file or guided review always shows one chip: the thread's name, or with no name the thread's subject in the chip (the row's face; names keep the list's monospace face, except right-to-left ones, `:dir(rtl)`, which the mono face would draw unjoined); the subject chip is left out only when the first line is the subject, begins with it, or is a start of it at least 12 characters long, never for a word met inside the text. The chip's tooltip and visually hidden words carry the whole thread ("Thread: name: subject"; always for a named chip, a subject chip only while cut), and ", " stands for each drawn "·". One flex line: the project and the chip give way together (chip at least 4.5em, at most `min(55%, 24em)`; project at least 2.5em); the lead, section and time keep their place, so nothing leaves the row. The answer carries it additively: `thread_name` on message, file and guide rows, so the phone door gets it too. Opening a result closes the palette and opens it as a row click does (`openSearchResult` in `App.tsx`): searched from a project's list, the list stays on that project, and the route is a new history entry, so Back returns to where the search started (on a phone `‹ Inbox` is the browser's Back to that list, D7); a result in the thread already open (nothing beside it) replaces the entry instead, since once `msg=` drops a new one would equal the last. A `msg=` with no thread is dropped from the address (`stripStrayMsg`). ↓ ↑ and Escape belong to an IME while it composes (the palette's `cancel` too); dismissing returns focus to what opened it. Opening a result with words posts it to recent searches.
- Landing (`Thread.tsx`'s `landing` prop, `search/highlight.ts`): `#thread=…&msg=…` opens the thread, unfolds the message (or its middle fold), scrolls it to the centre, focuses and rings it (`.ib-q-target`; on a phone, where a message has no padding of its own, the ringed message takes 8 px of inline padding inside an equal negative margin, so the ring clears the text and nothing moves; a question's card when the match was in a question, kept in memory by the window), and paints the query's words in that message with the CSS Custom Highlight API (`::highlight(ib-search-hit)`, no DOM change, the header skipped); the first click or key in the thread clears it. Then `msg=` is dropped with `replaceState`, so a reload does not jump again. A reload of a `msg=` link (no query in memory) lands without words.
- Window tests: `packages/inbox/searchPalette.test.tsx` (DOM: semantics, keys, debounce and stale answers, Show all, chips and menus, indexing, errors, recent searches, the highlight's ranges), `packages/inbox/searchShortcut.test.tsx` (DOM: the chord on each platform, from a text field, with the palette open, under another modal dialog, the one-shortcut scope, the entry's keycaps) and `tests/e2e/inbox-search.spec.ts` (Playwright on the compiled binary, seeded by `tests/e2e/inbox-search-world.ts`: the entry, ⌘K and Ctrl+K on each platform (from the reply box, again while open), no other key, grouped results, landing with the highlight, recent searches, filters, long and right-to-left text without overflow, a new tab, a result keeping the project's list, the same thread replacing its entry, a stray `msg=`, the phone sheet and Back, a phone's `‹ Inbox` as the browser's Back to a project list, the phone's landing ring; PNGs in `.local/proof/search/`).
- Tests: `packages/shared/inbox/search-text.test.ts` (the text rules, with fast-check), `packages/shared/inbox/search-vocabulary.test.ts` (identifier rules, which terms may start an id, buckets, lookups during a table growth, prefixes, postings against a model), `packages/shared/inbox/search.test.ts` (groups, ranking, filters, scripts, identifiers by whole value and by a start of 7+ characters, ids whose buckets collide (no false match, no title or phrase credit from the other id), a guard that id queries read text only where an id's full kept hash matched, numbers and long ids that share every kept bit told apart by the text, a long message's row drawn around its hit, centred on a token, the index following the store, the sliced build), `packages/server/inbox-search.test.ts` (the routes on a running Inbox, the cross-site refusal), the tailnet case in `inbox-tailscale.test.ts` and the door's refusal in `inbox-devices.test.ts`.

**The count on the tab** (`packages/inbox/tabCount.ts`; approval "inbox-tab-count", 2026-10-20, not in this repo). The tab shows how many threads hold agent messages the person has not looked at: the rows of the window's latest list read (`GET /api/inbox/threads?archived=exclude`, every project whatever the sidebar's filter) with `unseen > 0`, an archived thread only when it came back (`back_from_archive`). Never the sidebar's waiting-on-you count: an open question the person already saw does not count. The look (opening the thread, seen on sight) clears it. The title reads "(N) Plannotator Inbox" (the title the page loaded with, no prefix at zero; the accessible signal, nothing said in a live region), and the favicon link gets the page's own icon (`/favicon.png`, so the person's favicon style holds) with a badge in the bottom-right corner (white, near-black `#18181B` digits and a 4 px dark ring, one pixel at 16 px: the owner's pick over red, which sat too close to Tater's orange), the number up to nine and "9+" above: drawn once per count on a 64 px canvas as a PNG data URL, an SVG data URL where there is no 2D canvas (happy-dom) or the canvas draw throws (`roundRect` is missing before Safari 16 and Firefox 112), and `/favicon.png` again at zero. It follows the list reads the window already does (the event stream, every look); no new polling, no server change. Tests: `packages/inbox/tabCount.test.ts`, the DOM test `packages/inbox/tabCountWindow.test.tsx`.

**Notifications** (`packages/inbox/notify.ts`; the open page first, no Web Push, no service worker; approval "inbox-notify-every-thread", 2026-10-15, not in this repo).
- What notifies: every new thread an agent starts, the tab in front or not (`isNewAgentThread`: the root's FIRST line, which the event stream marks with the additive `first: true` on message records (`store.messageCursor(id) === line.seq`); a later line of a root (a look, an archive, an Unarchive, even of a thread archived before the page loaded) is never "new", nor is a thread a list read already showed this page); and each new question the event stream brings in, also in front, unless it is in the thread open and visible (ThreadPane's `onScreenChange`: the pane mounted and nothing over it, `covered` or a file over the thread, and the tab in front; `notifiableItems`). Plain news in an existing thread never notifies. Every notification carries one tag (`plannotator-inbox`) and `renotify: true` (`inboxNotificationOptions`), so a new one replaces the last and still alerts; without `renotify` Chrome replaces a notice still holding the tag silently.
- One thread: "<project>: <agent> stopped on you", "is waiting on you", or "started a thread" for a new thread that asks nothing, with the subject as the body. A click opens the thread.
- A burst becomes one notice, "3 waiting in 2 projects" ("3 new in …" when a thread in it asks nothing). A click opens the list. Away, a burst lasts until the tab is back in front; in front, notices within 30 s (`FRONT_BURST_MS`) are one burst; a change between the two starts a new one (`startsNewBurst`).
- **Nothing fails silently.** Every way a notification can fail to reach the person is detected and shown (`askKind` in `notify.ts`, the words in `notifyStatus.ts`):
  - One origin. The browser's permission is per scheme+host+port, so the Inbox has one address, `http://localhost:<port>/` (`inboxCanonicalBaseUrl`, `packages/server/inbox-canonical.ts`; the address it opens and advertises, the thread links agents get, and the spelling plan review shares its cookies on). A browser's top-level navigation of `/` at another loopback spelling of THIS port (`127.x.y.z`, `[::1]`: `Sec-Fetch-Mode: navigate` + `Sec-Fetch-Dest: document`, GET only) answers `307` to it with the query (the browser keeps the `#thread=` fragment), `no-store`. Never for an API, the device door, MCP, a connection route, a frame, a client without fetch metadata, the tailnet listener (`via: "tailnet"`), another port's spelling or any non-literal name (`inbox.plannotator.localhost`, a `PLANNOTATOR_ALLOWED_HOSTS` name). The fixed-address prototype (#1945) removes port drift entirely; it can make its name the one address when it lands.
  - The line above the list (`components/NotificationAsk.tsx`) stays on every load until it is resolved: `moved` (allowed at another address of this computer, `allowedOrigin`, and none here: the Inbox changed port or was opened at 127.0.0.1) shows at once, prominently, with **Allow**; `ask` (the browser has not been asked) once the Inbox holds a thread, never on an empty first run; `blocked` (the browser blocked this address) a quiet line with **How to allow** (Settings → General) and **Hide**, also only once there is a thread. "Not now" / Hide (`dismissed`), turning notifications off, or a Block in the browser's own prompt ends it; closing the prompt without an answer does not. A grant made in the browser's site settings while the page is open records `allowedOrigin` (once per page), so a later port change reads as `moved`.
  - The permission is read live: the Permissions API's `change` event, plus a fresh read on every `focus` and `visibilitychange`.
  - Settings → General: the status (`On for this address`, `Off`, `Not allowed in <browser> for this address` with **Allow**, `Blocked in <browser> for this address` with the browser's own steps for this address), **Send a test notification** while on (its own tag, `plannotator-inbox-test`, so it never replaces a real notice; "Didn't see it? Check System Settings → Notifications → Google Chrome, and Focus." on macOS, since a browser reports `granted` while macOS or Focus hides it), and "Notifications reach you" (below).
  - Which windows can notify (`packages/server/inbox-windows.ts`): notifications come only from an open Inbox tab. Each window opens its event stream with `window=<id>&permission=…&origin=…` and reports a change with `POST /api/inbox/window`; the server counts windows holding a stream (or served by one: see "One event stream per browser" below) and those whose browser said `granted` (a record outlives its last stream by 15 s, `WINDOW_GRACE_MS`; the URL's `permission=` is what the page had when it first connected, so the page reports again on every `hello`, i.e. every reconnect, past the grace and across an Inbox restart: `reportWindow` via `subscribeInboxEvents`' `onConnect`), in memory only. `notify_reach: { enabled, windows, allowed, allowed_origins }` rides `GET /api/inbox/health`, `GET /api/inbox/settings` and an `event: reach` frame on every window's stream (only streams with a `window=` id; never the phone's door, contract 7.9) when it changes, so "Notifications reach you: yes, through this tab / another Inbox tab (localhost:61000) / no: no open Inbox tab may notify / no Inbox tab is open" is live. Nothing notifies with no tab open; the options for that are a design note for the owner (not built).
  - A tab the browser put to sleep: Chrome's Memory Saver discards a background tab (`document.wasDiscarded` on the reload) and Energy Saver can freeze one (`freeze` / `resume`, 60 s or more: `FROZEN_NOTICE_MS`); the page then says once, under the list, that it could not notify meanwhile, and how to keep `localhost` always active in Chrome. A frozen tab's queued events arrive on `resume` and raise their notices then; an EventSource reconnect resumes from its `Last-Event-ID` (a usable one, a non-negative whole number, now wins over the `cursor` its URL was opened with; an empty or malformed header falls back to that cursor), so a tab whose connection dropped catches up and raises what it missed, once. Background timer throttling does not delay a notice beyond a second: the work after an event is one unchained timer.
  - A tab that may not notify (another origin with no permission, a blocked one) claims nothing (`claimNotices` runs only after `Notification.permission === 'granted'`), so it never swallows an item a tab that may notify would show; claims are per origin (localStorage) anyway.
- State lives in config.json as `inboxNotifications` (`{ enabled, dismissed, allowedOrigin }`), through `GET` and `POST /api/inbox/settings`.
- A notice is raised with `silent: true` only when the bell owns its sound: it is about a question, this tab is away, and the sound is on, armed and no other Inbox tab is in front (`bellCovers`), so Windows and Linux do not chime a second time. Every other notice (a new thread that asks nothing, anything raised in front, the sound off) keeps the system's sound.
- Several Inbox tabs raise each item once: a tab away stays quiet while another Inbox tab is in front (the sound's channel, `otherTabInFront`), and otherwise the first tab to claim the item raises it (`claimNotices`: claims in localStorage `plannotator-inbox-notified`, kept 10 minutes, under one Web Lock). In front, a thread the person opened leaves the burst.

**One event stream per browser** (`packages/inbox/sharedEvents.ts`; owner-approved). Every Inbox tab used to hold its own EventSource, one HTTP/1.1 connection for the tab's life; Chrome allows six per host, so a seventh tab (and everything else on that origin) stalled (proved against the build before this change: the seventh tab never loads until one closes). Now the tabs of one origin share ONE stream:
- **Leader and followers.** `subscribeInboxEvents` (api.ts) is unchanged for its callers. With Web Locks and BroadcastChannel (and a window id), each tab queues for the Web Lock `plannotator-inbox-events`; the tab holding it (the leader) opens the EventSource (with its own `window=`) and posts every frame (`hello`, `record`, `status`, `reach`, `deliveries`, `drafts`, unparsed) on `BroadcastChannel('plannotator-inbox-events')` (messages `{ v: 1, type: 'frame' | 'leader' | 'join' | 'ping' | 'pong' }`, anything else ignored), and handles it itself; followers only listen. Every tab still runs its own handlers (list reads, notifications with their claims, the sound with its lock), so nothing above it changed. Locks and channels are per origin: `localhost:<port>`, a tab left on an old port and the tailnet address never share. Where Web Locks or BroadcastChannel is missing, or there is no window id, the tab opens its own stream exactly as before. The surface (`packages/inbox/surface`) does not use it.
- **No record missed or twice.** Each tab drops a record whose seq it already passed (its subscribe cursor, its list read's, counts as passed). A new leader opens its stream after the highest seq IT has seen. A tab that learns of a new leader (a handover, or its own join) first fetches what it may lack, `GET /api/inbox/events?cursor=<its last seq>&once=1` (the hello and the replay, then the response ends; not counted as a stream), holding the leader's frames until then, so a tab that slept or whose list read was older than the new leader's start loses nothing. A catch-up that fails (the Inbox restarting) keeps holding: the frames that arrive meanwhile wait (past 5,000 the oldest records go, which the catch-up fetches again), and it is tried again on a timer (1 s, doubling to 30 s) and at the next `hello`, from the same seq, so the gap is never skipped. A replay holds each record's latest line only (`changesSince`), exactly as an EventSource reconnect always did. `prepareInboxEvents()` opens the channel before the first list read, so a frame passed on between that read and the subscription is kept.
- **Handover.** Close, reload, navigation and a crash free the leader's lock; the next tab in the lock's queue leads (measured 1 to 8 ms after the old leader went, 217 ms in the simulated freeze). `freeze` and a `pagehide` into the back/forward cache step down and leave the queue; `resume` / `pageshow` (persisted) join again, as a follower, with a catch-up. A frozen tab is never a candidate.
- **A leader that stops without freezing** (a debugger, a long script in an attached HTML page's frame, which shares the tab's main thread, a phone's browser suspending a background tab) keeps its lock and passes nothing on. So every follower asks: `ping` on the channel every 3 s while the person can see it (`LEADER_PING_EVERY_MS`; at once when it becomes visible or gets focus), every 15 s while hidden (`LEADER_HIDDEN_PING_EVERY_MS`: a notification may still be owed); the leader answers `pong` from its message handler, so the answer proves its main thread runs, and any frame or announcement from a leader counts as an answer. No answer in 2 s (`LEADER_PONG_TIMEOUT_MS`): the follower takes the lock (`navigator.locks.request(..., { steal: true })`) and leads, opening its stream from its own last seq. The old leader learns it when it runs again (its lock request rejects): it closes its stream, steps down, joins, queues again and catches up, as a follower. Until then the server holds two streams (the stopped one and the new); records the two pass on are told apart by seq. A follower takes a leader only from its announcement (or, knowing none, from a frame), so the old leader's last frames never take the tabs back. Measured: Chromium with the leader held by the debugger for 8 s, the tab in front had the stream 3.4 s in, its longest gap without a record 3.2 s, two streams at most, every tab every record once; WebKit with a looping script in an attached page, 3.8 s and 3.7 s. A leader busy for more than 2 s for an ordinary reason is taken over the same way; nothing is lost.
- **Presence (`notify_reach`).** A follower holds no stream, so its `POST /api/inbox/window` reports `served_by` (the leader's window id, `inboxEventsServedBy()`), again whenever its leader changes and on every relayed `hello` (an Inbox restart); the server counts it while that leader holds its own stream, or held one less than the 15 s grace ago (a handover). Only a leader's own stream counts, never one link further: two tabs naming each other are never counted. Each tab holds the Web Lock `plannotator-inbox-window:<its id>` for its life; the leader queues for each follower's (on its `join`), and when the browser grants it the tab is gone (closed or crashed): the leader posts `{ window, gone: true }`. A tab also sends that itself at `pagehide` (a beacon). A gone tab stops counting at once; the followers it served keep counting through the grace. Worst case (the whole browser killed): followers stop counting 15 s after the leader's stream drops (one grace, and the pages hear it then).
- **Health** carries `event_streams` (additive): the event streams open now, windows' and the phone door's.
- **Another site** is refused on `GET /api/inbox/events` (`Sec-Fetch-Site` cross-site or same-site, or an Origin naming another server: `403 cross_origin`), as on the other read routes; the window, the tailnet page (same-origin), the phone's door and agents (no fetch metadata) are answered.
- **With every tab hidden**, a stalled leader is taken over in about 16 s (the next hidden check, up to 15 s, plus the 2 s wait), longer where the browser throttles a hidden tab's timers (Chrome: at most once a minute in a tab hidden for more than 5 minutes; Safari suspends background tabs).
- **A crashed tab** frees its locks when the browser notices the renderer died: at once on macOS (2-3 ms measured), about 3 s on GitHub's Linux runners (CI: the next tab in line led 3.0 s after the leader's crash, and a crashed follower stopped counting 3.3 s after). Should that take longer than a check, the tab in front takes the lock first (the check every 3 s, no answer in 2 s).
- **A catch-up that fails while the tab has come to lead** owes nothing: its own stream replays every line after its last seq, so it clears what it held back and handles its stream (a leader never holds frames for a catch-up retry).
- **Not covered:** Chrome's Energy Saver is believed not to freeze a tab holding a Web Lock other tabs wait for; if it does, `freeze` hands over first. Headless Chrome cannot really freeze a page (`Page.setWebLifecycleState` is a no-op on a visible page), so the freeze proof plays `freeze`, a debugger hold and `resume`.
- **Proofs:** `packages/inbox/sharedEvents.test.ts` (fakes for Web Locks with `steal`, BroadcastChannel and the server's stream, and a paused tab whose main thread runs nothing; closes, crashes, freezes, a stopped leader taken over by a visible and by hidden followers and following when it runs again, a leader that answers never taken over, a failed catch-up keeping its gap, the back/forward cache, a follower behind a new leader, and seeded random lives of up to 12 tabs, with and without stopped leaders), `packages/server/inbox-shared-windows.test.ts` (`served_by`, `gone`, the grace through a handover, two tabs naming each other, the whole browser gone, `event_streams`, the cross-site refusal), `tests/e2e/inbox-shared-events.spec.ts` (Chromium, real tabs in one context, the compiled binary, the server's stream count in every case: 1, 3, 8 and 12 tabs; the old build's seventh-tab stall with `PLANNOTATOR_E2E_BASELINE_BINARY`; the leader closing, reloading, crashing (`Page.crash`), frozen and stalled (debugger-held, no freeze) while an agent writes, with a tab in front; notifications and the sound once; `notify_reach`; an Inbox restart; two origins; no Web Locks; a soak with `PLANNOTATOR_E2E_SOAK_MS`, which also brings tabs to the front and stalls leaders) and `tests/e2e/inbox-shared-events-webkit.spec.ts` (WebKit, with the leader stalled by a looping script in an attached page). Each tab logs what it did into `window.__plannotatorInboxEventLog` when a proof puts an array there first; nothing is logged otherwise.

**The question sound** (`packages/inbox/sound.ts`; design record `.product/approved/inbox-sound/`, not in this repo). A soft two-tone doorbell ("Ding-dong", the owner's pick of twelve), synthesized live with Web Audio (`DING_DONG`, no audio files).
- When it rings: for a new question in an agent's message (never a plain message, nor a new thread that asks nothing), and only while no Inbox tab is in front (`pageInFront`). It does not depend on notifications being on, allowed or blocked. `notify.ts` calls `onQuestions` after the list read, before any notification rule.
- Once per burst (`decideRing`, pure): the first question rings, a question within 30 s (`RING_BURST_MS`) of the last one stays silent and extends the burst, and a tab coming to the front ends it.
- Several tabs ring once: they share `BroadcastChannel('plannotator-inbox-sound')` (who is in front, repeated every 5 s and trusted for 15 s; who rang, which puts the others in that burst), and a tab rings only while it holds the Web Lock `plannotator-inbox-sound` (`ifAvailable`, held 3 s or until a tab comes to the front; a localStorage timestamp without Web Locks). Another port is another origin, so a tab left on an old port can ring once more.
- Chrome plays sound only after a user activation in the tab. The first pointer, click, touch or key event that the browser counts as one (`navigator.userActivation`; Escape or a modifier alone does not count, and the page keeps listening) makes and resumes the AudioContext ("armed"); before it a ring is skipped. Until then, with the sound on, Settings shows "Click once in this tab to allow sound." under the row; the sidebar says nothing (the "Click to turn on sound" row was removed, approval "inbox-notify-every-thread"): the first click arms it silently.
- Settings: one row under the notifications switch, "Play a sound · when an agent asks you", the volume (10 to 100 in steps of 10, disabled while off; letting go plays it once at that level), Play (always plays, even in front) and the switch.
- The one-time dialog (`components/SoundIntro.tsx`, on the `Modal` shell of `components/Updates.tsx`): "The Inbox can ring now" with Play, one sentence, a notification line only when something needs fixing (not allowed: Allow; off: Turn on; blocked: where to fix it), and Turn it off · Keep it on. Keep it on has the first focus; Escape and the backdrop keep it on; Tab stays inside; Turn it off saves off and toasts "Sound off". No entrance motion.
- It shows once per machine, for someone who used an earlier Inbox. The server decides at start from evidence that predates that start (`inboxUsedBefore`, read before the store, the update state and the registry are written): a recorded `inboxVersion`, `inbox/inbox.json`, a project under `inbox/projects/`, or `inboxNotifications` / `inboxTool` in config.json. Builds 0.28.7 to 0.28.11 recorded no version, so the version alone is not enough. With such evidence, on a release version other than the one recorded, it writes `inboxSound.dialogDueFor`, which waits in config.json until a page claims it, so a `--background` start that ends before any window opens does not lose it; settings answer `sound.dialog_due`. With none (a fresh install) it writes `dialogShownFor`, so the dialog never shows, and the notification ask line ends with "Sound is on." The page asks `POST /api/inbox/sound/dialog`, a compare-and-set from `dialogDueFor` to `dialogShownFor`: only the first ask ever gets `show: true` (other tabs and reloads get false). It waits for the list, for a reply being typed and for an update dialog; the notification ask line does not show on that load. A page that came through the tailnet is always answered false and leaves it for a page on this computer.
- State lives in config.json as `inboxSound` (`{ enabled, volume, dialogDueFor, dialogShownFor }`), through `GET` and `POST /api/inbox/settings` (`sound: { enabled?, volume? }`); one volume for every device.

**The Board: cards** (approval `.product/approved/inbox-board/`, 2026-10-20: `approval.md`, the model in `ANALYSIS.md`, the columns and who moves a card in `COLUMNS.md` "Recommended", set d; built in three steps, this is step 1: the records and the call. Step 2 is the Board page and the open card, step 3 the one-time seeding pass.)
- A card is one piece of work that outlasts the reply it was asked in (a lane started, a PR opened, "I'll send you X"). It is its own record, separate from threads: `projects/<key>/cards.jsonl`, `crd_` ULIDs, one full snapshot per line on the store's one seq counter (kind `card`, `InboxCard` in `packages/core/inbox-cards.ts`, re-exported by `inbox-types`), so the event stream carries card lines (`event: record`, `{ kind: "card", card }`) and so does the relay to phones. Nothing that routes threads or builds the list reads them: a card op never changes a section, a row or where a message lands (the routing-determinism property in `store.test.ts` mixes card ops in and checks the person's list is byte-equal across each one; the generic op model and the round trip include cards). An older Inbox skips the kind; `appendCard` writes `seq.json` after each card line so an older Inbox that never reads `cards.jsonl` cannot hand a card's seq out again. Deleting a thread keeps the cards that link it (the wire drops the dead link); deleting a project removes its cards with its folder.
- Fields: `title`, `column` (`asked`, `designing`, `your_look`, `building`, `your_review`, `shipped`, `icebox`, `dropped`), `you` (what the person owes, shown "You: …" in Your look and Your review, cleared when the card leaves them), `said` (the agent's last word), `threads` (roots), `prs` (`{ ref, url }`: `owner/repo#123` or a GitHub, GHE, GitLab or Bitbucket PR URL through `parsePRUrl`), `agent` (the session that made it: host, session, name; null for the person's; named `agent` because "owner" is the person), `created_at` / `created_by`, `moved_at`, `heard_at` / `heard_by` (every write), `dropped` (`{ at, by, reason, seen_at }`: `seen_at` stays null while an agent's drop waits for the person, below; a drop the person made is seen when made), `aside_from` (where restore goes back), `idempotency_key`. Nothing is derived on the wire: a card shows its last-heard age ("2d ago") from `heard_at`, and step 2 draws it (the owner dropped amber, 2026-10-20: no rule decides a card is stalled).
- Who moves a card (the store's rules, `createCard` / `updateCard` in `packages/shared/inbox/store.ts`, shared by the tool, the CLI and the window): an agent moves its work through the live columns, ships it, moves a re-report back to Asked, and drops with a `reason`; only the person puts a card in the Icebox or moves one out (`card_icebox_person_only`, `card_iceboxed`), restores (`card_person_only`), or brings back a card they dropped (`card_dropped_by_person`); an agent may still `say` and link on such a card. An agent that moves a card into Your look or Your review gives `you` (refused otherwise, and `you` is refused in other columns). A linked PR never moves a card: nothing reads PR state in this step.
- The call: the MCP tool `card` (`packages/server/inbox-mcp-cards.ts`, in `INBOX_MCP_TOOLS` and the contract's `INBOX_TOOL_ACTIONS`, so `plannotator_inbox` action `card` on the Claude Code mod, Pi and OpenCode; the mod's contract copy and bundled tool list follow). `op`: create (a `title`, or `thread_id` to link it and take its subject; `column`, `say`, `you`, `pr`, `idempotency_key`), move (`column`), say (`say`, `you`, `title`), link (`thread_id`, `pr`), ship, drop (`reason`), list (the caller's cards in its project, live and icebox; `asked_by: "anyone"`, `include_resolved`). An op refuses a field it does not take (a `false` default such as `include_resolved: false` is tolerated). A card call never makes a project: the caller's scope is looked up only (`findProjects`, as search does), so `list` from a folder the Inbox never had a message from answers no cards and every other op is refused `card_no_project` (send a message first, or pass a known project's `project_path`); a git timeout is `project_unresolved`. The card and any thread must be in that scope, else `card_other_project` naming the project's path. A create's `idempotency_key` is trimmed, one line, at most 128 characters (`INBOX_CARD_KEY_MAX`). A default title taken from a thread's subject drops the bidi and control characters a title refuses; a title the agent writes with them is refused. Results are text-complete (one line per card). The shim fills `card` like `send_message` (project, session, host, name). `plannotator inbox --help` has its section.
- `plannotator card create|move|say|link|ship|drop|list …` (`apps/hook/server/card-command.ts`): a thin client, one `tools/call` to `/mcp`, starting a stopped Inbox detached like the shim; dispatched on the raw argv before the strict-annotate parse (which takes `--json`). Inside a Claude Code or Pi session (`inboxHostSessionFromEnv`) the card is that session's. Exit 0, 1 on a refusal (stderr `<code>: <message>`), 2 on bad usage. In `HIDDEN_SUBCOMMANDS` until the Board ships; not in the skill or the agent guide yet.
- Shipped or held back: `INBOX_CARD_ACTION_ON` in `packages/core/inbox-cards.ts` is the one line. Off, the server does not register the `card` tool (`INBOX_SERVED_TOOLS`), the agent guide drops its section and its "When to use it" line, `INBOX_TOOL_COST` states the size without it (8,189 bytes since action items), and the card tool's own tests skip; then run `bun run scripts/sync-mod-inbox-tools.ts` for the mod's bundled list. The store, the window routes and the event stream stay. **Off** (the owner, 2026-10-20): it is switched on with the Board page in step 2. Off, `plannotator card` exits 1 saying "This Plannotator Inbox does not offer cards yet.", and the tests of the tool and the CLI skip while the store, route and held-back tests run.
- An agent's drop reaches the person: it is unseen (`dropped.seen_at` null, `isInboxCardDropUnseen`) until the person looks at Dropped. `GET /api/inbox/cards` carries `dropped_unseen` (in its project filter) for step 2's "N dropped by an agent", with each card's `dropped.reason`; `POST /api/inbox/cards/dropped/seen` (`{ project? }`, the window's guards) marks them seen (`markCardDropsSeen`: one line per card, `heard_at` unchanged). The agent's `list` line says "the person has not seen it yet" meanwhile.
- Window routes (local window guards; the owner over the tailnet too; not on the phone's door yet): `GET /api/inbox/cards` (`?project=`, `?column=a,b`; `{ cards, dropped_unseen }`), `POST /api/inbox/cards/:id` (`op` move / icebox / drop / restore, the person's) and `POST /api/inbox/cards/dropped/seen`. They are served whatever the switch says. No window UI in this step.
- Tests: `packages/shared/inbox/store-cards.test.ts`, the card ops in `store.test.ts`, `packages/server/inbox-cards.test.ts` (the SDK client against a real Inbox while the action is on; the routes, the unseen drops and the event stream always; the held-back refusal while off), `apps/hook/server/card-command.test.ts` (the CLI as processes, on or held back).

**Agent connections and the knob.**
- A connection gives its host one tool, `plannotator_inbox`, whose `action` is one of the Inbox's MCP tools. It also wakes the session that asked when the person sends.
- The contract lives once in `packages/shared/inbox/connection.ts`. The mod keeps a byte-for-byte copy of its CONTRACT section in `apps/hook/hooks/mod/inbox-contract.ts`, pinned by `inbox-contract.test.ts`.
- The tool is built from the running Inbox's own `tools/list` (`inboxAgentTool`), with the connection's own short words for the long field descriptions (`INBOX_AGENT_FIELD_DESCRIPTIONS`: `body` (a compact question block, `Stopped:` / `Holds up:`), `thread`, `supersedes`, `attachments`, `guide`, `snapshot`), a short line for `read_thread`, `search` and `get_guide_brief` (`INBOX_AGENT_ACTION_LEADS`, so the description stays under Claude Code's 2,048 characters) and a last line pointing at `plannotator inbox --help` (`INBOX_TOOL_HELP_NOTE`), which keeps the full question guide and every field. Pi and OpenCode 2 send the tool whole with every request: measured on the real hosts (the cost tests in `apps/pi-extension/inbox.test.ts` and `apps/opencode-plugin/inbox-v2.test.ts`, which read the request the host sends the scripted model and fail when the entry drifts more than 5% from `INBOX_TOOL_COST` in `packages/core/inbox-types.ts`), it is 7,328 bytes (1,732 tokens with o200k_base), measured on Pi after the read_thread window's fields and the `search` action were added (about 6,390 before them, estimated from the generated entry once Decisions were removed; 7,058 measured with Decisions), down from 11,736 bytes (2,796 tokens with o200k_base) when `body` carried the whole question guide. Action items (approval "inbox-next-actions") then added a paragraph to `body` and the `done` field: +861 bytes and +221 o200k tokens on the generated entry in Pi's request shape (7,362 → 8,223), so `INBOX_TOOL_COST` states 8,189 bytes (estimated, not re-measured on Pi). The window says "about 8 KB, roughly 2,300 tokens" (`inboxToolCostText(host)`: the bytes measured, the tokens a rounded high estimate since they depend on the model) on the first-run screen, under the tool's switch in Settings → Agents, and in `plannotator inbox --help`. The field descriptions are keyed by action (`INBOX_AGENT_FIELD_DESCRIPTIONS.send_message.body`, …); `body` keeps the rule that the person can always answer Other, add a note or skip. The Claude Code mod uses the same short text: the tool is deferred there, but once tool search loads it the schema rides every later request too, and one contract keeps the copies equal. The description is 1,736 characters, under Claude Code's 2,048. The Board's `card` action, held back until step 2 (`INBOX_CARD_ACTION_ON`), makes it 8,503 bytes (2,047 tokens with o200k_base, computed from the generated entry in Pi's request shape; the same computation gives 7,325 for the entry Pi measured at 7,328), 9,364 bytes with action items (estimated), and the description 1,855 characters; `INBOX_TOOL_COST` follows the switch. The MCP server's own descriptions (for raw MCP clients) are unchanged. The connection fills `project_path`, `agent_session`, `agent_host` and `agent_name` and keeps them out of the schema, except an OPTIONAL `project_path` (`INBOX_AGENT_PROJECT_PATH`: "The repository or folder this is about; defaults to your working folder."), for a session whose working folder is not the project (a notes subfolder). `inboxToolCall` shape-checks it (a string, no control characters, at most 4096 characters) and returns it as `projectPath`; the connection resolves it against the working folder (absolute as given) to an existing folder's real path (Pi/OpenCode: `inboxProjectDir` in `agent-link.ts`; the mod: `INBOX_PROJECT_DIR_SCRIPT`, `cd` + `pwd -P`) and refuses anything else before the Inbox is reached or started. The Inbox then resolves it to the git toplevel or folder as for any `project_path`, and relative `attachments` resolve against it. No new exposure: any MCP client could already pass any `project_path`. The schema is part of the tool list, so it changes from the next session.
- The wake text (`inboxWakeText`) is `Plannotator Inbox: <subject> (<reply id>)`, the fixed instruction line for its kind (`INBOX_WAKE_INSTRUCTION` for a reply, `INBOX_MESSAGE_INSTRUCTION` for a New message, `INBOX_NEW_THREAD_INSTRUCTION` for a thread the person started; for a reply the person sent to another session because the asker ended, one more line under it, `inboxRedirectedLine`; on a command carrying `name_thread`, `INBOX_NAME_THREAD_LINE`; to a session the person tagged, `INBOX_TAGGED_INSTRUCTION` and `inboxTaggedLine` instead, and to the owner of a reply that tags others, `inboxAlsoTaggedLine`), a blank line, then the reply verbatim.
- Naming a thread the person started (approval "inbox-agent-names-own-thread", 2026-10-16, amended: the name is the chip, `thread_name`; the bold subject stays the short name). While a thread the person started has no name, or only compose's suggestion (`named_by` absent or `kind: "auto"`), the sessions that may name it are `InboxStore.threadNamers`: the session it is addressed to and, once the address moved ("Send to another session"; `readdressed`, derived from the log), also the first agent that replied in it. The FIRST name such a session gives names it, once: its reply's `thread` (only `thread`; a reply's `subject` never names it), checked by `checkInboxThreadName`; a reply with no name, an invalid one, or one that is taken leaves the thread nameable (so "once" means the first accepted name, not the first reply), later names are ignored, and a name the person set in compose is never replaced. A name another OPEN thread of the project already has (compared by `inboxThreadNameKey`; a resolved thread does not hold its name) is refused, `thread_name_taken`: setting it would pull that thread's later sends, perhaps another session's work, into a thread addressed to someone else. The compose field is refused the same way (`409 thread_name_taken`). The outcome is decided before the reply is written and kept on it (`thread_naming`, `InboxThreadNaming` in `@plannotator/core/inbox-types`: `named` / `refused` with `code` `invalid_thread_name` or `thread_name_taken` and one sentence / `unnamed`), with the `thread` it carried (`reply_thread`), so a retry with the same idempotency key answers the same naming, and the same key with another `thread` is `idempotency_key_reused`. Then the root is written again with `thread_name` and `named_by` (append-only; `apply` indexes the name at that line, in seq order, so a replay routes the same; the routing oracle in `store.test.ts` covers it and checks that no name is ever set while another open thread has it). A crash between the reply line and the root line leaves the reply saying `named` over an unnamed thread, which a later reply can still name; accepted. How agents learn it: the wake (`name_thread: true` on the bridge command whenever the command's session may still name the thread, so a later reply's wake asks again; `INBOX_NAME_THREAD_LINE`, "Name this thread in your reply: pass `thread` with a few words saying what it is about. The first name you give sets it, once."; an older connection ignores the flag); `wait_for_reply` and `read_thread` (`name_this_thread: true` and `INBOX_NAME_THIS_THREAD_HINT` while the caller may name it); send_message's and submit_guide's result (`namingLine`: "Named this thread: <name>.", or one line that the thread still needs a name from it, or why the name was refused, for a taken one "Pick another name and reply again with it in `thread`."; structured `named_thread`, the name or null, `naming_refused` with the code, and `name_this_thread: true` while it stays unnamed); send_message's `thread` field description and `plannotator inbox --help`. submit_guide no longer gives a reply its default "Guided review: …" subject. Proved by `packages/shared/inbox/store-thread-naming.test.ts`, `packages/server/inbox-thread-naming.test.ts`, the harnesses (the mod's `inbox.test.ts` compose test, Pi's `inbox.test.ts` compose test, OpenCode 2's `inbox-v2.test.ts` 04: the scripted model passes `thread` when the wake asks and the chip round-trips), and a small real-model eval (Sonnet role-play in the earlier eval's format, 8 runs over the wake and MCP-only `wait_for_reply` and a later reply after the result's hint: 8/8 named the thread). It never carries the thread and never touches the system prompt.
- A connection whose wake runs sets `_meta["ai.plannotator/inbox-wakes"]: true` on its `tools/call` (`INBOX_WAKES_META_KEY`, `inboxToolCallParams`): the Claude Code mod always, Pi and OpenCode 2 while the session's wake exists, OpenCode 1 never. send_message and submit_guide then end their result with `INBOX_REPLY_ARRIVES_TEXT` (end the turn; the reply arrives by itself) instead of "Call wait_for_reply…", which the stdio shim, raw MCP clients and older connections keep (`callerWakes` in `inbox-mcp.ts`). An older Inbox ignores the key.
- The bridge is two connection routes:
  - `POST /api/inbox/bridge/poll` holds up to 25 s for the person's replies to that session.
  - `POST /api/inbox/bridge/event` `{ type: "delivered" }` writes `delivery` on the reply, which the thread shows as "Delivered to <agent>".
- Pending replies are derived from the store (`InboxStore.pendingReplies`), so a reply is handed out on every poll until it is delivered, survives a restart, and never wakes a session that already read it through the MCP.
- Each host checks the knob and the registry once: the Claude Code mod at the process's first `session.start` (so a change applies when Claude Code restarts; it registers the tool from a bundled list even with no `inbox/inbox.json`, see the mod section), Pi when the extension instance loads (each session and `/reload`) and OpenCode at plugin setup (each OpenCode start), where the tool exists only when `inbox/inbox.json` existed then and the knob allowed it. The tool list never changes during a session.
- The session-start reminder (`INBOX_REMINDER_TEXT`, config-only `inboxReminder`, on by default wherever the tool is, once the Inbox has run here): one fixed line, decided with the tool, in each host's cache-safe place: the mod's `prompt.context` block (the tool's full name), Pi's hidden `before_agent_start` message (`plannotator-inbox-reminder`, once per session, ignored by the Ask-this-session bridge), OpenCode 2's composed system part on requests that offer the tool (primary agents; no-wake wording without `session.prompt`), the end of OpenCode 1's last system part for agents with the tool (no-wake wording). Details in the `inboxReminder` entry under Config-only settings.
- The knob: `PLANNOTATOR_INBOX_TOOL` (`1`, `true`, `on` / `0`, `false`, `off`, `disabled`), then config `inboxTool` (one boolean, or `{ "claude-code", "pi", "opencode" }`, written by Settings), then `INBOX_TOOL_DEFAULTS` (on for Claude Code, off on Pi and OpenCode, which send every tool's full definition with each request) (`packages/shared/config.ts`, `resolveInboxTool`).
- **Claude Code** (the mod, `apps/hook/hooks/mod/inbox.ts`; details in "The Plannotator Inbox" in the mod section):
  - `InboxLink` long-polls on a 1 s tick and submits the wake once the session has been idle for two ticks; a Send now reply (`now`) goes in at once, into a running turn as a user row (`$.session.append`).
  - It claims each reply once (mkdir) and holds a per-session lease, `watcher.json`: the person's last process wins, and the lease goes stale after 20 s.
  - It needs the mod (Claude Code 2.1.287+, not `claude -p`, not Windows).
- **Pi and OpenCode** (`packages/shared/inbox/agent-link.ts`, vendored into Pi as `generated/inbox/`):
  - `InboxAgentConnection` starts a stopped Inbox with `plannotator inbox --background`, through `PLANNOTATOR_BIN`, `plannotator` on PATH, or `~/.local/bin/plannotator`. With no binary, the first result says to install Plannotator.
  - `InboxWake` long-polls, delivers after two idle ticks, checks the reply once more, and claims it with a mkdir of `inbox/claims/<reply id>`. It never interrupts a turn. A Send now reply (`now`) goes in at once: through the target's optional `steer` while the session is busy (its presence is what makes the poll say `send_now`), else `deliver`.
  - Two processes on one session (`pi -c` or `--session` twice; two `opencode2` servers on one database): only the holder of the session's lease, `inbox/leases/<host>-<session>.json` (`{ owner, at, touchedAt }`, `inboxLeaseFileOf` in `agent-link.ts`), polls and delivers. It is the Claude Code mod's rule ported: the process the person used last holds it, renewed every 5 s (`INBOX_LEASE_EVERY_MS`), taken over about 20 s after the holder dies (`INBOX_LEASE_STALE_MS`; released at once on a clean exit), and re-read right before the claim. The claim still keeps a delivery once whatever the lease says.
  - What moves the lease: on Pi, the person typing (an `input` whose source is not `extension`) and a `plannotator_inbox` call, plus a session start. On OpenCode 2 (checked on 2.0.19) typing does NOT move it, only a `plannotator_inbox` tool call does, because the plugin gets no typing events: its event subscription yielded none there. The code would also touch on a user `session.inbox.enqueued` item or a `session.execution.started`, should an OpenCode deliver them. So on OpenCode 2 a process the person only typed into, whose agent never called the tool, has no wake, and the other process still delivers.
  - Pi (`apps/pi-extension/inbox.ts`): the tool is inactive in print and JSON mode. Delivery is `pi.sendUserMessage(text, { deliverAs: "followUp" })` (Send now while a run goes: `deliverAs: "steer"`), confirmed by its `message_start`, and the thread reads "Delivered to Pi".
  - OpenCode 2 (`apps/opencode-plugin/inbox.ts`): the wake is per root session, made on its first tool call or run in the process. Delivery is `session.prompt({ delivery: "queue" })`, never steer except Send now while the session runs (`delivery: "steer"`), and the thread reads "Delivered to OpenCode".
  - OpenCode 1: the tool only, with no wake.
  - Neither package ships `inbox.html`.

**MCP for other agents** (`packages/server/inbox-mcp.ts`, `@modelcontextprotocol/server` 2.2.0, stateless).
- Tools: `send_message`, `read_thread`, `search`, `resolve_message`, `wait_for_reply`, `get_guide_brief`, `submit_guide`; `card` once the Board ships (held back by `INBOX_CARD_ACTION_ON`, see "The Board: cards"). (`list_decisions` and `record_decision` were removed with Decisions, 2026-10; a connection's `plannotator_inbox` never offers them, even against an older Inbox that still lists them.)
- Transports: stdio through `plannotator inbox mcp` (the harness picker's commands use it), or Streamable HTTP at `http://127.0.0.1:<port>/mcp`. The window says to prefer the command, because the port can change.
- Character limits: server instructions stay under Claude Code's 2,048 characters. The question guide rides `send_message`'s description, and `inbox.test.ts` pins that Claude Code's 2,048-character description cut keeps the guide's working part.
- Answers: success is `structuredContent` plus one line. A refusal is `isError` with `<snake_code>: <message>`.
- `wait_for_reply` returns a reply as soon as it lands, or `{ status: "waiting", cursor }` after 50 s.
- Result size, step 1 (the findings are not in this repo). The connections (the mod, Pi, OpenCode) hand the model the result's text plus `structuredContent` as COMPACT JSON (`inboxToolResultText`, no indentation; indented, a long thread read was about 1.5 times the bytes). `wait_for_reply`'s `questions` are the replied-to message's questions as `{ key, state, answer, sent_reply_id? }` (`replyQuestions`), not the window's full records: the prompts and choices are the agent's own block and the body words every answer; `status` and `reply.body` are unchanged (the phone proofs read them through `scripts/inbox-sim.ts`). `read_thread`'s list mode returns one short row per thread (`agentThreadRow`: `thread_id`, `subject`, `thread_name`, `section`, `message_count`, `questions: { open, picked, prompt }`, `last_author`, `last_at`, `last_person_at`, `last_person_message_id`, `unread`, and `resolved_at` on a resolved thread, listed with `include_resolved` or because an agent wrote after the archive), not the window's list row. `last_person_*` and `unread` read past the Inbox's own notes (`isInboxNote`: the set-aside, reopened and 👍 notes). `unread` is the caller's: a person message after the thread's agent-read mark (any agent's read_thread or wait_for_reply), or one addressed to that session (`to`) not yet delivered; the addressed session's own read_thread does not deliver it (only its wake or its own wait_for_reply does), so such a row stays unread until then. (A thread read was then still the whole thread; step 2 below made it a window.) send_message and submit_guide refuse a `thread` shaped like a message id (`msg_` + 26 ULID characters, any case; `refuseIdShapedThread`, checked in `sendProject` before a project is resolved) with `validation_error: thread: "<id>" is a message id, and thread takes a name. To write in an existing thread, pass reply_to <id> instead.`; beside `reply_to` it is refused too (there `thread` may name a person-started thread, and an id is never a name), worded "You passed reply_to, which already places this message: leave thread out". Before, it started a new thread named after the id. Old hosts on a new Inbox get the smaller payloads indented; new hosts on an old Inbox get its full payloads compact. Measured on a seeded 59-message thread (`tests/helpers/inbox-long-thread.ts`, as the hosts render it, before → after): read_thread 154,348 → 99,115 bytes; the list of 17 threads 18,932 → 5,425; wait_for_reply 3,594 → 1,446. Pinned by `packages/server/inbox-mcp-size.test.ts`.
- Result size, step 2: windowed thread reads, text transcripts and agent search (owner's choices: newest 6 in full, the same window on every read, `after` as an option). **Windowed read_thread** (`packages/server/inbox-mcp-read.ts`, `windowedThread`): the header (subject, name, project, participants with message counts, and `open_questions`: every open or picked question of the thread with `message_id`, `key`, `q` (its number as the reply's answers section numbers it), `state`, `prompt`, `choices`, a picked one's `answer`); then the newest `limit` messages in full (`INBOX_THREAD_WINDOW`, 6); the person's earlier messages in full, newest first, while their bodies total `INBOX_EARLIER_PERSON_BYTES` (12 KB: the person's words in the longest thread measured, 17 replies in 46 messages, and what agents re-read most; older ones become one line), each without its "Answers to your questions" section (`withoutAnswersSection`: the answers are on their questions; a reply in the window or expanded is as sent); every other message in range as one line in `thread.earlier` (`id`, `author`, `created_at`, `reply_to`, `words` (the first 120 characters, the person's own words for a reply, a question-only message's first prompt), `bytes`, `questions` as `{ key, q, state, prompt (clipped to 120), answer?, superseded_by? }`, attachment names, guide title, `ack`, `to`). A body over `INBOX_BODY_CUT_BYTES` (16 KB) is cut with a marker naming the `expand` call (`body_bytes` gives the size); the person's newest message (not an Inbox note) is always whole. The 12 KB budget skips a reply that does not fit and goes on with older ones. `withoutAnswersSection` cuts only the section, by the grammar `formatQuestionAnswersSection` writes (heading, the "N of M answered" line, `###` blocks of answer lines), so feedback and a skills block after it stay byte for byte; text that does not parse is not cut. Answers in the text are quoted whole as JSON strings (up to 4,000 characters, line breaks kept). A person's message with `to` carries `to: { host, session, you }` and reads `to you` / `to another session (…)`. A read builds the window first and only then marks read: up to `before` (`readThrough`), and seen only the acks of messages it showed, so a refused or `before` read never swallows an undelivered reply. `message_id` with `thread_id` must be in that thread. `expand: [ids]` and `message_id` show messages whole (as sent); `before` / `after` take a message id or a cursor (number, or digits) and bound the range; a message `before` / `after` left out keeps its questions in `thread.questions` (not open or picked ones, which the header has; for a message older than `after`, only those whose state changed since, `questionLineSeq` or the archive line), so no question's state is ever lost and a read of what is new stays the same size however long the thread (a property test over random windows, `inbox-mcp-window.test.ts`). `format: "full"` returns the old `{ thread: agentThread }` records, unmarked. Messages in full keep the record field names (`id`, `author.kind` (+ `name` for agents), `created_at`, `reply_to`, `body`, `questions[].key/kind/prompt/state/answer`, `attachments[].name/kind/size/path`, `ack { label, at }`, `guide.title`) and drop the bookkeeping (sha256s, mtimes, revisions, idempotency keys, per-message project and thread ids, pickers, inline-image records, `delivery`, `to`, `wakes`); answers drop their copies of key, kind and prompt. The result adds `window` (`limit`, `full`, `lines`, `left_out`, the bounds) and `cursor` (the store's). expand / before / after without a thread id are refused. **Text-complete results**: read_thread (both modes), search and every wait_for_reply answer carry `_meta["ai.plannotator/text-complete"]: true` (`INBOX_TEXT_COMPLETE_META_KEY` in the connection contract) and a text that holds everything their JSON does: the windowed transcript (`windowedThreadText`: a summary line kept from before, the header, the messages oldest first, full or one line, the date printed only when it changes and `reply to` only when it is not the message above, `Cursor N` last), one line per list row (`threadRowText`), one line per search result, and for wait_for_reply a closing `[reply <id> · to <id> · <time> · questions of <id>: Q1 q-… sent: "…" · cursor N · <url>]`. `inboxToolResultText` (contract, so the mod's copy too; Pi vendors it) then hands the model the text alone; send_message, submit_guide, resolve_message and `format: "full"` stay unmarked and keep the appended JSON. An older connection ignores the mark and appends the (now trimmed) JSON after the text; an older Inbox sends no mark, so a new connection appends its JSON as before. **Agent search** (`packages/server/inbox-mcp-search.ts`, MCP tool `search`, in `INBOX_MCP_TOOLS` and the contract's `INBOX_TOOL_ACTIONS`): `query`, `project_path` (filled; the caller's project plus an older worktree project, `threadReadScope`), `all_projects`, `limit` (default 10, at most 50; a larger one answers 50). The project is looked up, never made (`findProjects` on the MCP context: resolveProject's lookup without creation): a folder the Inbox has never seen answers no results with a note, and one whose git did not answer in time (no existing project holds it) answers no results saying so, never `project_unresolved`. It runs the window's own ⌘K index (`searchIndex` on the MCP context, `group: "messages"`), waiting up to 10 s for a first build (`search_indexing` after that), and answers rows `{ thread_id, message_id, author ("person" or the agent's name), at, subject, snippet, question?, project? (all_projects) }` plus `total`. It writes nothing: no store line, no recent search, no agent-read mark. Measured on seeded threads (`tests/helpers/inbox-long-thread.ts`, as the hosts render them, step 1 → step 2, bytes / o200k tokens): a 60-message thread 99,971 / 34,689 → 18,848 / 6,658; 46 messages 76,535 / 26,319 → 14,969 / 5,172; 3 messages 6,065 / 2,032 → 2,652 / 877; the list of 17 threads 5,719 / 1,959 → 2,759 / 1,217; wait_for_reply 1,446 / 523 → 705 / 281. Pinned by `packages/server/inbox-mcp-window.test.ts` (a size budget and a per-message growth bound, the window semantics, the property test, both renderings, search) and `inbox-mcp-size.test.ts`.
- `supersedes` (send_message, submit_guide) is described in its own field (`SUPERSEDES_DESCRIPTION`), which reaches the model whole; send_message's description is cut at 2,048 characters and stays the question guide. `plannotator inbox --help` documents it and the `Replaces:` line ("Only in the Inbox", `INBOX_REPLACES_EXAMPLE`).
- The Inbox-only `Stopped:` / `Holds up:` lines (with the bare-negative rule and an example, `INBOX_STOP_EXAMPLE`) are taught in send_message's `body` field (`SEND_BODY_DESCRIPTION`), which reaches the model whole and rides the `plannotator_inbox` tool's `body`; never in `QUESTION_AUTHORING_GUIDE`, which plan review shares and the skill copies byte for byte.

**Server routes** are listed under "Inbox Server" in "Server API".

**On a phone**: `adr/implementation/inbox-mobile.md` is the wire contract the iPhone app and its server steps build against: the pairing offer, the device token door `/api/inbox/device/*`, the LAN listener, the relay, the surface bridge and the idempotency rule. Built (P1, P2, R1, R2, R3): pairing, the door, the tailnet path, the LAN listener, and the relay's mailboxes, push (APNs, and FCM for Android: section 10) and carriage. The Plannotator iPhone app lives in the Workspaces repo. The Inbox writes no event when a thread is deleted: a phone learns it at its next read of that thread. Not built: Bonjour discovery in 1.3 (a Wi-Fi address that moves is followed only by scanning the code again).

**Phones** (`packages/server/inbox-devices.ts`, records in `packages/shared/inbox/devices.ts`; contract sections 1, 2 and 6).
- Off unless `PLANNOTATOR_INBOX_PHONES=1` (or config.json `inboxPhones: true`) is set when the Inbox starts: until the iPhone app ships, a released Inbox has no pairing, no door, no reach switches, no relay and no Phones block, and every one of those routes answers the unknown-route 404 (see the env table). Everything below describes the Inbox with the switch on.
- Pairing: Settings' "Pair a phone" calls `POST /api/inbox/pairing`, which opens one offer: a `plannotator://pair` link (drawn as a QR code with `uqr`, `packages/inbox/qr.ts`) carrying the computer's name, the tailnet address when it is on, the LAN address and the certificate's SHA-256 (`lan`, `fp`) when the Wi-Fi is on, a 32-byte secret and six digits. One offer is open at a time, in memory only. It closes when redeemed, when the window makes another, 10 minutes after it was made, or after 5 wrong codes: the two limits pairing needs, and the only ones. The phone redeems the secret or the digits at `POST /api/inbox/device/pair` for its own `tok_` bearer token, returned once.
- Records under `inbox/`: `devices.jsonl` (the store's line rules; `dev_` id, name, platform, the token's SHA-256 and never the token, created, last seen, revoked, `carriage`), `device-secrets/<dev id>` (the pairing secret, 0600 in a 0700 folder, for the relay's keys; deleted on revoke) and `device-commands.jsonl` (the door's answers by key). Last seen is kept in memory on each request and written when its UTC day changes.
- The relay (`packages/server/inbox-relay.ts`; the Worker in `apps/relay`; contract section 4):
  - The first pairing makes the mailbox (`POST /v1/mailboxes` with the SHA-256 of a fresh 32-byte mailbox secret) and keeps it in `inbox/relay.json` (0600): `{ v: 1, url, mailbox_id, secret }`. The redemption's answer carries `relay: { url, mailbox_id }`, or null when the relay cannot be reached (a call waits 10 s at most). Each paired phone is registered by the SHA-256 of its relay secret (HKDF of its pairing secret, `deriveRelayKeys` in `packages/core/crypto.ts`) and removed at the relay when it is revoked.
  - One outbound WebSocket to the mailbox while a phone is paired, reconnecting 1 s to 60 s apart. `hello` writes each phone's relay switch into its record, removes at the relay a phone revoked here, and registers a phone the relay does not list; `carriage` writes the switch a phone flipped. The phone registers its push token at the relay itself, with its relay secret: APNs (iPhone) or FCM (Android, section 10), one per device.
  - The carriage (R2). Frames are handled one at a time in arrival order. Down: after `hello`, each phone with its switch on gets every store line after the cursor the relay holds for it (`changesSince`, as the event stream catches up), then each line as it is written, as an `item` sealed under the phone's key `K` (the event stream's `record` payload plus `v`, `type` and `after`, the seq the previous item reached, so the phone notices a gap); a line past Cloudflare's 32 MiB WebSocket message goes down as a `too_large` placeholder and the cursor moves past it. The push plaintext carries `type: "push"`, so neither can pass for the other. Up: each `command` is opened with the phone's up key `U` (a key per direction, so a down envelope reflected up does not open), applied in-process through the door as that device (`asDevice` in `inbox-devices.ts`: the revocation check, the allowlist and the idempotency log, never a loopback HTTP call), answered with a `result` item under the id sealed inside it (a sealed id that is not the relay's frame id is refused) with status, type and body bytes as base64 (files are GET results; a body over 3/4 of Cloudflare's 32 MiB WebSocket message, base64's growth, becomes a 413 `result_too_large` in its place, refused from its Content-Length before a byte is read, and a body without one read only until it passes that bound, `readRelayBody`), and reported `applied`. `pair` and `events` are not carried. A sealed command carries no headers in v1, so no Range reaches the window through the relay: a video's `video` or `download` answers the whole file, carried when it fits one frame and a `413 result_too_large` otherwise; the phone plays a video over the Wi-Fi or the tailnet (relay ranges of 8 MiB or less are v1.1, contract section 3 of `adr/implementation/inbox-mobile.md`). A command no key opens is reported applied with no result. The Inbox stopped, commands wait at the relay and are applied on the next start; a replay answers the stored result and writes nothing.
  - Push: an agent's message landing with a question or a guided review, or one that superseded earlier questions (replaced questions; then `question: null` unless it asks a new one), (its first line in the store) sends one push per paired phone whose switch is on, the summary (thread, subject, project, agent, and one single-choice question with up to four choices) sealed with `encryptWithKey` under that phone's key, collapsed per thread by an HMAC of the thread id under that key (the relay never sees a thread id). Over Apple's 4096 bytes it drops the question's context, then the question, then sends the ids alone.
  - The relay is `https://relay.plannotator.ai` (not yet deployed; until then a pairing answers `relay: null`) unless `PLANNOTATOR_RELAY_URL` names another. Tests never reach the hosted relay: the root preload and the test world point it at a closed loopback port.
  - The Worker (`apps/relay`): one Durable Object per mailbox on SQLite (`mailbox` with the secret's hash; `devices` with the relay secret's hash, the switch, the cursor, the APNs token and environment or the FCM token, the next item number; `items` and `commands`, envelopes kept in parts of 1,000,000 characters because a row may not pass 2 MB). Down items are deleted on the phone's ack (by item number, or by store cursor when it read directly) and when it turns its switch off; commands when the Inbox reports them applied; everything a device held when it is removed. A device holds one push token, APNs or FCM (`PUT .../apns` and `PUT .../fcm` each clear the other; `hello` lists `apns` and `fcm` per device), and a push goes to whichever it holds; with neither it answers `no_push_token` (`no_apns_token` before R3; the Inbox only logs the reason). APNs over HTTP/2 through `connect()` (`src/apns-h2.ts`; a Worker's `fetch` cannot reach APNs; it refuses a frame over 16 KiB and keeps at most 8 KiB of an answer), an ES256 provider token from the `APNS_KEY` secret kept 50 minutes; a 410 deletes the token; without the key a push answers `no_apns_key`. FCM (R3, `src/fcm.ts`): HTTP v1 `messages:send` with plain `fetch`, the body data only (`{ message: { token, data: { e }, android: { priority: "high", collapse_key } } }`), an OAuth access token minted from the `FCM_SERVICE_ACCOUNT` secret (the service account's JSON key file: an RS256 JWT signed with WebCrypto, exchanged at oauth2.googleapis.com) and kept 50 minutes; `UNREGISTERED` deletes the token (`fcm_gone`); any other refusal is `502 fcm_failed` with `fcm_status` and `fcm_reason`; without the secret a push answers `no_fcm_key`. The size ladder stays measured against the APNs body, which is always larger than FCM's data payload around the same envelope. Mailbox creation takes guides.show's rate limit rule (20 a minute per IP); nothing else is braked (pushes are not: a push needs the phone's push token, which only the app and the relay hold); nothing is swept by time. The proof-only host overrides (`APNS_ORIGIN`, `FCM_ORIGIN`, `FCM_OAUTH_ORIGIN`, `src/origin.ts`) are honored only for a loopback host; any other value is ignored with one log line, so no signed token goes elsewhere. Concurrent FCM pushes share one token exchange, and a refused exchange (or an unreadable private key) is answered from memory for a minute.
- The door, `/api/inbox/device/*`, in order: any `Origin` is `403 origin_not_allowed`; `pair` takes no token; then `Authorization: Bearer tok_…` (`401 device_token_missing`, `device_token_invalid`, `device_revoked`); then the explicit allowlist (`ALLOWLIST`: health, threads, projects, the archived threads, a thread, seen, events, picks, reply, resolve, delete thread, attachments, view, an attachment's `image`, `video` and `download` bytes (the window's `206` returned unchanged), markups, the HTML asset route, a message's images (`messages/:id/image?path=`, the window's route with its rules and headers), annotations and remove, comments on an agent's message's text (7.59), the guide, its ticks and comments on its diff, live sessions, New message, 👍 Looks good (`messages/:id/ack`), and since 2026-10-15 compose (`sessions`, `messages`, `messages/:id/to`), search, the project menu's batches, the skill catalog, and uploads and drawings (`uploads?name=`, `markups`: raw bodies streamed through with their query, the key in `?idempotency_key=`, bounded by the door itself since the window runs in-process (100 MB and 32 MB, declared or counted as they stream: `413 upload_too_large` / `markup_too_large` with `Connection: close`, nothing recorded); after a replay or refusal at most 1 MiB or 2 s of the rest is read and dropped, then `Connection: close`; not carried by the relay: `413 relay_upload_unavailable`; `POST messages` with `draft_id` is `422`, drafts stay on the computer); anything else `404 device_route_not_found`); then a POST needs `idempotency_key` (`422`; in the query on the two raw-body routes). The request then goes to the window's own handler through the server's own `fetch` on loopback, with the route, query and body unchanged; of the phone's headers only `Last-Event-ID`, `If-None-Match` and, on a GET, `Range` and `If-Range` ride along (plus `Content-Type` and `Content-Length` on the raw-body routes). `/mcp`, the bridge, control, settings, restart, raw attachment bytes, project delete, every Decisions route (removed: `decisions`, `messages/:id/decision`, retire and replace; `404 device_route_not_found`), drafts, recent searches, pairing, the device list, the tailnet and Wi-Fi switches and "Open in" (the launch, the app list and the new-tab page) are never on it.
- Idempotency: a POST's status and JSON body are kept per device and key and read at start. The same key on the same route answers them again with `Idempotent-Replayed: true` and writes nothing; on another route it is `409 idempotency_key_reused`; a 5xx is not kept.
- Remove: Settings' Remove (`POST /api/inbox/devices/:id/revoke`) or the phone's own `POST /api/inbox/device/revoke` marks the record revoked, deletes its secret and ends its open event streams. Its next request is `401 device_revoked`.
- Settings → Devices (`packages/inbox/components/Devices.tsx`, design of record `.product/approved/inbox-settings-tabs/`): the paired phones with platform, last seen and Remove (asked twice), and Pair a phone; "How your phone reaches this computer": This Wi-Fi (the LAN address, the certificate's SHA-256 shortened with the whole in its tooltip (`data-fingerprint`), where nothing can publish Bonjour a note that phones will not list it but the scan still pairs) and Tailscale (the served address; the phone path, renamed from "Reach from my tailnet"), each a switch named by its title with a "Not working" chip and the reason while on and failing, so one click turns it off.
- Pair a phone, step by step (`components/PairFlow.tsx`, words and gate in `packages/inbox/pairing.ts`), inline in Devices at `#settings/devices/pair`. It always starts at step 1 (owner, decision 3), "How will your phone reach this computer?": the two ways side by side, each with "This computer" (live checks from `GET /api/inbox/pairing/checks`: ✓, ! or × with the fix in one line; Check again reads them again, and again after each switch) and "Your phone needs" (what the computer cannot check: the same Wi-Fi by name, Local Network allowed, the Tailscale app signed in to the same tailnet), Turn on / Turn off in each card, and one line that Plannotator's relay is not available yet. **The no-loop rule** (owner, decision 5): the checks are advisory and never a gate; Turn on stays offered beside Check again whatever a check says; the ONLY gate on the code is a way switched on (`canShowCode`), so with a way on and every check failing "Continue to the code" still shows the code (`settingsSections.test.tsx`, `inbox-phones.spec.ts` prove it). With no way on the button reads "Show the code", `aria-disabled`, and a press only says to turn a way on; with neither way able to work a red line says so. Step 2 (`POST /api/inbox/pairing`): the QR, the six digits only while Tailscale carries an address (over Wi-Fi it pairs by scanning only), the addresses the code carries with Change (back to step 1), "Before you scan, on your phone", the countdown with New code and Cancel, and live notes from `GET /api/inbox/pairing` every 2 s (wrong digits with tries left, digits typed over the Wi-Fi, an older code, a phone after the code closed); on expiry with nothing seen, a numbered troubleshooting list for the ways that were on; a code closed by five wrong tries says so; a code another window replaced (the GET's `expires_at` is not this tab's) reads "This code was replaced", never as this tab's expiry or attempts. A double press makes one code (a ref guards `makeCode`). Step 3: "Paired with <name>", how it reached this computer, and Done (back to `#settings/devices`, focus on Pair a phone). Nothing reads the tailnet's other devices (owner, decision 4). A page opened over the tailnet offers no code: it says pairing and the switches work only from this computer's own screen.

**The surface** (PLAN step S1; contract section 5). `apps/inbox`'s `build:surface` (`vite.surface.config.ts`, entry `surface.html`) builds `packages/inbox/surface` into one file, which `build:hook` copies to `apps/hook/dist/surface.html`; the iPhone app bundles it.
- It mounts only `Viewer` with the annotation toolstrip, `HtmlViewer` with pins, `DiagramViewer` (lazy) and the guide (`packages/inbox/guide/SurfaceGuideReader.tsx` behind `#surface-guide-reader`, lazy: the sections, then one `GuideSectionCard` per screen).
- No network: CSP `default-src 'none'`, `connect-src 'none'`; an HTML page's folder loads from the shell's asset origin, `plannotator-asset:` on iOS and `https://appassets.androidplatform.net` on Android (both in the one file's policy). The system face on Plannotator's tokens; settings live in memory; diffs unified and wrapped.
- The bridge: `packages/core/inbox-surface-bridge.ts` (re-exported by `inbox-types`), the surface's end in `packages/inbox/surface/bridge.ts`: it posts to `window.webkit.messageHandlers.plannotatorSurface` when `window.webkit` exists, else to the Android shell's `window.plannotatorShell` as a JSON string (contract section 10). The composer is the shell's: the viewers report drafts through ui's `onHostDraft` seams, and `commit_annotation` draws the saved one.
- Proof: `tests/e2e/surface.spec.ts`, Playwright WebKit against the built file and a compiled Inbox (in `inbox-e2e.yml`).
- The iPhone app is the surface's host: one web view loads the bundled file, `plannotator-asset:` serves an open HTML page's folder through the door, and a guided review opens on the same web view (`open_guide`, `reviewed`, `section`, `set_wrap`; contract section 5). The Plannotator iPhone app lives in the Workspaces repo.
- Added for the phone (M2): `comment_selection` (Comment in the system edit menu; on a touch screen a markdown selection stays the system's until then, ui's `ViewerHandle.takeSelection`), `export_feedback` and `feedback` (Send's feedback text, built by `attachmentFeedback` as the window builds it), and ui's `HtmlViewer` `hostNavigates` (a tapped link in an agent's page opens as a new window the shell decides, never a frame message).

**Security**, on every request:
- The Host allowlist (`createRequestHostGuard({ localOnly: true })`) on the window's port. The tailnet listener ("Over your tailnet") runs its own checks instead: the served Host, the owner's `Tailscale-User-Login`, `Sec-Fetch-Site`.
- `/mcp` refuses any request with an Origin (403 `origin_not_allowed`) and any Host that is not a loopback name with this port (403 `forbidden_host`). Release note: an MCP client that reaches the Inbox through `ssh -L <other port>:127.0.0.1:<port>` sends `Host: localhost:<other port>` and is now refused; forward the same port number, or use `plannotator inbox mcp` on the Inbox's machine.
- The window's port refuses any request carrying `Tailscale-Headers-Info`, `Tailscale-User-Login` or `X-Forwarded-For` (403 `local_only`): it came through a serve mapping pointed straight at this port.
- Connection routes (`/api/inbox/bridge/*`, `/api/inbox/control/*`) take the registry's bearer token, a loopback Host naming this port, and no Origin.
- Nothing that arrives through the tailnet listener reaches `/mcp`, a connection route or the device door (403 `local_only`), whatever Host it claims.
- State-changing window routes run `isSameOriginOrNoOrigin` (403 `cross_origin`), then the `serverSession` stale-tab guard (409 `session_mismatch`).
- No CORS headers on the Inbox's routes. The one exception is annotate's asset route for an attached HTML page's folder.
- The window's CSP: `default-src 'self'`, inline script and style, `'wasm-unsafe-eval'` in `script-src` (the Graphviz engine, `@viz-js/viz`, compiles WebAssembly to render `.dot`/`.gv` attachments; it allows no `eval()` or `new Function()`, and there is no `'unsafe-eval'`), `connect-src 'self'`, `frame-ancestors 'none'`, `base-uri 'self'`, `form-action 'none'`. An attached HTML page's srcdoc frame inherits this policy.
- Agent text reaches the page only through React and Plannotator's markdown renderer.
- The device door (`/api/inbox/device/*`): no Origin, the phone's bearer token, the allowlist (see "Phones"). The tailnet and the Wi-Fi reach only the door, each through its own listener (see "Local only by default").
- DAST (`.github/workflows/dast.yml`) scans a seeded Inbox on port 19435, the door's refusals included.

**Proofs.** Every proof runs under a temp data dir, against a real server, with no mocks.
- Server and store:
  - `packages/server/inbox.test.ts`: registry, health, port reuse and fallback, restart to update, every refusal, and the MCP through the SDK's own client, including a real 50 s `wait_for_reply`.
  - `packages/server/inbox-threads.test.ts`: the row model live.
  - `packages/shared/inbox/store.test.ts`: fast-check properties, including routing determinism against an independent oracle.
  - `apps/hook/server/inbox-cli.test.ts`: the subcommand as processes, the shim through the SDK's stdio client, and uninstall.
  - `packages/server/inbox-data-gone.test.ts` and `apps/hook/server/inbox-data-gone-cli.test.ts`: an Inbox whose data folder is removed (with and without `--tailscale`), made again empty, or taken over stops on its own and never makes the folder again; an unreadable or half-written `inbox.json` or a moved copy of the folder never stops it; a stopping Inbox leaves its successor's entry alone.
  - `inbox-attachments.test.ts`, `inbox-guide-comments.test.ts` (comments on a guide's diffs: save, edit, remove, refusals, sent with the reply, closed after) and `inbox-bridge.test.ts`.
  - Replaced questions: `packages/shared/inbox/store-supersede.test.ts` and `packages/server/inbox-supersede.test.ts`.
  - Over your tailnet: `packages/shared/inbox/tailnet.test.ts` (identity parsing, Q-decoding, the owner check, the served Host, `Sec-Fetch-Site`, the switch's resolution), `packages/server/inbox-tailscale.test.ts` (a real Inbox with a scripted `tailscale` through the runner seam: the mapping, the owner let in and everyone else refused, Host claims, the connection surface and `/mcp` refused through the tailnet, the window's guards, the switch, restart, a crash leftover, a leftover kept while Tailscale is down, the record written before the mapping, a hand-made mapping onto the window port refused and replaced, a message's image through the tailnet (owner yes, wrong or no login and another site no), the switch turned off through the tailnet, a Settings save that saves nothing when refused, the env var's hard off, `uninstall --purge`, Phones beside it) and `apps/hook/server/inbox-tailscale-cli.test.ts` (the CLI as processes with a fake `tailscale` on PATH: `PLANNOTATOR_INBOX_TAILSCALE=1`, `--tailscale` against a running Inbox, the stop route and SIGTERM taking the mapping down, no `tailscale` at all). No test runs the real `tailscale`: the CLI test with none on PATH asserts its PATH holds no `tailscale`.
  - `packages/server/inbox-pairing.test.ts`: Pair a phone's two reads (`GET /api/inbox/pairing/checks` through scripted probes and a scripted `tailscale`, turning nothing on; `GET /api/inbox/pairing` with every attempt kind and its listener, expiry with nothing seen, five wrong tries, `reachable`), refused to another site and through the tailnet. The window side is `packages/inbox/settingsSections.test.tsx` (DOM, over `tests/helpers/inbox-dom-server.ts`'s `phones` mode) and `packages/inbox/pairing.test.ts`.
  - `packages/server/inbox-devices.test.ts`: every pairing and door exchange of the mobile contract (7.1 to 7.25, 7.36, 7.37) replayed with real fetch against `plannotator inbox --background`, a phone's pick and Send reaching the agent's `wait_for_reply`, the refusals, a key replayed across a restart; on the compiled binary in the inbox-e2e job.
  - `packages/server/inbox-lan.test.ts`: the Wi-Fi listener on `plannotator inbox --background`: a phone (`tests/helpers/pinned-phone.ts`, which pins the certificate's SHA-256 and sends raw HTTP/1.1) pairs over the LAN address (7.2) by the QR's secret, while six digits there are `400 code_not_accepted_here` and still pair on the window's port; a wrong fingerprint is refused before a byte is sent; spoofed Host, Origin, encoded paths, an absolute-form request line and a WebSocket upgrade reach nothing outside the door; off and on again keep the port; a listener that cannot open at start turns off; the Bonjour record read back with `dns-sd -L` on macOS; off, a clean stop, a kill -9 and the next start; `openssl` failing. The certificate is made at run time, never committed. On the compiled binary in the inbox-e2e job.
  - `apps/relay/test/relay.test.ts`: the relay under `wrangler dev` with `plannotator inbox --background` pointed at it and a local HTTP/2 server playing Apple (it checks the ES256 provider token): a pairing makes the mailbox and registers the phone; a replayed registration changes nothing; the phone's relay switch reaches the device record over the socket; a question is one push (two questions one, news none, a guided review one) whose envelope the phone's key opens; Apple's 4096 bytes; no push with the switch off; no key, secret, subject or body in the Durable Object's storage; a 410 deletes the token and the next push answers `no_push_token`; `hello` after a restart; a removed phone gone with what it held; the carriage (two phones, one with its switch off: the list, the thread, a pick and a Send as commands, the agent's `wait_for_reply` getting the answer; a replayed reply writing nothing; a down item reflected up refused; an attachment's view and a 1.4 MB HTML asset by request; the Inbox stopped with an answer queued, then started, the agent receiving it once; storage holding ciphertext only and empty after ack; ack by cursor; a revoked phone's items gone); `no_apns_key` and the creation brake on a relay without the key, where the APNs and FCM token routes (register, clear, one replacing the other, `hello`'s `apns` and `fcm`), `no_fcm_key` and `no_push_token` are checked too; FCM (R3) with an Android phone paired and Google's token endpoint and FCM played locally (the endpoint verifies the RS256 JWT against a throwaway RSA key; FCM checks the access token it minted): one data-only message per question, the envelope opening to the summary, the collapse key per thread, the access token reused, the size ladder against the APNs body, a 401 as `fcm_failed` and a fresh access token on the next push, a 5xx as `fcm_failed` keeping the token, `UNREGISTERED` deleting it as `fcm_gone`, and no Google credential in storage; concurrent pushes sharing one refused token exchange, remembered for a minute; host overrides that are not loopback ignored with one log line, and an unreadable private key as `fcm_failed`; a mailbox made under R2's schema gaining `fcm_token` on its first request; a hostile peer in Apple's place (a 16 MiB frame and a body flood fail at once; a graceful GOAWAY still answers); Apple's real sandbox and production answering 403 InvalidProviderToken to a throwaway key (only with `RELAY_PROOF_APPLE=1`, which the workflow sets, so a local run works offline). Run from `apps/relay` (`bun test`), on the compiled binary in the relay workflow (`.github/workflows/relay.yml`).
  - `packages/core/crypto.test.ts`: the relay's keys and envelope against `packages/core/fixtures/inbox-relay-vectors.json` (all-zero inputs), which the app checks in Swift too.
- The window: Playwright 1.63.0 headless Chromium against the compiled binary (`bun run test:e2e:inbox`, `.github/workflows/inbox-e2e.yml`), with agents writing through `plannotator inbox mcp` (`scripts/inbox-sim.ts`):
  - `tests/e2e/inbox.spec.ts`
  - `notifications.spec.ts`
  - `inbox-attachments.spec.ts`
  - `inbox-guides.spec.ts`
  - `inbox-thread-folding.spec.ts`
  - `inbox-order.spec.ts` (three agents' questions read newest first in Waiting on you; a reply moves its row to Sent)
  - `inbox-replaced.spec.ts` (an agent replaces a picked question while the person writes: the Quiet card, the links, the notice, the stale guard at Send, Send your words only, and a withdrawal moving the row out of Stopped on you; PNGs in `.local/proof/replaced/`)
  - `inbox-sidebar.spec.ts` (the sidebar's close and open sampled every frame, ⌘B and Ctrl+B, ⌘B left to the reply box, the reload, the peek, the edge's click, drag, snap-close and keyboard, reduced motion, the phone sheet; its PNGs, video and curves in `.local/proof/sidebar/`)
  - `inbox-phones.spec.ts` (Pair a phone step by step with `tailscale` a script on PATH, `fake-tailscale.ts`: step 1 first, no code until a way is on, the code over the tailnet's door, wrong digits seen, Paired, the device list and Remove; the no-loop rule on the binary; This Wi-Fi turned on in step 1 with a pinned phone pairing over the LAN, the no-Bonjour note and `openssl` failing; with `PLANNOTATOR_E2E_TAILNET=1` on a Mac signed in to Tailscale, the door at the MagicDNS name on 8443)
  - `inbox-settings.spec.ts` (Settings in sections: the nav, addresses, keyboard and focus, Back and Forward, the sidebar away and back without its cookie, ← Inbox to the thread; on an iPhone in WebKit the list of sections, ‹ Settings, and Pair a phone to the code)
  - `toolstrip-stacking.spec.ts` (the annotation toolstrip stays above the document: in the Inbox's attachment pane (beside, full screen, 1000 px, phone; always the Clean look) and in annotate at 1440, 1024 and 820 px, `elementFromPoint` across the strip lands on the strip with a table, code block, alert, diagram and question card scrolled under it; the stepping list stays above the document; the table popout still covers the strip. The pane isolates `.ib-docscroll` / `.ib-codeview`, because ui's Viewer wraps the document in a `relative z-50` layer that otherwise escapes into `.ib-view` over the strip, the error line and the stepping bar)
  - `inbox-tailscale.spec.ts` (Settings' "Over your tailnet": on and off with a `tailscale` script on PATH, Tailscale stopped, a run started with `--tailscale` and "Keep it on at every start", a hand-made mapping onto the window port and Replace; PNGs in `.local/proof/tailscale/`)
  - `inbox-soft-polish.spec.ts` (the Soft look's polish pass against each switch turned off in the same page: Mark read's keycap, a tile's name at rest, hovered and focused, left to right and right to left, the layout corners, the type knob on and off, rows with no line in light, dark, beside a thread and on a phone, the thread's other lines unchanged; PNGs in `.local/proof/soft-polish/`), with `packages/inbox/softType.test.ts` (the type knob reaches every size, its fallbacks are today's, the corner scale, the rows' and lines' switches)
  - `inbox-worst-case.spec.ts` (the worst realistic data from `scripts/inbox-worst-case.ts`: non-Latin and same-named project folders, right-to-left text, long file names, a message table and a tall screenshot, old dates, 46 projects, 50 live sessions; at 1440, 1280, 1024, an iPad, a phone, a phone on its side and 200% zoom it checks shapes, not pixels: nothing scrolls sideways, primary buttons stay in the window, columns keep a readable width. A break not fixed yet is a `test.fixme` naming its fix-plan row. PNGs in `.local/proof/worst-case/`)

  PNGs land in `.local/proof/`.

  Every spec makes its temp folders with `inboxScratch` and ends with `removeInboxScratch` in a `finally` (`tests/e2e/inbox-scratch.ts`); a spec that stops its own Inbox mid-test uses `stopScratchInbox`. Both signal only an Inbox proven to be the one the folder started (`provenInbox` in `tests/helpers/inbox-process.ts`, shared by every test): an entry remembered after each start or found in an `inbox.json` under the folder, whose command line is still `plannotator inbox` / `index.ts inbox`, and whose port answers health with that pid and `serverSession` (or, with nothing answering, whose working directory, `/proc` or `lsof`, is inside the folder). SIGTERM, then SIGKILL after re-proving, then the folder goes.
- The connections:
  - Claude Code: `apps/hook/hooks/mod/inbox.test.ts`, run by `.github/workflows/inbox-claude-code.yml`.
  - Pi: `apps/pi-extension/inbox.test.ts`, the real Pi in RPC mode, plus the 0.79.1 floor in `.github/workflows/inbox-pi.yml`.
  - OpenCode: `apps/opencode-plugin/inbox-v2.test.ts`, the packed plugin in the real `opencode2`, run by the "OpenCode 2 installed package" job in `test.yml`, plus `inbox.test.ts` for OpenCode 1.
  - All three use a scripted model endpoint (`tests/helpers/scripted-model.ts`) and a real Inbox (`tests/helpers/inbox-world.ts`).

## Archive Flow

```
User runs plannotator archive (CLI)
        ↓
Server starts in mode:"archive", reads ~/.plannotator/plans/
        ↓
Browser opens read-only archive viewer
        ↓
User browses saved plan decisions with approved/denied badges
        ↓
Done → POST /api/done closes the browser
```

During normal plan review, an Archive sidebar tab provides the same browsing via linked doc overlay without leaving the current session.

## Server API

### Plan Server (`packages/server/index.ts`)

| Endpoint              | Method | Purpose                                    |
| --------------------- | ------ | ------------------------------------------ |
| `/api/plan`           | GET    | Returns `{ plan, origin, previousPlan, versionInfo, approvalNotesSupported }` (plan mode; `approvalNotesSupported` says whether the launching host delivers notes sent with an approval, see "Plan review header decision control") or `{ plan, origin, mode: "archive", archivePlans }` (archive mode) |
| `/api/plan/version`   | GET    | Fetch specific version (`?v=N`)            |
| `/api/plan/versions`  | GET    | List all versions of current plan          |
| `/api/plan/revision`  | GET    | `{ revision, decided }` for a review that receives revised plans while open (see "Pi plan review does not block"). With `planRevisions: true` on the server options, `/api/plan` also carries `planRevision`; `/api/approve` / `/api/deny` refuse a stale `planRevision` with `409 { code: "plan_revised" }` |
| `/api/archive/plans`  | GET    | List archived plan decisions (`?customPath=`) |
| `/api/archive/plan`   | GET    | Fetch archived plan content (`?filename=&customPath=`) |
| `/api/done`           | POST   | Close archive browser (archive mode only)  |
| `/api/approve`        | POST   | Approve plan (body: planSave, agentSwitch, obsidian, bear, feedback, serverSession?; see "Stale-tab guard") |
| `/api/deny`           | POST   | Deny plan (body: feedback, planSave, answersOnly?, serverSession?). `answersOnly: true` (a boolean, nothing else) rides the decision so the consumer sends `plan.answered` instead of the denied prompt; see "Question blocks" |
| `/api/save-notes`     | POST   | Save to external note apps (Obsidian, Bear, Octarine) |
| `/api/update`         | POST   | Update now from the update toast or the Options menu (compiled CLI, the binary the install script manages): the install script for the newest known release, detached, once (`update.lock`). Loopback Host with this port and same origin only, never for a remote-mode or `--tailscale` session, body `{ serverSession? }`; `403` / `409 { code }` when it cannot run (see the `PLANNOTATOR_UPDATE_CHECK` row). Also on the review and annotate servers |
| `/api/image`          | GET    | Serve image by path query param. Every answer carries `Content-Security-Policy: sandbox; …`, `nosniff` and `Cross-Origin-Resource-Policy: same-origin` (`packages/shared/local-image.ts`, both runtimes), so an SVG opened directly runs no script |
| `/api/upload`         | POST   | Upload image, returns `{ path, originalName }` |
| `/api/obsidian/vaults`| GET    | Detect available Obsidian vaults           |
| `/api/skills`         | GET    | List global agent skills for comment skill references (`{ skills: [{ name, root, description?, humanOnly, dir }] }`) |
| `/api/skills/content` | GET    | SKILL.md contents of one discovered skill for human-only feedback injection (`?name=<skill>`) returns `{ skill: { name, dir, path, content, truncated, humanOnly } }`; the name is matched against discovery only, never used as a path |
| `/api/reference/obsidian/files` | GET | List vault markdown files as nested tree (`?vaultPath=<path>`) |
| `/api/reference/obsidian/doc`   | GET | Read a vault markdown file (`?vaultPath=<path>&path=<file>`) |
| `/api/plan/vscode-diff` | POST   | Open diff in VS Code (body: baseVersion)   |
| `/api/doc`              | GET    | Serve linked .md/.mdx file (`?path=<path>`). When the hook reports the plan's own file (Claude Code's `planFilePath`, trusted only when its contents equal the plan), `/api/plan` advertises `planDir` and a request with `base=<planDir>` is also served from that directory, but only for paths that are exactly one of the plan's link targets (`[x](target)`, `[[target]]`, HTML `href`, ignoring links inside code; both sides compared with `?query`/`#fragment` dropped, percent-decoding and `./` collapsed, and the file served is the one that normalized target names; `resolvePlanLinkedDoc` in `packages/shared/doc-resolve.ts`) — other files there, such as other plans in `~/.claude/plans/`, stay unreachable. A linked file beside the plan shadows a project document of the same relative name; everything else resolves against the project roots exactly as without a base. Bun plan server only (Pi plans live under the project root) |
| `/api/doc/exists`       | POST   | Batch-validate code-file paths (body: `{ paths: string[], base?: string }`) returns `{ results: { [path]: { status: "found"\|"ambiguous"\|"missing"\|"unavailable", … } } }` |
| `/api/draft`          | GET/POST/DELETE | Auto-save annotation drafts to survive server crashes |
| `/api/editor-annotations` | GET | List editor annotations (VS Code only) |
| `/api/editor-annotation` | POST/DELETE | Add or remove an editor annotation (VS Code only) |
| `/api/ai/capabilities` | GET | Check if AI features are available |
| `/api/ai/session` | POST | Create or fork an AI session |
| `/api/ai/query` | POST | Send a message and stream the response (SSE) |
| `/api/ai/abort` | POST | Abort the current query |
| `/api/ai/permission` | POST | Respond to a permission request |
| `/api/ai/sessions` | GET | List active sessions |
| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind: "plan", documents: [], unsentAnnotations, decided }`. A plan review has no host close (`POST /api/host/close` answers `409 { code: "not_closable" }`). |

### Review Server (`packages/server/review.ts`)

| Endpoint              | Method | Purpose                                    |
| --------------------- | ------ | ------------------------------------------ |
| `/api/diff`           | GET    | Returns `{ rawPatch, gitRef, snapshotId, origin, mode?, diffType, base, hideWhitespace, gitContext, agentCwd?, approvalNotesSupported, semanticDiff?, callFlow?, sections?, commitInfo?, generatedFiles?, baseBehindRemote? }`. `snapshotId` identifies this diff snapshot; the client echoes it on `/api/diff/fresh` probes (also returned by the switch/PR endpoints). `approvalNotesSupported` is the approve-with-notes capability advert (echoed on `/api/diff/switch`, `/api/pr-diff-scope`, and `/api/pr-switch` too, so it survives a diff switch); absent reads as false. `sections` is the since-base sidecar (Committed/Changes/Untracked partition); `commitInfo` is the commit-metadata sidecar (subject, markdown body, author + avatar) present only while a `commit:<sha>` (or jj `jj-commit:<commit id>`) diff is active; `generatedFiles` lists the repo-relative paths that count as generated, which the client collapses by default GitHub-style (presentation-only: the patch is never filtered). Two-layer detection (`packages/shared/generated-files.ts`, vendored to Pi): built-in name defaults (`DEFAULT_GENERATED_PATTERNS`, which lives in `@plannotator/core/file-kind` so the client's file kinds share it — lockfiles like `bun.lock`/`package-lock.json`/`Cargo.lock`, plus `*.min.js`/`*.min.css`/`*.map`, matched against the path's last segment) apply in every mode with no git needed, and explicit `.gitattributes` `linguist-generated` refines them in BOTH directions via one batched `git check-attr --stdin` at the review cwd (set/true marks any file, unset/false un-marks even a built-in name, unspecified keeps the default). Attribute refinement runs for plain local Git sessions only — PR worktrees, workspace, jj, GitButler, P4, and piped patches get the name-based defaults alone; `baseBehindRemote` flags that the diff base is behind its remote tip. Workspace mode returns `mode: "workspace"` with folder-prefixed paths and no `gitContext`. |
| `/api/diff/switch`    | POST   | Switch diff type, base branch, or whitespace mode (body: `{ diffType, base?, hideWhitespace?, explicitBase? }` — `diffType` includes the `commit:<sha>` family, and `jj-commit:<commit id>` in a jj session). Also kicks off the rate-limited remote-default/staleness probe fire-and-forget (#1553): this endpoint backs the pickers AND the "Diff out of date · Refresh" button, so it is where a reviewer asks for a fresh answer. Fire-and-forget because a hanging remote must never make a diff switch wait — this response carries the cached `baseBehindRemote` and the next one carries the refreshed value. `explicitBase: true` marks a base the user picked from the picker — the server then honors it verbatim and permanently disables the bare-local-name → `origin/*` canonicalization for the session (echoed bases stay canonicalizable). Response includes `semanticDiff?`, `callFlow?`, `sections?`, `commitInfo?`, `generatedFiles?`, `baseBehindRemote?`, or `{ superseded: true }` when a newer concurrent switch has taken over (client ignores it). |
| `/api/commits`        | GET    | One page of the branch's linear `--first-parent` history for the Commits panel (`?limit=&before=`) → `{ commits, hasMore, base }`. Rows carry `isHead` / `isPastBase` (where the branch meets the active base) and best-effort author `avatarUrl`. Local git and jj sessions only (PR/workspace/GitButler/p4 → 400); computed against the active diff's cwd, so worktree sessions list the worktree's history. In a jj session the rail walks first parents from `@` (`isHead` = the working copy, `shortSha` = the short change id, `base` = the compare target's label) and clicks open `jj-commit:<commit id>`; a jj older than 0.33 (no `first_ancestors`) answers `500` with a message naming the version. |
| `/api/diff/fresh`     | GET    | Cheap staleness probe: recomputes the VCS fingerprint captured with the current diff snapshot and returns `{ fresh, fingerprint?, baseBehindRemote?, agentCwd? }`. Strictly **local**: it never contacts the git remote (#1553 — the client polls it every 5s, so the remote probe that used to hang off it made an idle session query the remote once a minute forever). `baseBehindRemote` is carried from the cached value refreshed by the other endpoints. Accepts `?snapshot=<id>` — the client echoes the `snapshotId` it received with its diff, and a mismatch with the server's current snapshot reports stale PER CLIENT (covers the startup base upgrade and cross-tab switches even when the VCS fingerprint matches). `baseBehindRemote` is carried on every response (omitting it would flicker the "behind GitHub" banner); `agentCwd` re-advertises the PR checkout in PR mode. Unfingerprintable modes (e.g. P4) always report fresh to a matching snapshot. Polled by the UI's "Diff out of date · Refresh" notice. |
| `/api/fetch-base`     | POST   | Runs `git fetch` for the base's remote tracking ref, then re-queries the remote tip (fresh `ls-remote`) so narrow-refspec fetches report honestly. Backs the "Baseline is behind GitHub · Fetch" banner. Git-only, base-relative diff types only. |
| `/api/semantic-diff`  | GET    | Runs semantic diff for the active patch and returns parsed sem output or an unavailable/error response (`?fileExt=` / `?fileExts=` optional). |
| `/api/call-flow`      | GET    | Runs snapshot-bound CallDiff analysis for the active Git review (`?snapshot=<id>` required). Returns bounded call trees, raw output, per-file impacts, and explicit skipped-language/file metadata for packs not yet installed. |
| `/api/call-flow/install` | POST | Starts or joins the selective install (`{ languageIds?: [...] }`; omission uses the current review's server-authored plan). The UI calls it automatically once per target per review session after Call flow consent; manual calls remain for Retry and install-ahead. The coordinator deduplicates/queues core and pack targets, a stale-tolerant data-dir lease serializes publication across server processes, Node >= 22 preflight runs before download, and the endpoint enforces the same-origin guard. |
| `/api/call-flow/install-status` | GET | Poll `{ state, stage?, languageIds?, currentLanguageId?, error?, reason? }` across `downloading` / `verifying` / `installing-deps` / `building`. |
| `/api/review-analysis` | GET / POST  | GET refreshes capability adverts without mutating settings; POST persists independent `{ semanticDiff, callFlow }` booleans and returns adverts. |
| `/api/file-content`   | GET    | Returns `{ oldContent, newContent }` for expandable diff context (`?path=&oldPath=&base=`) |
| `/api/review-image`   | GET    | One side of a changed image as raw bytes for the Before/After preview (`?path=&side=old\|new&snapshot=`; #1598). Serves only a file in the current patch whose chunk has no hunks and whose path is `png jpg jpeg gif webp svg avif bmp ico apng`; the old path is taken from the chunk, never the client. `Content-Type` is sniffed from magic bytes; every image response carries `nosniff`, `Content-Security-Policy: sandbox; …` and `Cross-Origin-Resource-Policy: same-origin`, plus `ETag` (304 on `If-None-Match`) and `X-Image-Width`/`X-Image-Height` when the header parses. Errors are JSON `{ reason, error }`: `400 unavailable\|bad-request`, `404 not-in-diff\|absent\|missing`, `409 stale`, `413 too-large` (10 MB per side or 50 megapixels), `415 not-image\|lfs-pointer`, `502 fetch-failed`. Advertised by `imagePreviewSupported` on every diff payload (false for static-patch and P4 sessions). |
| `/api/review-markdown-image` | GET | An image a previewed Markdown file shows, read at that side's revision (`?doc=&side=old\|new&src=&snapshot=`; see "Markdown preview in code review"). Serves only an image path the Markdown file `doc` (in the current patch) references at that side, resolved against its folder there (`/` = repository root). Same caps, sniffing, headers and ETag as `/api/review-image`; extra refusals `403 outside-repo\|not-referenced`. Available where `imagePreviewSupported` is; the preview itself is advertised by `markdownPreviewSupported` (false only for static-patch sessions). |
| `/api/git-add`        | POST   | Stage/unstage a file (body: `{ filePath, undo? }`) |
| `/api/review-progress?snapshot=<snapshotId>` | GET/POST | Load or save durable viewed-file progress. GET returns `{ available, key?, fingerprints?, viewedFiles?, suppressedFiles? }`; POST takes `{ key, changes: [{ path, fingerprint, viewed }] }`. Stale snapshots return 409. |
| `/api/feedback`       | POST   | Submit review (body: feedback, annotations, agentSwitch, platform?, serverSession?). `platform: true` (boolean only) marks the status post the PR-platform path sends after `/api/pr-action`; it rides onto the decision, where the Claude Code mod logs it instead of starting a turn and OpenCode, Pi, CLI stdout and Amp deliver the status line verbatim without the request-changes suffix. Never infer it from empty `annotations` (see "Host result file") |
| `/api/image`          | GET    | Serve image by path query param (sandboxed headers, see the plan server row) |
| `/api/upload`         | POST   | Upload image, returns `{ path, originalName }` |
| `/api/draft`          | GET/POST/DELETE | Auto-save annotation drafts to survive server crashes |
| `/api/editor-annotations` | GET | List editor annotations (VS Code only) |
| `/api/editor-annotation` | POST/DELETE | Add or remove an editor annotation (VS Code only) |
| `/api/ai/capabilities` | GET | Check if AI features are available |
| `/api/ai/session` | POST | Create or fork an AI session |
| `/api/ai/query` | POST | Send a message and stream the response (SSE) |
| `/api/ai/abort` | POST | Abort the current query |
| `/api/ai/permission` | POST | Respond to a permission request |
| `/api/ai/sessions` | GET | List active sessions |
| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind, documents, unsentAnnotations, decided }`; counts only, never comment text |
| `/api/host/close` | POST | Host-only: the reviewer's Close marked `closedBy: "agent"`, KEEPING the draft; tells open tabs over the external-annotation SSE (`session-closed`) and answers `{ unsentAnnotations }`; `409 { code: "already_decided" }` once decided |
| `/api/agents/capabilities` | GET | Check available agent providers (claude, codex, tour, guide, cursor, opencode, pi, copilot) |
| `/api/agents/review-profiles` | GET | List launchable review profiles (enabled skills + builtin default) |
| `/api/agents/skills` | GET | List all discovered skills for the add-a-review picker (each flagged `enabled`) |
| `/api/agents/review-skills` | POST | Enable a skill as a review (body: `{ name }`); writes `review-skills.json` |
| `/api/agents/guide-instructions` | GET/PUT | Read or replace the Guided Review standing instructions, stored in `${dataDir}/guide-instructions.md` (trimmed, capped; blank PUT deletes). Guide launches whose body carries no `instructions` apply this stored text. |
| `/api/agents/jobs/stream` | GET | SSE stream for real-time agent job status updates |
| `/api/agents/jobs` | GET | Snapshot of agent jobs (polling fallback, `?since=N` for version gating) |
| `/api/agents/jobs` | POST | Launch an agent job (body: `{ provider, command, label, engine?, model?, effort?, reasoningEffort?, thinking?, fastMode?, reviewProfileId?, repairOf?, instructions? }`; `instructions` is guide-only reviewer text appended to the organizer prompt, capped at `GUIDE_EXTRA_INSTRUCTIONS_MAX_CHARS`; when absent, guide launches apply the server-stored standing instructions) |
| `/api/agents/jobs` | DELETE | Kill all running agent jobs |
| `/api/agents/jobs/:id` | DELETE | Kill a specific agent job |
| `/api/pr-diff-scope` | POST | Switch between layer and full-stack diff scope. Response includes `semanticDiff?`. |
| `/api/pr-list` | GET | List PRs for the current repo (cached 30s) |
| `/api/pr-switch` | POST | Switch to a different PR in-place (body: `{ url }`). Response includes `semanticDiff?`. |
| `/api/tour/:jobId` | GET | Fetch Code Tour result (greeting, stops, checklist) for a completed tour job |
| `/api/tour/:jobId/checklist` | PUT | Persist checklist item state for a Code Tour |
| `/api/guide/:jobId` | GET | Fetch Guided Review result (ordered sections with overviews + file refs) for a completed guide job, or a persisted guide via the `saved:{id}` pseudo job id |
| `/api/guide/:jobId/reviewed` | PUT | Persist per-section reviewed state for a guide (live job ids write through to the job's autosaved file; `saved:{id}` ids persist directly) |
| `/api/guide/:jobId/export` | GET | Download a guide as one portable HTML file (`Content-Disposition: attachment`): live job ids resolve from the session's launch-time review (store fallback), `saved:{id}` from the store. 404 when the guide's diff was not retained (pre-portable envelopes). No size gate. `/api/guide/:jobId/export-info` returns `{ bytes, filename, languages }` for the same resolution. |
| `/api/guide/:jobId/share` | POST | Create a share link for a guide on the guide host (`resolveGuideShareUrl`; guide share hosting contract `adr/implementation/guide-share-hosting.md` §7). Body `{ public?: boolean, ttlSeconds?: number }`, every field optional and an empty body means the defaults: encrypted upload (the key lives only in the returned URL's `#key=` fragment; the host stores ciphertext) unless `public: true` stores the snapshot unencrypted so the hosted page can carry a title and `og:` tags. Resolves the guide exactly like `/export` (launch-time review, `saved:{id}` from the store). `200 { id, url, deleteToken, expiresAt?, bytes, recorded }` where `recorded` says whether the saved envelope now remembers `share: { id, url, createdAt, deleteToken, serviceUrl }` (false without an envelope, e.g. guide history off, in which case only the one-time token can remove the link). `400` bad body, `403 { error: "sharing disabled" }` when `PLANNOTATOR_SHARE=disabled` (also the same-origin guard as other mutating endpoints), `404` when the diff was not retained, `409 { error, url }` when the envelope already records a link (one link per guide: the record is the only place the token lives, so a second upload would orphan the first), `502 { error }` on a service failure (`GuideShareError`). |
| `/api/guide/:jobId/share` | DELETE | Remove the recorded share link: calls the host the record names (`serviceUrl`, never merely the currently configured share URL) with the stored delete token and clears the envelope record. `204`; `404` when no record; a host `404` (already expired or removed elsewhere) still clears the record; other host errors `502`. Same-origin guard. |
| `/api/guide/:jobId/share-info` | GET | `{ enabled, serviceUrl, existing?: { url, createdAt } }`: whether sharing is on (`resolveSharingEnabled`), which host links go to, and the link the saved envelope already records, so the UI can hide "Create share link" or offer Remove link. |
| `/api/guides` | GET | List persisted guides for the current repo: `[{ id, label, title, savedAt, progress: { reviewed, total }, moved }]` — `moved` flags a stored head sha that differs from the head currently under review |
| `/api/guides/:id` | DELETE | Delete a persisted guide. A recorded share link is removed from its host first, best effort: the envelope is the only copy of the delete token, so a host failure is logged with the manual `plannotator guide unshare` command and the delete still proceeds |
| `/api/guide/:jobId/output` | GET | Fetch a failed guide job's captured raw output for manual repair (404 if none captured) |
| `/api/guide/:jobId/submit` | POST | Manually submit corrected guide JSON for a failed job (body: `{ payload }`) |
| `/api/code-nav/resolve` | POST | Search for symbol definitions and references via ripgrep (body: `{ symbol, filePath, line, charStart, side, language? }`) |
| `/api/code-nav/hover` | POST | Token hover card resolution: the same body and the same guards as `/resolve`, over the same ripgrep search, returning one enriched definition (kind, approximate signature, heuristic doc comment, short preview), an optional runner-up candidate, and a five-reference sample. `backend: 'unavailable'` (rg missing) is a normal 200 and the client renders nothing. `source` is always `'search'` in Tier 0; the nullable `symbolKind` / `signature` / `doc` fields are what a later syntax- or index-backed tier would fill. Client-side the card is governed by two cookie-only settings (`packages/ui/config/settings.ts`, types in `@plannotator/core/token-hover`): `tokenHoverTrigger` (`hover` default / `modifier`, meaning the platform's primary modifier held, Cmd on macOS and Ctrl elsewhere via `isModKeyHeld` / `modEventKey` in `packages/ui/utils/platform.ts` / `off`, which withholds the handler props so the diff views wire no listeners at all) and `tokenHoverDelay` (150 / 300 default / 700 ms, the dwell before any request exists; 300 matches the VS Code hover delay). `tokenHoverTrigger` REPLACED the original `tokenHoverCards` boolean and re-reads its cookie as a migration on every load until the user touches the setting (`false` becomes `off`), never writing it back: a migrating read returns a value, so the registry's default-seeding write never fires, and resolution is pure and identical every time. Cmd rather than Alt because Alt is widely bound to push-to-talk dictation (an Alt gate would open cards while the user speaks) and because Cmd+hover is already VS Code's "tell me about this symbol" gesture; the navigable-target underline and the card under one held key is that composite gesture, not a collision, since `handleCodeNavRequest` dismisses the hover surface on every References invocation. Only the modifier ALONE arms: any other key while it is held (Cmd+C) disarms and closes, so a copy with the pointer parked on a token cannot pop a card. Both key branches read `composedPath()[0]`, not `event.target`, because a window-level listener sees the shadow HOST and Pierre's edit-session editor is a contenteditable inside that root; typing suppresses ARMING only, never disarming, and keyup carries no typing guard at all. The `pn-token-nav` affordance is the other half of the held-key gesture: the diff views paint it from the pointer enter event, and the hook additionally reports arm/disarm through `onModifierGate(armed, tokenElement)` so a key pressed over a parked pointer (and the release after it) paints and unpaints it too. `pn-token-hover` (underline plus a `cursor: pointer !important` that beats Pierre's I-beam) is painted by BOTH diff views, gated on a hover handler actually being wired, so `off` and the portable viewer get no affordance. Click behavior is untouched by the trigger setting, and the #1461 Alt+click References alias is unrelated. The stored value stays `modifier`: the setting names the shape of the gate, not which key fills it. |
| `/api/code-nav/file` | GET | Read file from working tree for code-nav preview (`?path=`) |

### Annotate Server (`packages/server/annotate.ts`)

| Endpoint              | Method | Purpose                                    |
| --------------------- | ------ | ------------------------------------------ |
| `/api/plan`           | GET    | Returns `{ plan, origin, mode: "annotate", filePath, sourceInfo?, gate, renderAs?, rawHtml?, previousPlan?, versionInfo?, diffCurrent?, diffHtml? }`. `renderAs` is `"markdown"`, `"html"`, or — for a whole-file diagram source (`.mmd`/`.mermaid`/`.dot`/`.gv`) — `"mermaid"` / `"graphviz"`, in which case `plan` is the file's RAW text and the editor renders it as one diagram block (see "Diagram files"). The decision is the pure, shared `annotateDiagramRenderKind` (`packages/core/annotatable.ts`), so a raw-HTML, converted, URL, folder, message or live-app session is never a diagram session in either runtime. The last four power the per-file version diff: `previousPlan`/`versionInfo`/`diffCurrent` for the markdown diff, `diffHtml` (the previous→current page rendered with inline `<ins>`/`<del>`) for `--render-html` files. A local rendered-HTML root is served from its CURRENT bytes on every read (`readRootHtml`), with the startup snapshot as the fallback when the file is missing, unreadable, or over the 2MB cap; when the served bytes differ from the snapshot, `previousPlan`/`versionInfo` still name the saved baseline and `diffCurrent`/`diffHtml` are recomputed against the served bytes (`htmlDiff` is pure; a GET never writes history), so a reload after an agent edit keeps the version diff. `/api/doc` carries the same recomputed `previousPlan`/`versionInfo`/`diffHtml` when it serves that root document (the in-app Refresh path, `rootHtmlVersionDiff`), and nothing extra for any other document. Live app sessions return `{ mode: "annotate-app", appUrl, targetUrl, liveToken, sharingEnabled: false, ... }` instead: no rawHtml, no version fields (see "Live app annotation"). A review of several files answers `{ mode: "annotate-bundle", plan: "", bundle: [{ path, renderAs }], projectRoot: <bundle root>, documentDrafts: true, ... }` (see "Several files in one review"). |
| `/api/plan/version`   | GET    | Fetch a specific stored version of the annotated file (`?v=N`) |
| `/api/plan/versions`  | GET    | List all stored versions of the annotated file |
| `/api/plan/versions`  | POST   | Save the session's own file, as it is on disk now, as the next version (#2037; see "Live versions" under Plan Version History). Body `{ serverSession?, hash }`: `hash` is the source hash of the text the editor shows; the server reads the file itself and saves only while its bytes still have that hash. `200 { ok: true, saved, previousPlan, versionInfo }` (`saved: false` when the text equals the latest version); `400 validation_error`, `404 not_eligible` (not a single local Markdown/text session: `.yaml`, `.json`, `.mmd` and the like answer it too), `409 history_off` / `stale` / `missing` / `empty` / `session_mismatch`, `413 too_large` (past the 2MB `MAX_ANNOTATABLE_FILE_BYTES`, checked before and after the read), `500 history_unavailable`. `/api/plan` advertises it with `liveVersions: true` (absent when history is off or the session is not eligible). Both runtimes, through `saveAnnotateLiveVersion` (`packages/shared/annotate-live-version.ts`) |
| `/api/feedback`       | POST   | Submit annotations (body: feedback, annotations, serverSession?) |
| `/api/approve`        | POST   | Approve without feedback (review-gate UX, `--gate`) |
| `/api/exit`           | POST   | Close session without feedback (`?serverSession=` in the query; the body is empty) |
| `/api/save-notes`     | POST   | Save to external note apps (Obsidian, Bear, Octarine) |
| `/api/html-assets/<token>/<path>` | GET | Serve relative support assets for raw HTML annotation sessions (every non-HTML asset with `Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src 'self' data:` and nosniff, so an SVG or XML opened as a document runs no script on the session origin), and the sibling `.html`/`.htm` documents an annotated page EMBEDS (`<iframe>`/`<embed>`/`<object>`/`<frame>`). The served page carries a `<base href>` pointing here, which is what makes relative URLs — including ones a script assigns at runtime — resolve against the document's own directory. The token's root is that directory, or in an `annotate-folder` session the selected folder (so `../` reaches siblings inside it; outside the page's own directory, hidden paths and the dotenv family are then `404`). HTML responses carry `Content-Security-Policy: sandbox allow-scripts allow-modals` (no `allow-same-origin`, so an embed can never call this session's API) plus `nosniff`, and honour the 2MB annotate cap; a framed or `.html` failure renders a small 404 document naming the file rather than JSON or the app. See "Embedded local documents" under Annotation System. |
| `/api/share-html`     | GET    | Lazily prepare portable raw HTML for sharing (`?path=<html-file>` optional) |
| `/api/image`          | GET    | Serve image by path query param (sandboxed headers, see the plan server row) |
| `/api/upload`         | POST   | Upload image, returns `{ path, originalName }` |
| `/api/doc`            | GET    | Serve linked .md/.mdx/.html file or code file (`?path=<path>&base=<dir>`). A diagram source carries the same `renderAs: "mermaid" \| "graphviz"` with its raw text as `markdown`, so folder navigation opens it in the diagram viewer too |
| `/api/doc/exists`     | POST   | Batch-validate code-file paths (body: `{ paths: string[], base?: string }`) |
| `/api/skills`         | GET    | List global agent skills for comment skill references (`{ skills: [{ name, root, description?, humanOnly, dir }] }`) |
| `/api/skills/content` | GET    | SKILL.md contents of one discovered skill for human-only feedback injection (`?name=<skill>`) returns `{ skill: { name, dir, path, content, truncated, humanOnly } }`; the name is matched against discovery only, never used as a path |
| `/api/draft`          | GET/POST/DELETE | Auto-save annotation drafts to survive server crashes. A single local file is keyed by its content AND its path (see "Annotate drafts follow the file"); with the path copy in use a stale save answers `409 { ok: false, error: "stale draft generation", found, draftGeneration }`, and the client (`useAnnotationDraft`, default transport) adopts `draftGeneration` and saves once more above it. After the review is decided every save (any session kind, any generation) answers `409 { ok: false, decided: true, error, found, draftGeneration }`, which the client never retries |
| `/api/draft/document` | GET/POST | Per-document draft copies (local-file and folder sessions; `/api/plan` advertises `documentDrafts: true`): GET `?path=<abs>` returns `{ found, annotations, globalAttachments }` (404 when none, 400 when the path is not an existing regular file, 403 outside the session's roots or for a single-file session's own file, symlink aliases included); POST `{ documents: [{ path, annotations, globalAttachments? }] }` returns `{ ok, written, rejected? }`, an empty list clears that copy, and `409` after a decision |
| `/api/annotate/client-lease` | GET (SSE) | Client lease for local direct structured gates: each open stream is one connected review surface. 404 when the capability is not advertised. |
| `/api/agent-terminal/pty/<token>` | WebSocket | Tokenized PTY bridge for the optional annotate-mode agent terminal |
| `/api/ai/capabilities` | GET | Check if AI features are available |
| `/api/ai/session` | POST | Create or fork an AI session |
| `/api/ai/query` | POST | Send a message and stream the response (SSE) |
| `/api/ai/abort` | POST | Abort the current query |
| `/api/ai/permission` | POST | Respond to a permission request |
| `/api/ai/sessions` | GET | List active sessions |
| `/api/external-annotations/stream` | GET | SSE stream for real-time external annotations |
| `/api/external-annotations` | GET | Snapshot of external annotations (polling fallback, `?since=N` for version gating) |
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind, documents, unsentAnnotations, decided }`; counts only, never comment text |
| `/api/host/close` | POST | Host-only: the reviewer's Close marked `closedBy: "agent"`, KEEPING the draft; tells open tabs over the external-annotation SSE (`session-closed`) and answers `{ unsentAnnotations }`; `409 { code: "already_decided" }` once decided |

All servers use random ports locally or fixed port (`19432`) in remote mode.

**Stale-tab guard (`serverSession`).** Because a port can be reused (a fixed `PLANNOTATOR_PORT`, remote mode's `19432`, a rare random-port collision), a tab left open on an old session could post its decision to a NEW server on the same address and approve a document it never showed. Every plan, annotate and review server (Bun and Pi) therefore issues one random `serverSession` nonce per process (`packages/core/server-session.ts`, vendored to Pi) and advertises it on `/api/plan` and on every diff payload (`/api/diff` and the switch/PR endpoints, beside `approvalNotesSupported`). The client (`packages/ui/utils/serverSession.ts`) echoes it on every decision: `serverSession` in the body of plan `/api/approve` + `/api/deny`, annotate `/api/approve` + `/api/feedback`, review `/api/feedback` (the platform status post included), and as `?serverSession=` on `/api/exit` (whose body is empty). A server holding a DIFFERENT nonce answers `409 { code: "session_mismatch", error }` before it claims or settles anything, and the tab shows `ServerSessionReplacedBanner` ("This review was replaced — reload"). A decision WITHOUT the field is accepted, so an older client (and any host posting decisions by hand) keeps working; only a present, different nonce is refused. `/api/pr-action` (which posts the review to GitHub, GitLab or Bitbucket) carries the nonce in its body too and is guarded the same way in both runtimes: a mismatch posts nothing and the tab shows the same banner. So is annotate's `POST /api/source/save` (Edit Mode writing a file, single-file, folder and bundle sessions): the body carries `serverSession` and a mismatch writes nothing. So is `POST /api/open-in` on the annotate and review servers (both runtimes, after its same-origin check): a mismatch launches nothing. That route also requires an `appId` from the open-in catalog: a missing or unknown one is `400`, and there is no fallback to the OS default handler, which could run the file. Open-in is also off in a session published with `--tailscale` (Bun only: `exposed` on `handleOpenIn` / `handleOpenInApps`, from `tailnetPublished`), exactly as in remote mode: the apps list answers `{ available: false }` and a launch is `400`, since other devices reach the session (the update route's `update_exposed` rule). The same nonce guards the other routes that write files or start and stop processes, both runtimes: `POST /api/save-notes` on the plan and annotate servers (writes into an Obsidian vault, opens `bear://` / `octarine://`; body), `POST /api/plan/vscode-diff` (opens an editor; body), and the review server's agent jobs, `POST /api/agents/jobs` (body; `serverSession` is a known launch field) and `DELETE /api/agents/jobs[/:id]` (`?serverSession=`). The clients send it (`ExportModal`'s default notes wire, plan review's auto-save and quick save, `PlanDiffViewer`'s default VS Code wire, `useAgentJobs`; each a no-op for a `@plannotator/ui` host that never adopted a nonce). Each of these handlers also runs `isSameOriginOrNoOrigin` itself, so it is safe wherever it is mounted. `saveToObsidian` refuses a folder setting with a `..` segment (`obsidianFolderEscapesVault` in `packages/shared/integrations-common.ts`), so the note is always written inside the vault; the vault itself must already be an existing directory, as before, and is not restricted further (a custom path that is not a detected vault keeps working).

### Cross-origin write guard (every state-changing request)

Every plan, review, annotate and goal-setup server (archive and the servers OpenCode embeds included), Bun and Pi, refuses a `POST`, `PUT`, `PATCH` or `DELETE` that a page on another site sent, right after the Host allowlist and before any route: `403 { ok: false, error, code: "cross_origin" }` (`refuseCrossOriginWrite` in `packages/server/request-origin-guard.ts`, Pi mirror `apps/pi-extension/server/request-origin-guard.ts`, over the shared pure `isSameOriginOrNoOrigin` + `isStateChangingMethod` in `packages/shared/request-origin.ts`). A page on another site can send a preflight-free `text/plain` POST, and every JSON route parses its body whatever the content type, so before this a page that knew the port could reach every route that writes, decides or launches (plan approve without a nonce, review feedback, `/api/git-add`, `/api/pr-action`, Ask AI sessions, external annotations, agent jobs). The rule: refused when the browser marked the request `Sec-Fetch-Site: cross-site` or `same-site` (whatever Origin says, present, absent or matching: another localhost port is `same-site`), or when Origin is `null` or names another host; passed with no Origin and no such fetch metadata (agents' curl, the VS Code extension host, the Claude Code mod's `$.http.fetch`, the pull bridge and host control, which already require no Origin), with an Origin naming the request host, or with `Sec-Fetch-Site: same-origin` (the VS Code panel's cookie proxy, and a reverse proxy that rewrites Host when the page is served over HTTPS or from localhost). Browsers send `Sec-Fetch-Site` only to HTTPS and localhost origins: over plain HTTP to any other address there is none (measured in Chromium, Firefox and WebKit), so behind a plain-HTTP reverse proxy that rewrites Host (nginx's default `proxy_pass http://127.0.0.1:<port>` with no `proxy_set_header Host`) the page's Origin names the proxy and Host names the upstream, and nothing marks the request as the session's own. For that case an Origin whose hostname `PLANNOTATOR_ALLOWED_HOSTS` names EXPLICITLY (an exact entry or a `.suffix` entry) also passes, unless the browser sent fetch metadata (`isOriginNamedInAllowedHosts` in `packages/shared/request-host.ts`, the same allowlist parsing as the Host check; read on each request). `*` never widens it: a `*` that turned the Host check off does not turn this guard off. The route-level checks on `/api/save-notes`, `/api/plan/vscode-diff` and the agent jobs use the same helper (`isSameOriginRequest` in each adapter); the older per-route checks below use `isSameOriginOrNoOrigin` alone, as before, so those routes (config, review progress, guide share links, the CallDiff install, source save, open-in, update) still refuse a plain-HTTP Host-rewriting proxy, which they already did. GET, HEAD and OPTIONS are left to their routes, and so are WebSocket upgrades (GET; the agent terminal's carries a per-session token in its path). The per-route checks that predate it (config, review progress, guide share links, the CallDiff install, source save, open-in, update) stay. Not covered, by design: GET routes that start read-only work (`/api/semantic-diff`, `/api/call-flow`, `/api/agents/capabilities` and `/api/ai/capabilities?activate=` model discovery), which another site can trigger but not read or steer; the Inbox does not run this guard ahead of its routes (it has its own guards, see "Security" under "Plannotator Inbox"), but its window writes use `isSameOriginOrNoOrigin`, so the stricter rule (cross-site or same-site fetch metadata refused even without an Origin) applies there too, harmlessly, since its window is always same-origin; the live-app proxy (its own Host, Origin and WebSocket-origin checks). Tests: `packages/server/state-route-guards.scenarios.ts`, run by `packages/server/state-route-guards.test.ts` (Bun) and `apps/pi-extension/server/state-route-guards.test.ts` (Pi).

### Host allowlist (every request)

Every plan, review, annotate (archive and goal-setup included, and the servers OpenCode embeds) server, and the Plannotator Inbox (always the local rule: `createRequestHostGuard({ localOnly: true })`), checks the request's `Host` header BEFORE any route, in both runtimes: the app HTML, every API and every WebSocket upgrade. The rule is one pure predicate, `isAllowedRequestHost` in `packages/shared/request-host.ts` (vendored to Pi); the adapters are `packages/server/request-host-guard.ts` (Bun, first lines of each `fetch`) and `apps/pi-extension/server/request-host-guard.ts` (node:http, first line of each handler, plus an `upgrade` interception, because node:http hands an upgrade to every `upgrade` listener, such as the annotate agent terminal's). Why: `isSameOriginOrNoOrigin` compares Origin with Host, which cannot tell the session's own page from a page served under another DNS name that resolves to this machine (both carry matching Origin and Host), and most GETs had no check at all. IP literals and loopback names cannot be re-pointed by DNS, so the allowlist is built from them:

- **Every mode:** loopback names: `localhost`, `*.localhost`, `127.0.0.0/8` literals, `[::1]` (`isLoopbackHostname`).
- **Remote mode** (`PLANNOTATOR_REMOTE` / SSH, wide bind): also any IPv4 or IPv6 literal (LAN or container address), the configured urlHost (`auto` resolved through the same cached Tailscale lookup the advertised URL uses), and this machine's `os.hostname()` (full name, first label, and `<first label>.local`, the mDNS name another LAN device types, which `os.hostname()` omits on Linux and often on macOS; mDNS answers on the local link only, so it cannot be pointed here from outside the network). These names are resolved lazily, on the first request that is neither loopback nor an IP literal.
- **`--tailscale`** (local mode, Bun CLI only): `tailscale serve` forwards the browser's own Host (the MagicDNS name; for TCP backends it sets `r.Out.Host = r.In.Host`), so `enableTailscaleServe` registers the serve URL's hostname with `allowServedHostname` once serve reports it (not for the Inbox's persisted mapping, which points at a door-only listener that reads no Host).
- **Browser IDE port proxies** (every mode): code-server and Coder set `VSCODE_PROXY_URI`; when its HOSTNAME holds the `{{port}}` template (`https://{{port}}--main--ws--me.coder.example.com/`), the per-port hostname (`<digits>` in the template's place, nothing else) is allowed (`forwardedPortHostPatterns`). Such a proxy reaches the loopback-bound server and forwards its own Host. The value comes from the environment the IDE started and names the IDE's own proxy domain, never a request. A path-based template (`./proxy/{{port}}/`) adds nothing. GitHub Codespaces and VS Code dev tunnels need no rule: their forwarders present `Host: localhost:<port>` (the browser's name rides in `X-Forwarded-Host`, which is never read). No provider domain (`.app.github.dev`, `.gitpod.io`, `.devtunnels.ms`) is built in: the forwarders that matter present loopback, and a blanket suffix would admit every other tenant's forwarded hostname for no gain.
- **`PLANNOTATOR_ALLOWED_HOSTS`**: extra names (a `:port` on an entry is ignored), `.suffix` entries, or `*` (off). See the env table.
- **No Host header** (an HTTP/1.0 non-browser client): allowed; browsers always send one. A malformed Host is refused.
- **The port is never compared.** Forwarded ports legitimately arrive with another port (`ssh -L 8080:localhost:19432`, VS Code / devcontainer auto-forwarding to a loopback-bound server when the local port is taken, `docker -p`), and a foreign name is refused by its hostname alone. The VS Code cookie proxy rewrites Host to the upstream's `localhost:<port>`, a loopback name. The narrower loopback-AND-port checks of the pull bridge and host control stay as they were, behind this one.
- **Refusal:** `403`, `text/plain`, `X-Plannotator-Error: host_not_allowed`, a one-paragraph body naming the hostname (only when it parses as one) and `PLANNOTATOR_ALLOWED_HOSTS`; never a 404, so it cannot be mistaken for the app catch-all.

Not covered, by design: the Inbox's tailnet listener ("Over your tailnet": it answers only the served MagicDNS name and the owner's Tailscale login, and never hands on `/mcp` or a connection route), the live-app proxy (`live-proxy-core.ts` has its own Host, Origin and WebSocket-origin checks), the compiled build's agent-terminal Node sidecar (`agent-terminal-node-sidecar.mjs`: bound to `127.0.0.1` on a port only the Bun server learns, never sent to the browser, and served only under the session's random-token PTY path; the browser's upgrade reaches the guarded annotate server first), the paste service (a public service, not a session) and the guides.show local static dev server (serves build output only). Tests: `packages/shared/request-host.test.ts` (the predicate), `packages/server/request-host.scenarios.ts` run by `packages/server/request-host.test.ts` (Bun, plus goal setup and the tailnet name) and `apps/pi-extension/server/request-host.test.ts` (Pi), and `apps/pi-extension/server/request-host-guard.test.ts` (the upgrade interception).

### Inbox Server (`packages/server/inbox.ts`)

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/` | GET | The window (`htmlContent`, the embedded `inbox.html`), with its CSP |
| `/favicon.png` | GET | The window's icon (`handleFavicon`) |
| `/api/inbox/health` | GET | `{ ok, app: "plannotator-inbox", version, serverSession, pid, update, notify_reach, event_streams }`: liveness for the registry readers; `notify_reach` (additive): `{ enabled, windows, allowed, allowed_origins }`, whether a browser notification can reach the person now (see "Notifications"); `event_streams` (additive): event streams open now (the tabs of one origin share one, "One event stream per browser") |
| `/` | GET | The window. A browser navigation at `127.x.y.z:<port>` or `[::1]:<port>` answers `307` to `http://localhost:<port>/` (one origin for the notification permission; `inbox-canonical.ts`) |
| `/api/inbox/window` | POST | `{ serverSession?, window, permission, origin?, served_by? }`: a window reports its browser's notification permission for its own origin (`granted`, `default`, `denied`, `unsupported`); answers `{ notify_reach }`. `served_by` (additive): the window whose event stream this tab listens to (a follower, "One event stream per browser"); `null` or absent for a tab with its own. `{ window, gone: true }` (additive, no permission needed): the tab closed (its pagehide beacon, or the leader saw its lock freed); it stops counting at once. `422` a bad window id, permission or `served_by`. Same-origin guard; the window sends it without `serverSession`, so it reaches an Inbox that restarted under the tab (a `serverSession` that is sent and differs is still `409`). Sent on every event-stream `hello`. Not on the device door |
| `/api/inbox/threads` | GET | The list model, a row per thread: `{ serverSession, version, cursor, update, notice, projects: [{ ...project, threads, unread }], project, sections: [{ id, label, threads: [row] }] }`. All six sections, in order, empty ones included. A row is the thread summary (Workspaces' question counts `open`, `picked`, `stopped`, `holds_up`, `prompt`; `waiting_on_person`) plus `project: { id, name }`, `thread_name`, `section`, `unread`, `answered_not_sent`, `waiting_since`, `unseen`, `sent: { at, checked_at } \| null`. `?project=prj_…` keeps the sections and drops other projects' rows (`422` malformed, `404` unknown). `?archived=exclude` (the window) leaves archived threads (resolved, with no agent message after the archive) out of every section; the default `include` keeps them in Quiet (the phone, an older window); anything else `422`. A row also carries the additive `agent_after_archive` (an agent wrote after the archive line) and `back_from_archive` (that, and something there still waits: the thread is in the list, placed like an open one), and `delivery` (additive, approval "inbox-row-delivery"): where the person's latest sent item is, `{ kind: reply \| message \| ack, state: queued \| sending \| saved \| delivered \| undelivered, reason, send_now, message_id, at, host, name, another_session?, asking? } \| null` (`InboxRowDelivery`, `packages/core/inbox-delivery.ts`). It is decided by `inboxDeliveryState`, the same rule the thread's delivery line runs (`deliveryLine` delegates to it), from the store plus the live sessions the server hands the store (`InboxStore.setDeliveryPresence`: each session's `busy` / `send_now` while it polls, and `askerLive` with its 60 s grace), gathering the inputs the thread gathers (`InboxStore.rowDelivery`): a reply's or message's recipient session, `wakes`, `deliver_now_at`, its delivery or the agent's read, a `to` session that stopped before it took it (`undelivered`), the asking session ended (`reason: "ended"`, with `asking` naming that session's agent; which session asked is the thread's own rule, `inboxAskingMessage` with the default skip `inboxDefaultSkip`, which is always false since approval "inbox-explicit-skip", shared with `askingSessionOf` in Thread.tsx), a 👍's Undo window (`ack_pending`), settled note and delivery. Memory only, a few lookups per row; no git or network. `reason` names the case so a client words it as the thread does; `send_now` mirrors the thread's offer (the row never offers it). Null when an agent wrote last or a 👍 was not sent; absent from an older Inbox. The phone's door forwards it unchanged; an older phone app ignores it |
| `/api/inbox/cards` | GET | The Board's cards (approval "inbox-board"): `{ serverSession, cursor, cards: [InboxCardWire] }` in the Board's column order, the latest move first; `?project=prj_…` and `?column=building,your_review` filter (`422` a bad column, `404` an unknown project) |
| `/api/inbox/cards/:id` | POST | `{ serverSession?, op, column?, reason? }`: the person's move (`move` with any `column`, `icebox`, `drop` with an optional `reason`, `restore` back to where the card was); answers `{ card }`. Window guards; `404 card_not_found`, `422` a bad op or column |
| `/api/inbox/threads/archived` | GET | Settings' Archived block: `{ serverSession, cursor, project, projects: [{ id, name, archived }], total, offset, limit, threads: [row] }`, archived threads newest archived first. `?project=prj_…` filters (`projects` stays every project with archived threads); `?offset=` and `?limit=` (1 to 200, default 50) page; a bad value is `422` |
| `/api/inbox/projects` | GET | The sidebar's folders: `{ serverSession, cursor, projects: [{ id, key, name, root, created_at, threads, unread, listed, archived }] }` (`listed`: threads the window's list holds; `archived`: the rest; the list model's `projects` carry the same; additive) |
| `/api/inbox/projects/:id/read` | POST | The project menu's Mark all as read: `{ serverSession?, batch_id? }`; Mark read on every thread waiting on the person (each thread's set-aside note after the Undo window). Answers `{ project, batch: { read: [ids] }, threads: [row], replayed }`; a repeated `batch_id` answers the first answer (`replayed: true`), the same id on another project or action `409 batch_id_reused`. Same-origin and `serverSession` guards; `422` malformed id, `404 project_not_found`. Also on the phone door (contract 7.43) |
| `/api/inbox/projects/:id/unread` | POST | Its Undo: `{ serverSession?, threads: [ids] }`; `markRead(false)` for exactly those (one not this project's, or refused, is skipped). Answers `{ project, threads: [row], skipped }`. Also on the phone door (contract 7.44) |
| `/api/inbox/projects/:id/resolve` | POST | Archive all: `{ serverSession?, resolved: true, batch_id? }` resolves every listed open thread and marks read a thread that came back. Answers `{ project, batch: { resolved: [ids], read: [ids] }, threads, replayed }`. Undo: `{ resolved: false, threads: { resolved: [ids], read: [ids] } }`, answering `{ project, threads, skipped }`. Also on the phone door (contract 7.45) |
| `/api/inbox/threads/:id` | GET | `{ serverSession, cursor, thread }`: every message, each with its `questions` (Workspaces' `Question` wire plus `message_id`) and its `seq` (the first line's; with the root's `person_seen_seq` the window tells what is new before it records the look), a person's reply with `sent_annotations`, and the thread's `thread_name`; `row` (additive): the thread's list row, an archived thread's too; `thread.archive_seq` (additive): the archive line's seq, null for an open thread (a message whose `seq` is after it behaves as an open thread's) |
| `/api/inbox/threads/:id/seen` | POST | `{ serverSession?, through_seq? }`: the person looked at the thread; its agent messages so far leave "New since you looked". `through_seq` (optional, a whole number: the seq of the newest message the window showed) caps the look at the agent messages at or below it; at or behind the recorded look it writes nothing (a look never goes back), past the newest message it is the newest; anything else is `422 validation_error` (`field: "through_seq"`). Writes nothing when nothing is new. Returns `{ thread: row }` |
| `/api/inbox/threads/:id/read` | POST | `{ serverSession? }`: Mark read. The thread goes to Quiet without archiving; its questions still waiting on the person close unanswered (skips); counts as a look. After the Undo window the asking agents get one set-aside note. Same-origin and `serverSession` guards; `409 thread_resolved` on an archived thread. Returns `{ thread: row }` (`read_at` set) |
| `/api/inbox/threads/:id/unread` | POST | `{ serverSession? }`: Undo Mark read: reopens the questions that Mark read closed as they were (a saved pick included); an earlier Mark read's stay closed. Same guards. Returns `{ thread: row }` |
| `/api/inbox/messages/:id/ack` | POST | `{ serverSession?, ack? }`: 👍 Looks good on the thread's latest agent message plus Mark read, sent to the agent after the Undo window (a note delivered like a reply); `ack: false` takes both back. Same guards. Returns `{ message, thread: row }`; `422 ack_not_allowed`, `409 ack_stale` / `ack_after_reply` / `question_open` / `thread_resolved` (see "👍 Looks good") |
| `/api/inbox/messages/:id/actions/:key` | POST | `{ serverSession?, outcome: "done" \| "cant" \| null, note? }`: an action item's Done (an optional note) or Can't do it (a reason, required), sent to the agent as the person's reply once the Undo window passes; `null` inside the window is the Undo. Answers `{ questions }` (the message's questions and action items). `409 action_already_sent` / `action_closed`, `422 validation_error` (a question's key, a bad outcome, Can't do it without a reason). Window guards; on the device door (contract 7.63). See "Action items an agent needs you to go do" |
| `/api/inbox/threads/:id/sessions` | GET | New message: the live agent sessions of the thread's project, `{ home, project, sessions: [{ session, host, started_at, last_seen_at, busy, idle_since, wrote_thread }] }`, the thread's writers first (latest writer first), then by start. `?asker=<session>` adds `asker: { session, live, connection }`: whether the session that asked is still there, with a 60 s grace (see "Replying when the asking session has ended"), and `connection` (additive) `{ busy, idle_since, send_now }` while its connection polls, else null (the line under the person's message, see "Questions and Send"); each session also carries `send_now`. `?recipients=a,b` (additive) adds `recipients: { <session>: connection or null }`, the tagged sessions' lines |
| `/api/inbox/threads/:id/taggable` | GET | Who the person can tag with `@`: `{ serverSession, owner, sessions: [{ session, host, kind: "live" \| "mcp", name, project, started_at, last_at, busy, idle_since, taggable, owner, wrote_thread }] }`, the owner first, MCP agents last (see "Tagging agents in a reply or a comment"). Also on the device door (contract 7.60) |
| `/api/inbox/messages/:id/send-now` | POST | `{ serverSession?, session? }` (`session`: one tagged session's own line; absent, the owner): Send now. The person's reply or message goes to its session at once, into the running turn when one runs: `{ message }` with `deliver_now_at`, and the bridge command's `now: true`. `409 send_now_unavailable` (that session's connection does not poll now, or cannot deliver mid-turn), `409 already_delivered`, `422 not_addressed`. Window guards; on the device door (contract 7.58) |
| `/api/inbox/threads/:id/message` | POST | New message: `{ serverSession?, session, body, idempotency_key }` writes the person's words to that live session (`to` on the message); same-origin and `serverSession` guards; `409 session_not_live` when the session is not live (nothing written); a replayed key answers the message it wrote |
| `/api/inbox/sessions` | GET | Compose: every live session, `{ serverSession, home, projects: [{ project: { id \| null, name, root }, sessions: [{ session, host, started_at, last_seen_at, busy, idle_since, last_thread: { id, subject, at } \| null }] }] }`, the most recently active project first. `?session=<id>` adds `session: { session, live }` with the asker grace. Also on the phone door (contract 7.39) |
| `/api/inbox/messages` | POST | Compose: `{ serverSession?, to: { host?, session }, body, idempotency_key, uploads?: [upl_id], draft_id?, thread_name?, thread_name_auto? }` starts a thread the person writes (`thread_name`: the chip, checked by the thread-name rules, `422` otherwise; with `thread_name_auto: true` it is compose's suggestion, dropped instead of refused, and the agent may rename it), addressed to that live session (any project): `{ thread_id, message, project, replayed }`. `409 session_not_live` (nothing written), a replayed key answers the thread it wrote, `idempotency_key_reused` for another body; the uploads become attachments and `draft_id` is deleted. Also on the phone door (contract 7.40) |
| `/api/inbox/messages/:id/to` | POST | Send to another session: `{ serverSession?, to: { host?, session } }` re-addresses a person message no session took yet to a live session of its thread's project: `{ message, row }`; `409 session_not_live`, `409 already_delivered`, `422 not_addressed`. Also on the phone door (contract 7.41) |
| `/api/inbox/drafts` | GET | `{ serverSession, drafts: [draft + status], replies }`, newest saved first; `status` `live`, `ended` or `none`; `replies` (additive): open threads holding unsent work (list rows plus `reply_preview`), the most recently drafted first |
| `/api/inbox/threads/:id/draft` | GET | `{ serverSession, draft }`: the reply box's words kept for the thread (`{ v, thread_id, body, created_at, updated_at }`) or null; another site's read `403`. Also on the phone door (contract 7.62), read only |
| `/api/inbox/threads/:id/draft` | POST | `{ serverSession?, body, base, base_body? }`: save the reply draft (compare-and-set on `updated_at`: `409 draft_conflict` with the newer draft; `base_body`, the words this window saved last, is accepted in place of a stale `base` while the draft still holds them); an empty body deletes it; `{ draft }`. Sends `event: drafts` to every window |
| `/api/inbox/threads/:id/draft/delete` | POST | `{ serverSession? }`: Discard; `{ ok, deleted }` |
| `/api/inbox/drafts/:id` | POST | `{ serverSession?, body, to, project, files: [upl_id], base }` creates (`base` null) or replaces a draft; compare-and-set on `updated_at` (`409 draft_conflict` with the newer `draft`); `404 upload_not_found` for a file no longer here: `{ draft }` |
| `/api/inbox/drafts/:id/delete` | POST | `{ serverSession? }`: `{ ok, deleted }` |
| `/api/inbox/uploads` | POST | `?name=<file name>&serverSession=<s>`, the raw bytes as the body: `{ upload: { upload_id, name, size, kind, sha256, created_at, media_type?, width?, height? } }`; `422 upload_refused` (dotenv family, a path separator, a control character, over 255 bytes), `413 upload_too_large` (over 100 MB). Also on the phone door (contract 7.48, `?idempotency_key=`; never through the relay) |
| `/api/inbox/events` | GET (SSE) | `event: record` per store line (`id:` = seq) after `Last-Event-ID` / `?cursor=` (a usable header, a non-negative whole number, wins, so a reconnect resumes where it was; else the cursor; replay first, then live), `event: status` for restart-to-update, `event: reach` (`notify_reach`) when the open windows change, only on a stream with `window=`, `event: deliveries` (empty data) when the live sessions moved in a way a row's `delivery` reads (a turn started or ended, a session stopped polling, an asker grace ran out; compared every second while a window listens), also only with `window=`, `event: drafts` (`{ thread_id }`) when a reply draft is saved or deleted, windows only too, a heartbeat every 15 s. A window adds `window=<id>&permission=…&origin=…` and is counted while its stream is open. `once=1` (additive): the hello and the replay after the cursor, then the response ends (a follower tab's catch-up; not counted as a stream) |
| `/api/inbox/messages/:id/picks` | POST | Save picks at once: `{ serverSession?, questions: [{ key, revision, answer or null }] }`; a superseded question answers `422 question_superseded` |
| `/api/inbox/messages/:id/reply` | POST | The person's Send: `{ serverSession?, idempotency_key, words?, questions?: [{ message_id?, key, revision, answer? }], skip?: [key | { message_id?, key }], feedback?, annotation_ids?, to?: { host?, session }, uploads?: [upl_id] }` (the annotations' feedback text is appended after the answers; the named annotations are marked sent; `uploads`, files pasted into the reply box, become the reply's `attachments` as compose's do, `404 upload_not_found` for one that is gone, and a replayed key copies nothing; a reply of files alone is a reply; `to` sends the reply to another live session of the project because the one that asked has ended, `409 session_not_live` and nothing written when it is not live; `skip`, the questions the person chose to skip with "Skip them" (only those, while still open, as skips `by_reply`; a Send never skips on its own, and `skip_unanswered` is ignored; approval "inbox-explicit-skip"); a pick or skip on another message of the same thread and session names it with `message_id`, so one Send to one session is one reply (`422 validation_error` for another session's or thread's message); `tags: [{ host?, session, label? }]`, the agent sessions the person tagged with `@`, each handed the reply too, `409 tag_needs_update` for a live session on an older Plannotator, `409 tag_host_mismatch` for a session known under another host, and `409 session_not_live` for one neither live nor a known MCP agent, nothing written: see "Tagging agents in a reply or a comment"; `clear_draft: "<updated_at>"`, the reply carries the reply box's words: the thread's reply draft is deleted with it only while it is still the draft those words were saved as (a compare-and-set, so another window's newer draft stays; anything else, `true` included, clears nothing)) returns `{ reply, questions, replayed }`; naming a superseded question is `422 question_superseded`, one a Mark read closed `409 question_set_aside`, and nothing is written. With only a `skip` list whose questions all closed meanwhile it answers `{ reply: null, nothing_to_send: true }`: a no-op, not an error |
| `/api/inbox/messages/:id/reask` | POST | Re-ask (approval "inbox-reask"): `{ serverSession?, idempotency_key, to?: { host?, session } }` writes the person's note asking the session that wrote this message for its open questions in the thread again, in one message (`reask` on the note; its unsent picks go with it as answers), and answers `{ message_id, questions, reply, replayed }`. `409 nothing_to_reask`, `422 validation_error` (a person's message, no key), `409 thread_resolved`, `409 session_not_live` for a `to` that is not live; a replay answers the note. Also on the phone's door (contract 7.61) |
| `/api/inbox/messages/:id/guide` | GET | The guided review a message carries: `{ message_id, guide, snapshot }` (the snapshot as validated and stored); `404 guide_not_found` when it carries none |
| `/api/inbox/messages/:id/annotations` | POST | `{ serverSession?, annotation }`: a comment on the text of an agent's message (Plannotator's text-selection annotation, `type: "COMMENT"`, `originalText` the words selected), new or edited (same id); kept in `annotations.jsonl` with `message: { at }`, `path` the message id, and answered `{ annotation: record }`; same-origin and `serverSession` guards; `422 annotation_not_allowed` on the person's own message, `422` not a comment or an id used elsewhere, `404 message_not_found`, `409` sent or removed, or a message an archive closed. Removed through `/api/inbox/annotations/:id/remove`. Also on the phone door (contract 7.59) |
| `/api/inbox/messages/:id/guide/annotations` | POST | `{ serverSession?, annotation }`: a comment on that guide's diff (the review app's `CodeAnnotation`: `id`, `filePath` in the guide's patch, `side` `old`/`new`, `lineStart`/`lineEnd`, `text`), new or edited (same id); kept in `annotations.jsonl` with `guide` set and answered `{ annotation: record }`; same-origin and `serverSession` guards; `422` a file not in the patch, a bad side, lines not in one hunk of the file's patch, or an id used elsewhere, `404 guide_not_found` / `message_not_found`, `409` sent or removed, or a resolved thread. Removed through `/api/inbox/annotations/:id/remove`. Also on the phone door (contract 7.53) |
| `/api/inbox/messages/:id/guide/reviewed` | POST | `{ serverSession?, reviewed: boolean[] }`: the person's reviewed ticks on that guide, kept on the message (`guide_reviewed`); same-origin and `serverSession` guards; `422` not a list of booleans, `404` no such message or no guide |
| `/api/inbox/messages/:id/resolve` | POST | `{ serverSession?, resolved? }`: resolve or reopen the thread (the window's Archive and Unarchive) |
| `/api/inbox/agents` | GET | Local only (`403 local_only` through the tailnet). The agents on this computer (additive `sessions`: the open sessions per Plannotator host and which need a restart, see "A session that needs a restart after an update"): `{ agents: [{ id, label, detected, reach: { kind, on, state, path, locked, reason }, tool: { on, locked, chosen_off?, mod_off? } \| null, reminder: { on, locked, needs_tool } \| null, note: { agent, path, target, state, create, created, reason } \| null, plugin: { installed, disabled?, generation? } \| null }], records, last_report, connecting, connect_env_off, tool_env, notes_offered, notes_asked, note_text }` (`InboxAgentsModel` in `packages/core/inbox-types.ts`; `notes_asked`: the agents the note dialog was asked about; for Claude Code, Pi and OpenCode, `plugin` says whether Plannotator's own plugin or extension is installed, `disabled` a Claude Code plugin turned off by name (`claude plugin disable`; the strongest settings scope that names it decides, managed settings first, and `managed` says they did), `generation` the OpenCode version from evidence (the global config's `plugins` / `plugin` shape, else `opencode2` on PATH is 2 and `opencode` alone is 1), and `tool.mod_off` that the Claude Code mod is off (`PLANNOTATOR_CLAUDE_MOD` from Claude Code's settings `env`, else the Inbox's environment, then `claudeCodeMod`), so Claude Code has no Inbox tool, no reminder, and Settings → Agents shows why in place of a switch; a Claude Code whose plugin gives it no tool (not installed, disabled, mod off) and whose `.claude.json` (`$CLAUDE_CONFIG_DIR` or `~`, read up to 32 MiB) holds a `plannotator-inbox` MCP entry reads `reach.kind: "mcp"`, on. The first-run screen never offers a plugin disabled or a mod turned off, and says "No agent reaches the Inbox yet" (never "All set") when agents were found and none reaches it. Turning Pi's or OpenCode's tool on first removes the MCP entry Plannotator recorded adding for it (the tool stays off when it cannot), and a person's `plannotator inbox` run does the same once the plugin's tool is on) |
| `/api/inbox/agents` | POST | `{ serverSession?, agent, reach?, reminder?, note? }`: Settings → Agents' switches; answers the model plus `error` (a refusal: the env var decides, a file can't be written). Same-origin and `serverSession` guards, local only |
| `/api/inbox/agents/notes` | POST | `{ serverSession?, add: [ids], asked?: [ids], seen?: boolean }`: the note dialog's answer; adds the ticked notes (`results`), records each agent in `asked` as asked (except one whose add failed; without `asked`, the current candidates plus `add`), and with `seen` marks the last run's report seen (`[]` for Not now) |
| `/api/inbox/agents/seen` | POST | `{ serverSession? }`: the last run's report is seen (kept for an older window; the dialog sends `seen` with its answer) |
| `/api/inbox/control/connect` | POST | Connection route (the registry token, loopback Host, no Origin): `plannotator inbox` with an Inbox already running; connects the agents on this computer, answers `{ connect: report }` |
| `/api/inbox/settings` | GET | What Settings and the connect snippets read: `{ serverSession, tailscale: { on, source, env, url, error, owner, allowed, exposed }, via: "local" \| "tailnet", version, port, url, mcp_url, mcp_command, home, data_dir, inbox_tool: { hosts: { claude-code, pi, opencode }, env }, notifications: { enabled, dismissed, allowed_origin }, notify_reach, sound: { enabled, volume, dialog_shown_for, dialog_due }, updates: { update_check: { on, env }, auto_update: { on, env } }, theme: { mode?, light?, dark? } \| null, text_size: 12 \| 13 \| 14 \| 15, store: { dir, bytes, projects: [{ id, name, root, bytes, threads: [{ thread_id, subject, bytes }] }] } }` |
| `/api/inbox/settings` | POST | `{ serverSession?, inbox_tool?: { <host>: boolean }, notifications?: { enabled?, dismissed?, allowed_origin? }, sound?: { enabled?, volume? }, tailscale?: { on: boolean, replace_exposed?: boolean }, theme?: { mode?, light?, dark? }, text_size?: 12 \| 13 \| 14 \| 15, update_check?: boolean, auto_update?: boolean }` (one required; the update switches write `updateCheck` / `autoUpdate`, answer `updates`, and never come through the tailnet; every part is validated first and the tailnet change runs before the others, so a refusal saves nothing): saves `inboxTool` per host (the hosts not named keep their value), `inboxNotifications`, `inboxSound`, `theme` (merged, so a mode change keeps the palettes; `mode` light/dark/system, palettes as ids), `inboxTextSize` (`422 validation_error` for anything but 12, 13, 14 or 15) and/or `inboxTailscale` (applied at once: published or taken down) into config.json, and answers `{ inbox_tool, notifications, sound, tailscale, updates, theme, text_size }`; same-origin and `serverSession` guards; `500 config_not_saved` when the file did not change; `409 tailscale_env_decides` while `PLANNOTATOR_INBOX_TAILSCALE` is set; `409 tailscale_unavailable` when the take-down failed; `403 local_only` for `tailscale.on: true` through the tailnet |
| `/api/inbox/sound/dialog` | POST | `{ serverSession? }`: the page asks to show the one-time sound dialog. A compare-and-set from `inboxSound.dialogDueFor` to `dialogShownFor`: `{ show: true, sound }` only while the dialog is due (`sound.dialog_due`) and the page is on this computer; every later ask (another tab, a reload, a later start) gets `show: false`. Through the tailnet always `show: false`, nothing written. Same-origin and `serverSession` guards |
| `/api/inbox/restart` | POST | `{ serverSession? }`: the window's Restart. Stops listening and calls `onRestartRequested` (the command starts the binary on disk); `409 restart_unavailable` without one. Same-origin and `serverSession` guards |
| `/api/inbox/update` | GET | The update dialogs and Settings → About: `{ update, current, updated, latest, check: { on, env, last_attempt_at, error }, auto_update: { on, env, supported }, summary, flags, command, plugin_command, sessions, failure, log, snoozed_until }` |
| `/api/inbox/update` | POST | `{ serverSession? }`: Update now (the install script for the newest known release, detached, once: `409 update_locked` while one runs; `409 update_unmanaged` / `update_dev_build` / `update_no_release` / `update_up_to_date` otherwise). Same-origin and `serverSession` guards; never through the tailnet |
| `/api/inbox/update/snooze` | POST | `{ serverSession? }`: Remind me tomorrow for the version shown (24 h, server-side) |
| `/api/inbox/update/check` | POST | `{ serverSession? }`: Check now, a forced release check; answers the GET model plus `checked: { ok, error? }` |
| `/api/inbox/whats-new` | GET | `?version=X`: `{ version, current, since, published_at, release_url, notes, skipped: [{ version, text }], images }` from `update-notes/` (`since`, additive: the version `skipped` counts from, the one run before the update for a release this Inbox already runs, else `current`; null for a development build); `404 notes_not_found`; `images` (additive): the notes' image srcs saved on this computer. Local only, like every update route (`403 local_only` through the tailnet) |
| `/api/inbox/whats-new/image` | GET / HEAD | `?version=X&src=<as the notes write it>`: a stored copy of an image the release's saved notes still show (see "Images in the notes" under the update control); never fetches. Sniffed `Content-Type`, nosniff, CSP `sandbox; default-src 'none'; style-src 'unsafe-inline'`, CORP same-origin, `ETag` (the sha256 its file is named by, checked against the bytes; `304`), `private, no-cache`, `X-Image-Width`/`-Height`. `403 cross_origin` for `Sec-Fetch-Site` cross-site or same-site, `404 image_not_referenced` / `image_not_stored`, `422` a bad version or src, `405`. Local only like the page (`403 local_only` through the tailnet); not on the device door |
| `/api/inbox/bridge/poll` | POST | Connection route (token, loopback Host, no Origin): `{ session, host?, waitMs? }` returns `{ commands: [{ type: "reply", id, thread_id, reply_to, subject, body, url }] }`, the person's replies waiting for that agent session; held up to 25 s when there are none |
| `/api/inbox/bridge/event` | POST | Connection route: `{ session, host, type: "delivered", id }` records that the reply or New message reached the session as a turn (`delivery` on it, the thread read by the agent; `422` for another session's); `{ session, host, type: "state", busy }` reports a turn starting or ending, for New message's live sessions |
| `/api/inbox/control/stop` | POST | Connection route: the bearer token from `inbox.json`, a loopback Host with this port, no Origin. Stops the Inbox (uninstall --purge) |
| `/api/inbox/control/tailscale` | POST | Connection route, same guards: `plannotator inbox --tailscale` against a running Inbox. Publishes over the tailnet for this run and answers `{ tailscale: { on, source, env, url, error, owner, allowed } }` (an older Inbox answers 404) |
| `/mcp` | POST | MCP, stateless; any Origin refused |
| `/api/inbox/search` | GET | Search (see "Search"): `q`, `project=prj_…`, `status=waiting\|new\|sent\|quiet\|archived`, `from=agent\|me`, `group=` + `offset=` + `limit` (at most 50), `current=prj_…` (a tie boost). Answers `{ serverSession, q, terms, took_ms, indexing, threads, totals, groups, recent, recent_searches? }`; `indexing: true` with no groups while the index builds (ask again); `422` a bad parameter, `404` an unknown project. Read only. Also on the phone door (contract 7.42) |
| `/api/inbox/search/recent` | POST | `{ serverSession?, q }` remembers a search the person opened a result from, or `{ clear: true }`; answers `{ recent_searches }` (the last 6, newest first). Same-origin and `serverSession` guards |
| `/api/inbox/skills` | GET | The composers' skill picker: `{ skills: [{ name, root, description?, humanOnly, dir }] }`, the global skill folders only (plan review's `/api/skills`), read fresh. Read route; another site `403 cross_origin`; on the device door (contract 7.46) |
| `/api/inbox/skills/content` | GET | `?name=`: one skill's SKILL.md for the block a Send pastes in, `{ skill: { name, dir, path, content, truncated, humanOnly } }` (plan review's `/api/skills/content`: matched against discovered skills, never a path, `404` otherwise; 20,000-character cap). Same guards; on the device door (contract 7.47) |
| `/api/inbox/threads/:id/attachments` | GET | `{ serverSession, attachments: [state], annotations }`: each attachment record with `message_id`, `current: { sha256, size, mtime } \| null`, `changed_since_sent`, `unavailable: { code, message } \| null`, and the thread's annotations waiting for a Send |
| `/api/inbox/attachments/:id` | GET | The current file's bytes by id (`?version=sent`: the sent blob), text kinds only (`415 attachment_not_text` for image, pdf, file and unknown kinds), always `text/plain`, CSP `sandbox`. `404 attachment_not_found` / `attachment_missing`, `409 attachment_changed_type`. No route takes a path |
| `/api/inbox/attachments/:id/image` | GET | An image attachment's bytes (`?version=sent`: the sent blob) for `<img src>`: `Content-Type` sniffed from the bytes served, CSP `sandbox; default-src 'none'; style-src 'unsafe-inline'`, nosniff, CORP same-origin, `ETag` (sha256, `304`), `X-Image-Width/Height`. `415 attachment_not_image` for another kind or bytes that are no longer an image; cross-site `403` |
| `/api/inbox/attachments/:id/video` | GET | A video attachment's bytes (`?version=sent`: the sent blob) for `<video src>` and a phone's player, by HTTP Range: `Accept-Ranges: bytes`; one range `206` with `Content-Range` (at most 8 MiB: a longer or open-ended range gets its first 8 MiB, and the client asks again), none or several the full `200`, past the end `416` (`bytes */size`), an `If-Range` other than this version's `ETag` the full `200`; `ETag` `"<sent_sha256>"` or the current file's stat tag; `Content-Type` sniffed (`video/mp4`, `video/quicktime`, `video/webm`), `inline`, the message-images CSP, nosniff, CORP same-origin, `private, no-cache`. `415 attachment_not_video` for another kind; `405` for anything but GET; cross-site `403` |
| `/api/inbox/attachments/:id/download` | GET / HEAD | Any kind's bytes as a download, streamed: `Content-Disposition: attachment; filename=…; filename*=UTF-8''…`, `application/pdf` for a PDF else `application/octet-stream`, CSP `sandbox`, nosniff, CORP same-origin, `no-store`; the same Range, `If-Range`, `Accept-Ranges` and `ETag` as `video`; cross-site `403` |
| `/api/inbox/attachments/:id/page` | GET | An attached HTML page in a tab of its own ("Open in" → Browser): now, a `303` to its own folder's asset URL (`/api/html-assets/<token>/<name>`); `?version=sent` (or a hidden name, or a page over 2 MB), the bytes with a `<base href>` at the folder; both under `sandbox allow-scripts allow-modals; connect-src 'none'`. `415 attachment_not_html`, `404 attachment_missing`, cross-site `403`. Not on the device door |
| `/api/inbox/attachments/:id/linked-page` | GET | `?path=<relative path>`: another page an attached HTML page links to, not attached itself, for the pane's read-only view: `{ serverSession, path, name, html, url }` (`html` with a `<base href>` at its own folder's asset route, `url` its asset URL for Open in new tab). Only inside the attached page's folder by realpath, and the opened descriptor must still be the file that realpath names (on Linux the descriptor's own path, `/proc/self/fd/N`; elsewhere the same dev and ino by lstat on both sides of a second realpath: a parent folder swapped for a symlink in between is refused) (`403 linked_page_outside`), no hidden segment or dotenv name as requested or by where it leads (`403 linked_page_refused`), `.html`/`.htm` (`415 linked_page_not_html`), a regular file (`404 linked_page_missing`), at most 2 MB (`413 linked_page_too_large`); `422 validation_error` for an absolute or empty path, `415 attachment_not_html` when the attachment is not a page, cross-site `403`, GET only. Read only (the owner over the tailnet too). Not on the device door |
| `/api/inbox/open-in` | POST | `{ serverSession?, attachment_id, app_id }`: open the file as it is now in a catalog editor, the file manager (`reveal`) or the OS default (`default`), as the per-kind policy allows (`inboxOpenInPolicy`); answers `{ ok, error? }`. Never a path. `403 local_only` through the tailnet, `403 cross_origin`, `409 session_mismatch`, `422 validation_error` / `open_not_allowed` / `app_not_available`, `404 attachment_not_found` / `attachment_missing`, `409 attachment_changed_type`. Not on the device door |
| `/api/inbox/open-in/apps` | GET | `{ available: true, platform, apps }`: the file manager and the editors installed here (never terminals). `403 local_only` through the tailnet. Not on the device door |
| `/api/inbox/markups` | POST | The person's marked-up image (the raw PNG, JPEG or WebP body; `?serverSession=`; same-origin): kept as `inbox/markups/<sha256>.<ext>`, answers `{ path, name, url }`; `422` when the body is not one of those images; `413 markup_too_large` past the request bound, 128 MiB (`INBOX_MARKUP_MAX_BYTES`, declared or counted as it is read, never buffered past it; the phone door's own bound is 32 MB, `INBOX_DEVICE_MARKUP_MAX_BYTES`). Also on the phone door (contract 7.49, `?idempotency_key=`; never through the relay) |
| `/api/inbox/markups/:name` | GET | A marked-up image by its file name only, with the image headers above |
| `/api/inbox/messages/:id/image` | GET | `?path=<src as written>`: an image the message's body shows, read from wherever it is on this computer for an agent's message and from its project for the person's own (see "Images in a message"); sniffed `Content-Type`, nosniff, sandbox CSP, same-origin CORP, `X-Image-Width`/`-Height`, `ETag` (sha256 of the bytes served, `304` on `If-None-Match`), `Cache-Control: private, no-cache`. Also on the phone door (`messages/:id/image`). `403 image_not_referenced` / `image_hidden` / `outside_project` (a person's message only) / `image_unreadable` / `cross_origin`, `500 image_read_failed`, `404 message_not_found` / `image_missing`, `405`, `409 image_changed`, `413 image_too_large`, `415 not_an_image`. Through the tailnet listener ("Over your tailnet") it answers the owner's same-origin page like every read route; another site is refused there first (`403 cross_site`), and the route's own `cross_origin` refusal still holds on the window's port |
| `/api/inbox/attachments/:id/view` | GET | `{ attachment, version, text, html }`: one version's text (`version` is `current` or the sent sha256, the annotations' key); for HTML, `html` is the page with its `<base href>` at its folder's asset route |
| `/api/html-assets/<token>/<path>` | GET | Annotate's asset route (`resolveHtmlAssetRoute`) for the folder of an attached HTML page |
| `/api/inbox/annotations` | POST | `{ serverSession?, attachment_id, version, annotation }`: save a new annotation or edit one still waiting (`409 annotation_closed` once sent or removed) |
| `/api/inbox/annotations/:id/remove` | POST | `{ serverSession? }`: remove one still waiting |
| `/api/inbox/threads/:id/delete` | POST | `{ serverSession? }`: delete the thread and the blobs no other record uses; returns `{ ok, store }` |
| `/api/inbox/projects/:id/delete` | POST | `{ serverSession? }`: delete the project's folder and its unused blobs; returns `{ ok, store }` |
| `/api/inbox/pairing` | POST | `{ serverSession? }`: open the one pairing offer, `201 { offer: { code, expires_at }, link, computer: { name }, addresses: { tailnet, lan, fingerprint }, reachable }` (mobile contract 7.1; `reachable`: the code carries an address a phone can use, which the window gates on; the server still answers without one, for loopback tests and the simulator) |
| `/api/inbox/pairing` | GET | The last offer as the window reads it, never its secret or code: `{ offer: { expires_at, state: open \| expired \| closed \| redeemed, tries_left, attempts: [{ via: wifi \| tailnet \| local, result: wrong_code \| code_over_wifi \| old_code \| expired \| redeemed, at, tries_left?, device? }] } \| null }` (at most 20 attempts, kept until the next offer). Phones only; `local_only` through the tailnet; another site's read (`Sec-Fetch-Site` cross-site or same-site, or a foreign Origin) is `403 cross_origin` |
| `/api/inbox/pairing/checks` | GET | Step 1 of Pair a phone, read only (`packages/server/inbox-pairing-checks.ts`): `{ checks: { wifi: { address, network, openssl, certificate, bonjour, firewall: off \| on \| block_all \| unknown }, tailscale: { state: running \| stopped \| signed_out \| needs_approval \| starting \| cli_missing \| no_answer \| unknown, login, https_certs, port_free, error } }, lan, tailnet }` (`cli_missing`: no `tailscale` command on PATH, as with the Tailscale app before its command-line tool is turned on in its Settings, Install CLI; `no_answer`: it did not answer in time; `firewall` is the macOS application firewall only, `unknown` elsewhere). Turns nothing on, makes no certificate (`openssl` is looked up on PATH, never run), runs `tailscale status --json --peers=false` (never the tailnet's other devices) and `serve status --json`, `ipconfig getsummary` (macOS) or `iwgetid -r` (Linux) for the Wi-Fi's name, and `socketfilterfw` (macOS) for the firewall. Every probe is a child process in a process group of its own with its own time limit (`runQuietly`: at the limit the whole group is killed and the answer settles at once, so a shell wrapper such as the Mac app's `/usr/local/bin/tailscale`, whose real program keeps the pipes open, cannot hold it), side by side, under a whole-read deadline (`PAIRING_CHECKS_DEADLINE_MS`, 15 s: a probe past it reads as not answering), so the Inbox's event loop never waits on them; one read in flight is shared (never past its deadline) and its answer kept 3 s (`PAIRING_CHECKS_FRESH_MS`); `?fresh=1` (Check again, after a switch) skips the kept answer but joins a read in flight; a switch change drops it. Every probe is a seam (`startInboxServer`'s `pairingProbes`, the `tailscale` runner, and `createInboxDevices`' `checksTailscale`). Phones only; the same guards as the GET above |
| `/api/inbox/devices` | GET | `{ devices: [{ id, name, platform, created_at, last_seen_at, revoked_at, carriage }] }`: the paired phones not revoked, newest first |
| `/api/inbox/devices/:id/revoke` | POST | `{ serverSession? }`: remove a phone, `{ device }`; `404 device_not_found` |
| `/api/inbox/tailnet` | GET / POST | `{ tailnet: { on, address, error } }`; POST `{ serverSession?, on }` switches "Reach from my tailnet" (`409 tailnet_port_taken`, `409 tailnet_unavailable`) |
| `/api/inbox/lan` | GET / POST | `{ lan: { on, address, fingerprint, bonjour, error } }`; POST `{ serverSession?, on }` switches "Reach from this Wi-Fi" (`409 lan_unavailable` when `openssl` cannot make the certificate) |
| `/api/inbox/device/*` | GET / POST | The phone door: `pair` (no token), `revoke`, and the allowlist mapped onto the routes above (see "Phones" and `adr/implementation/inbox-mobile.md` section 2) |

### Host session control

`GET /api/host/status` and `POST /api/host/close` (`packages/shared/host-control.ts`,
vendored to Pi; Bun adapter `packages/server/host-control.ts`, Pi adapter
`apps/pi-extension/server/host-control.ts`) let the agent session that launched a
review ask what it holds and close it. Guarded exactly like the pull bridge: a
loopback Host naming the server's port (`403`), no `Origin` (`403`), and
`Authorization: Bearer <token>` (`401`), the launch's `PLANNOTATOR_SESSION_BRIDGE_TOKEN`
(Bun default; servers also take `hostControlToken`). Without a token the paths answer
`404 { error: "Not found", code: "host_control_disabled" }` (`HOST_CONTROL_DISABLED_CODE`),
which a host reads as "turned off" rather than "an older Plannotator" (an uncoded `404`);
they are off in remote mode, and
`--tailscale` discards the env token. Unlike the pull bridge they still answer under
`PLANNOTATOR_AI=disabled` (closing a review is not an AI feature). Once a session is
decided (a host close included), the review servers refuse a late `/api/feedback` or
`/api/exit` with `409` (both runtimes, like annotate), so a tab still open after the
close neither deletes the kept draft nor gets an ok for feedback nobody receives.
Close settles the decision as `exit` with
`closedBy: "agent"` and `unsentAnnotations` (no draft delete, no feedback-archive
record: the reviewer decided nothing), broadcasts `{ type: "session-closed", by:
"agent", unsentAnnotations }` on the external-annotation stream (`broadcast` on both
runtimes' handlers; `useExternalAnnotations`'s `onSessionClosed`), and the CLI's
host result record carries the same `closedBy` / `unsentAnnotations` on its
`dismissed` record. Every server result also exposes `hostControl` (`status()`,
`close?()`) for hosts that run the server in-process (Pi, the OpenCode 2 embedded
plan server). Plan servers implement status only. A host that calls the endpoints
over HTTP reads the answers with `classifyHostCloseAnswer` / `readHostStatusAnswer`
from the same shared module (the OpenCode 2 tool); the Claude Code mod keeps its own
copy of that rule because a hooks module imports only its own folder.

### Paste Service (`apps/paste-service/`)

| Endpoint              | Method | Purpose                                    |
| --------------------- | ------ | ------------------------------------------ |
| `/api/paste`          | POST   | Store compressed plan data, returns `{ id }` |
| `/api/paste/:id`      | GET    | Retrieve stored compressed data            |

Runs as a separate service on port `19433` (self-hosted) or as a Cloudflare Worker (hosted).

## Plan Version History

Every plan is automatically saved to `~/.plannotator/history/{project}/{slug}/` on arrival, before the user sees the UI. Versions are numbered sequentially (`001.md`, `002.md`, etc.). The history slug is `{sanitized-heading}-YYYY-MM-DD`, scoped by project name (git repo or cwd), and is resolved by `resolveHistorySlug()` (`packages/shared/storage.ts`) so that the date names the day the chain STARTED, not today (#1679): an open server keeps its own slug for revisions whose heading is unchanged (`updatePlan`, Pi's and the Claude Code mod's); otherwise today's `{heading}-{UTC date}` directory is used if it already holds versions; otherwise the most recently written existing `{heading}-YYYY-MM-DD` directory of the project that is not dated after today is continued when its newest version file's mtime is within `PLAN_HISTORY_CONTINUE_WINDOW_MS` (48h); otherwise today's directory starts a new chain. So a plan revised across midnight (UTC or local) or resumed the next day keeps its version diff, every revision refreshes the window, and a same-heading plan after two quiet days starts fresh. Nothing on disk is renamed or migrated. Both plan servers (Bun and Pi) use it. The decision snapshots in `~/.plannotator/plans/` are named separately by `generateSlug()` (heading + the UTC date the plan arrived at the server, or of its latest in-session revision, unchanged), because `parseArchiveFilename` / `listArchivedPlans` read that date back; the feedback archive's `target.slug` names the history directory, matching its `planVersionFile`. Identical resubmissions are deduplicated (no new file if content matches the latest version).

This powers the version history API (`/api/plan/version`, `/api/plan/versions`) and the plan diff system.

**Annotate mode** also saves history on open, so the same version diff works when annotating a standalone `.md`/`.txt`/`.html` file (or any other supported plain-text file, e.g. `.yaml`/`.json`/`.toml`). It keys the slug by **file path** — `annotate-{sanitized-basename}-{hash8}` — rather than heading + date, so re-opening the same file groups its versions even as its content (and headings) change. **Note this writes a copy of each annotated file's content** under `~/.plannotator/history/` (or `PLANNOTATOR_DATA_DIR`); disable via `PLANNOTATOR_ANNOTATE_HISTORY=0` or `{ "annotateHistory": false }` in `~/.plannotator/config.json` to keep annotate sessions stateless (the version diff is then unavailable, and the durable submitted-feedback records described in the env-var table are also skipped). Single-local-file annotate sessions additionally write each submitted decision to `history/{project}/{slug}/submissions/{timestamp}.md` BEFORE deleting the annotation draft, so feedback survives an agent-side timeout (#678); a failed record write keeps the draft as the recovery copy. For `--render-html` files the diff is rendered as the real page with inline `<ins>`/`<del>` highlights via `htmlDiff()` (`packages/shared/html-diff.ts`).

**Live versions (#2037).** An open single-file Markdown/text annotate session already reloads the text in place when the file changes on disk (the editor's source-document reconcile over `/api/reference/files/stream`). That reload now also becomes a version, so the `+N/-M` badge and the Version Browser show an agent's edit in the same session instead of only after a reopen. When the session's OWN file's disk text lands on screen (`noteRootDiskText` in App: the watcher reconcile's `clean-updated`, "Reload from disk" after a conflict, and a save that found the file changed and reloaded it; linked and folder documents are not covered), and `/api/plan` advertised `liveVersions`, `useLiveAnnotateVersion` (`packages/editor/hooks/`) waits until the file has held still for `LIVE_VERSION_SETTLE_MS` (750 ms, so a burst of agent writes is one version) and posts `POST /api/plan/versions { serverSession, hash }`. The server (`saveAnnotateLiveVersion` in `packages/shared/annotate-live-version.ts`, vendored to Pi; the Bun and Pi routes only parse the body and answer) reads the file itself, saves it only while its bytes still have the hash the editor showed (`409 stale` otherwise, and the next change asks again), and runs the open-time pipeline (`computeAnnotateHistory`: dedupe against the latest version, then the one before it), keyed by the same resolved path as the open-time save. It also replaces the session's `annotateHistory`, so a tab reload's `/api/plan` names the new version. The client then sets `previousPlan`/`versionInfo` and gives `usePlanDiff` a new identity (`live-version:<n>`), so the diff base becomes the version before the edit (each edit shows on its own; the Version Browser can still pick an older base) and an open diff view stays open on the new comparison. Design choice: save a version (what the issue and the approved card asked), not the lighter "diff against the version at open" HTML Refresh does, because the reviewer wants what changed since they last looked; and never on a GET: the write is an explicit POST from the open editor. Not saved: the reviewer's own Edit Mode saves (the reconcile reads them as `unchanged`), raw HTML (HTML Refresh keeps its open-time diff), folder and bundle files, URL, message and live-app sessions. Eligible means a single local session whose named and real paths are Markdown/text (`isSourceSaveFilePath`, `annotateLiveVersionFilePath`), so data files and diagram sources are left out. A file that was empty at open has no version yet but is still advertised: its first text becomes version 1. A session without history (`PLANNOTATOR_ANNOTATE_HISTORY=0`) gets no `liveVersions` and never posts, and the server answers `409 history_off` without touching the data dir; a file past the 2MB annotate cap answers `413 too_large`. Tests: `packages/server/annotate-live-version.scenarios.ts` (both runtimes) and the DOM test `packages/editor/App.liveVersion.test.tsx`.

History saves independently of the `planSave` user setting (which controls decision snapshots in `~/.plannotator/plans/`). Storage functions live in `packages/shared/storage.ts` (runtime-agnostic, re-exported by `packages/server/storage.ts`). Pi copies the shared files at build time. Slug format (history and archive alike): `{sanitized-heading}-YYYY-MM-DD` (heading first for readability; `plan-…` when the plan has no heading).

## Feedback Archive

Every review submitted through a Plannotator decision is durably archived at
decision-settlement time, so a submission survives an agent-side timeout, a
closed terminal, or a `planSave` setting the user turned off. One deliberate
exception: a review posted straight to GitHub, GitLab or Bitbucket with `POST
/api/pr-action` is delivered to the platform and is **not** archived locally
yet (a named follow-up). Layout, per project (same `{project}` key as
`history/`):

```
${PLANNOTATOR_DATA_DIR}/feedback/{project}/
  index.jsonl                                  # append-only, authoritative, schema v1
  records/2026-08-31T14-22-07-511Z-review-feedback.md   # human-readable sidecar
```

The JSONL line is self-contained (`v`, `ts`, `client`, `clientVersion?`,
`project`, `origin`, `surface`, `decision`, `target`, `feedback`,
`annotations`, `counts`, `recordFile`) so an analyzer never has to open a
sidecar; the markdown sidecar exists because the rest of the data dir is
greppable markdown and is written only for records that carry content. Bare
approvals, LGTMs, and dismissals are decision-only lines with no sidecar.

**This index is shared, not Plannotator-private.** Several tools that share the
data dir append to the SAME `feedback/{project}/index.jsonl`, separated by the
`client` field on each line rather than by separate files. Known writers today:
`plannotator` (this repo) and `plannotator-tui`, the Rust terminal client;
`herdr-annotate` is reserved for a possible future Lite writer. Treat `client`
as an open set, never an enum to validate against. Practical consequences: the
line shape is a cross-tool contract, so fields are **added, never repurposed**;
other clients suffix their id onto their sidecar filenames
(`{stamp}-{surface}-{decision}-plannotator-tui.md`), so the `records/`
directory holds more filename shapes than this repo writes and `recordFile` is
the only valid handle to a sidecar (nothing may parse the name); and unknown
fields must be ignored rather than rejected.

Two optional fields are declared in v1 but not populated here, so their names
are reserved across every client: `target.agent` (`{ host?, session?,
transcript? }`) is the provenance for surfaces whose subject is an agent
session rather than a file or a diff, such as annotate-last, and
`clientVersion` is the writing client's own version where it knows it
(`packages/shared` has no runtime-agnostic version constant, so this repo
leaves it unset rather than reading `package.json` from a vendored module).

Everything is written by one shared module, `packages/shared/feedback-archive.ts`
(vendored to Pi as `apps/pi-extension/generated/feedback-archive.ts`), which
resolves the data dir per call and **never throws**: a failed archive write is
logged, degrades silently for the user, and keeps the annotation draft as the
recovery copy. The append happens BEFORE `deleteDraft`, generalizing the #678
ordering to every surface. Call sites: `packages/server/index.ts`
(`/api/approve`, `/api/deny`), `packages/server/review.ts` (`/api/feedback`,
`/api/exit`), `packages/server/annotate.ts` (`persistSubmittedDecision`,
`/api/exit`), and the three Pi mirrors in `apps/pi-extension/server/`.

Invariants worth keeping: records never contain patch bytes or a second copy of
the plan (identity and a version-file reference instead); repeat decisions
append rather than overwrite (unlike the legacy `plans/` snapshot, which is
keyed by slug and status and is left alone); annotation `source` / `author`
provenance is preserved so external, agent, and WebMCP findings stay
distinguishable from the human's own comments; and `feedback` is listed in
`PURGE_OWNED_TOP_LEVEL` (`packages/server/uninstall.ts`) so uninstall purge
removes it. Controls and the privacy/retention note are in the
`PLANNOTATOR_FEEDBACK_HISTORY` row of the environment table above. The read
path in v1 is the files on disk (`jq` over `index.jsonl`, `grep` over
`records/`); there is no CLI reader or UI surface yet.

Details that surprise people:

- **Index durability is a practical guarantee, not a formal one.** One record
  is always exactly one line, and the whole line is handed to a single
  append-mode write. That write is not one syscall (`appendFileSync` loops
  internally until its buffer is drained); what holds in practice is that an
  `O_APPEND` write of a line-sized buffer completes without interleaving on a
  local filesystem. NFS and SMB do not promise even that, and a genuine
  interleave damages **both** records that raced, not just the later one. The
  backstop is the reader: unparsable lines are skipped, so everything else in
  the file still reads. With several clients writing one index, this caveat is
  worth knowing rather than assuming away.
- **Readers gate on structure, not version.** `parseFeedbackIndex` keeps any
  line that parses and carries a numeric `v`, so a newer writer's lines are
  still returned; an analyzer that depends on v1 semantics should filter
  `v <= 1` itself. Since fields are only added and never repurposed, a `v2`
  would signal a real shape change rather than the arrival of new keys.
- **Folder-session records name the folder, not the open document.** A folder
  annotate session submits one body of feedback for the session, so
  `target.filePath` is the session's folder. The record's `annotations` hold
  every document's comments (not only the open one's), and each comment made
  on a document other than the session's own target carries the additive
  `documentPath` field naming that document (absent means the session's own
  target or message; distinct from `file`, a code annotation's file).
- **Records of a review of several files name every file.** Surface
  `annotate-bundle` (additive), no `target.filePath`, and the additive
  `target.documents: [{ path, annotationCount }]` in review order; every
  comment on a file carries its `documentPath`.
- **URL-session records store the full URL, query string included**, because
  that is the page that was reviewed. A URL carrying a token in its query is
  therefore written to disk; the opt-out is the control for that.
- **`target.review.cwd` is provenance, not a durable handle.** A PR review
  started with `--local` records a per-PR pool checkout that is cleaned up when
  the session ends; `target.review.pr` plus `gitRef` are the identity that
  survives.
- **Project bucketing prefers the caller's `project` option** (the `project`
  field on `ReviewServerOptions`, mirroring the annotate server), falling back
  to deriving a name from the review cwd. The fallback is wrong in PR mode,
  where there is no `gitContext` and `--local` points `agentCwd` at
  `pool/pr-<n>`, so every CLI entry point passes `detectProjectName()`.
- **The test suite turns the archive off** through the `tests/setup/feedback-archive-off.ts`
  preload in `bunfig.toml`, because most server tests boot a real server
  without redirecting `PLANNOTATOR_DATA_DIR` and would otherwise write into the
  contributor's own data dir. Tests that need the archive opt back in inside
  their own test bodies.

## Plan Diff

When a user denies a plan and Claude resubmits, the UI shows what changed between versions. A `+N/-M` badge appears below the document card; clicking it toggles between normal view and diff view.

**Diff engine** (`packages/ui/utils/planDiffEngine.ts`): Uses the `diff` npm package (`diffLines()`) to compute line-level diffs. Groups consecutive remove+add into "modified" blocks. Returns `PlanDiffBlock[]` and `PlanDiffStats`.

**Three view modes** (toggle via `PlanDiffModeSwitcher`; `planDiffMode` in `packages/editor/App.tsx` defaults to `classic`):
- **Classic** (`PlanCleanDiffView`, block-level, old above new): Color-coded left borders — green (added), red (removed/strikethrough), yellow (modified). The default.
- **Rendered** (`PlanCleanDiffView` with `wordLevel`, experimental): the same view with word-level inline highlighting.
- **Raw** (`PlanRawDiffView`): Monospace `+/-` lines, git-style

**State** (`packages/ui/hooks/usePlanDiff.ts`): Manages base version selection, diff computation, and version fetching. The server sends `previousPlan` with the initial `/api/plan` response; the hook auto-diffs against it. Users can select any prior version from the sidebar Version Browser.

**Diff annotations:** The clean diff view supports block-level annotation — hover over added/removed/modified sections to annotate entire blocks. Annotations carry a `diffContext` field (`added`/`removed`/`modified`). Exported feedback includes `[In diff content]` labels. A diff annotation's `blockId` is `diff-block-N` (N indexes the diff against the selected base, not a document block), so the export cannot place it in the document: diff comments print together AFTER the document's other comments, in diff order (`sortAnnotationsInDocumentOrder` in `packages/ui/utils/parser.ts`); a document with no diff comments sorts exactly as before.

**Annotation hook** (`packages/ui/hooks/useAnnotationHighlighter.ts`): Annotation infrastructure used by `Viewer.tsx`. Manages web-highlighter lifecycle, toolbar/popover state, annotation creation, text-based restoration, and scroll-to-selected. The diff view uses its own block-level hover system instead.

**Sidebar** (`packages/ui/hooks/useSidebar.ts`): Shared left sidebar with three tabs — Table of Contents, Version Browser, and Archive. The "Auto-open Sidebar" setting controls whether it opens on load (TOC tab only). In archive mode, the sidebar opens to the Archive tab automatically.

## Portable Guided Reviews

Decision record: `adr/decisions/007-portable-guided-reviews-20260815.md`; spec: `adr/implementation/portable-guided-reviews.md`.

A guide exports as ONE small HTML file (size ≈ the diff, never the app) that pins a specific viewer build on `guides.show` (`viewer.<hash>.js/.css` + SRI). Format lives in `@plannotator/core/guide-format` (versioned strict snapshot, `createGuideHtml`, fixtures + a compatibility test that must keep parsing every shipped fixture); the pinned build is the generated `@plannotator/core/guide-viewer-manifest` (regenerate with `bun run --cwd apps/guides-show build:viewer && bun run --cwd apps/guides-show sync:manifest`; CI fails if stale).

Invariants: the diff a guide describes is captured when the guide job LAUNCHES (`buildCommand`'s `launchReview`, carried server-side like `changedFilesSnapshot` — never on the SSE-broadcast `AgentJobInfo`) and stored beside the saved guide as `{id}.patch` (patch written before the envelope that references it; deleted together). Exports never read the on-screen diff. `/v1/` on guides.show is add-only (content-hashed, never overwritten or deleted) so exported files keep opening; the viewer is the same guide chain (`@plannotator/guide-viewer`) over `AllFilesCodeView` in `readOnly` mode — no drift by construction. Read-only hosts stub the annotation composer/popovers at build time (`apps/guides-show/build/read-only-stubs-plugin.ts`); do not add app-only surfaces to the guide chain without going through the `GuideHost` contract.

Viewer runtime invariants (`apps/guides-show/viewer/`): the highlight worker is fetched from guides.show and constructed locally, and HOW is decided by a live probe (`portablePool.tsx`: blob classic → blob module → data classic → data module; a one-line worker must answer), never by `location.protocol` — Chrome refuses blob *module* workers from `file://` asynchronously (its console says "cross-origin redirects of the top-level worker script") but accepts classic ones, and headless checks with `--allow-file-access-from-files` hide that, so test `file://` exports WITHOUT that flag. The worker bundle must stay import-free (`check-budgets` asserts it) so it can run as a classic worker. A pool that is not initialized within 4 s is dropped (`PoolWatchdog`) and the guide re-renders on the main thread; Pierre renders nothing while waiting on a pool whose workers died, so this is what keeps diffs from going blank. The exported document's plain-text fallback article is opacity 0 for the first 2.5 s (CSS-only reveal), so a cold viewer download shows the theme ground, then the guide skeleton, then the guide — never a flash of the fallback prose. The portable page must not set `overflow` on `body`/`html`: `GuideViewportManager.findScrollRoot` walks up for an `overflow-y: auto|scroll` ancestor to use as its IntersectionObserver root + scroll-event source, and an overflow on body propagates to the viewport without body itself scrolling — the manager would observe a never-scrolling element, mark everything "near", rank by distance from the middle of the whole document, and CodeViews would only mount on hover (`requestMount`). The manager now treats body/html as the window regardless, but keep the CSS clean too.

Three producers share the one pure export (`createGuideHtml`): the in-app **Download portable guide** button, `plannotator guide export --id <saved>`, and the agent path `plannotator guide export --guide guide.json --patch guide.patch` (`packages/server/guide/guide-cli.ts`, `buildAuthoredGuideSnapshot`) used by the standalone `guided-review` agent skill (renamed from `plannotator-guide`; its own repo, `plannotator/guides` — deliberately NOT part of this repo or its installers; install with `npx skills add plannotator/guides`). That repo also ships `guided-plan`, a one-page guided plan built by its own `system/build.mjs`, not by this CLI. The authored form takes the same `{ title, intent, sections, unplacedFiles? }` shape the in-app generator emits plus optional `review { gitRef, base }`, `source`, `generator`; it is STRICT where the in-app validator is lenient (a file not in the patch, or placed twice, is an error listing the patch's files — exit 1 — rather than a silently dropped chapter), fills `source` from git in cwd (`origin` → owner/repo, branch, head sha) unless the guide supplies one, and round-trips the built snapshot through the strict format parser so a bad `source`/`generator` fails at export time. `--patch -` reads stdin. The skill's worked example is the `AUTHORED` fixture in `guide-cli.test.ts` — keep them in step.

### Hosted share links (guide share hosting)

Contract: `adr/implementation/guide-share-hosting.md` (names, routes, shapes and error codes there are final; change them there first). A guide can also be shared as a link on a guide host instead of a downloaded file: the review header's Share menu offers **Download portable guide** (unchanged) and **Create share link**; the CLI has `plannotator guide share --id <saved> | --guide g.json --patch p.patch | --snapshot s.json [--public] [--ttl 7d|24h|30m|3600] [--json]` (stdout: the URL, or `{ id, url, deleteToken, expiresAt? }` with `--json`; stderr: the size and the exact `Delete with: plannotator guide unshare <id> --token <t>` line) and `plannotator guide unshare <id> --token <t>` (removal goes to the host a saved guide's record names, else `PLANNOTATOR_GUIDE_SHARE_URL` / `guideShareUrl`). `--id` refuses with exit 1 while the saved guide already records a link. Exit codes match `export` (0 / 1 not found, invalid, service error / 2 usage). The upload itself is `shareGuide` / `unshareGuide` in `packages/server/guide/guide-share.ts` (vendored to Pi as `apps/pi-extension/generated/guide-share.ts`; both review servers expose the same `/share`, `/share-info` and `DELETE /share` endpoints). No upload ever happens without the Create click or the CLI command.

Two modes, encrypted by default. **Encrypted** stores `encrypt(await compress(snapshot))` (the same `@plannotator/core/crypto` + `@plannotator/core/compress` pair plan share links use); the key is generated by the uploader and lives ONLY in the URL fragment (`#key=<key>`, `GUIDE_SHARE_KEY_PARAM`), which browsers never send to the server, so the host holds ciphertext it cannot read and the page it serves is a shell that fetches `/api/g/<id>` and decrypts in the browser. **Plain** (`--public` / "Allow link previews", `{ public: true }`) stores the snapshot JSON (validated server-side with `parseGuideSnapshotJson`) so the hosted page can carry `<title>`, `og:*` and the guide text; use it when a chat app should unfurl the link. Both modes cap the stored body at `MAX_SHARED_GUIDE_BYTES` (25 MiB; `413`), have no expiry unless `ttlSeconds` (CLI `--ttl`) sets one, and return a one-time `deleteToken` (16 random bytes base64url, stored as a hex SHA-256) that is the only way to remove the guide besides the saved-envelope record.

Where it lives: `apps/guides-show/share/` (`core/handler.ts` is the pure request handler, `core/storage.ts` the `GuideStore` interface, `stores/{r2,memory}.ts`), served by the Cloudflare Worker (`apps/guides-show/worker/index.ts`, R2 bucket binding `GUIDES` = `guides-show-guides`). "Self-hostable" means deploying that Worker yourself and pointing `PLANNOTATOR_GUIDE_SHARE_URL` at it. Routes: `POST /api/g` (`201 { id, url, deleteToken, expiresAt? }`, `400`/`413`/`429`), `GET /g/<id>` (HTML, `Cache-Control: public, max-age=300`, styled 404 page), `GET /api/g/<id>` (the stored body, CORS `*`), `DELETE /api/g/<id>` with `Authorization: Bearer <deleteToken>` (`204`/`401`/`404`), `OPTIONS /api/g*`. Upload guards: the size cap plus a per-IP rate limit on creation only (Cloudflare's `[[ratelimits]]` binding, 20 creates per minute per `CF-Connecting-IP`, `429` + `Retry-After`), optional in the Worker's `Env` and fail-open whenever it cannot resolve, so local runs and self-hosts without the binding are unlimited. Guides are kept indefinitely by decision (no host-imposed TTL, nothing prunes the bucket); only an upload's own `ttlSeconds` expires one, enforced on read.

Invariants: hosted pages of either mode carry `<meta name=GUIDE_HOSTED_META_NAME>` (plus `<link rel=canonical>`, `robots noindex`, `og:*`), which is how the viewer knows to add its client-side **Download** button (builds the portable file from the DOM-reconstructed viewer pin, never re-fetches, never includes the hosted meta); the encrypted shell (`createGuideShellHtml`) additionally carries `<meta name=GUIDE_PAYLOAD_META_NAME>` naming `/api/g/<id>` and NO title, intent or payload in the HTML; a plain page embeds the snapshot like an export and has no payload meta. The key must never appear anywhere but the fragment (not in a query string, not in a request, not in a stored record other than the uploader's own envelope). The uploader sends its viewer pin (`{ js, css, jsIntegrity, cssIntegrity, langs? }` from `GUIDE_VIEWER_MANIFEST`) and the host renders with it on its OWN `/v1/` (`baseUrl` is never sent); without a pin the host uses its bundled manifest. Error pages name the serving host, never guides.show, and store failures answer `500 { error: "internal error" }` with the real message logged host-side only. One link per guide in Plannotator (`409` on a second upload); removal goes to the host the record names. Deploying the Worker with the `guides-show-guides` bucket is a separate, explicit step: no production deploy without a bucket, and never as part of a build.

## Data Types

**Location:** `packages/ui/types.ts`

```typescript
enum AnnotationType {
  DELETION = "DELETION",
  COMMENT = "COMMENT",
  GLOBAL_COMMENT = "GLOBAL_COMMENT",
}

interface ImageAttachment {
  path: string;   // temp file path
  name: string;   // human-readable label (e.g., "login-mockup")
}

interface Annotation {
  id: string;
  blockId: string;
  startOffset: number;
  endOffset: number;
  type: AnnotationType;
  text?: string; // For comment
  originalText: string; // The selected text
  createdA: number; // Timestamp
  author?: string; // Tater identity
  images?: ImageAttachment[]; // Attached images with names
  source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API
  diffContext?: 'added' | 'removed' | 'modified'; // Set when annotation created in plan diff view
  htmlAnchor?: HtmlElementAnchor; // Raw-HTML pinpoint: serialized element anchor for reliable restoration
  htmlAdditionalTargets?: HtmlAnnotationTarget[]; // Raw-HTML shift-click multi-select: extra elements this one comment covers
  diagramAnchor?: DiagramAnchor; // A comment on a rendered diagram part: { v: 1, family, kind, id | from + to, label, sourceLine } (document lines); see "Diagram comments"
  startMeta?: { parentTagName; parentIndex; textOffset };
  endMeta?: { parentTagName; parentIndex; textOffset };
}

interface HtmlElementAnchor {
  selector: string; // verified-unique CSS selector built in the viewer bridge
  tagName: string;
  text?: string; // normalized text snapshot; weak selectors fail closed against it
  point?: { x: number; y: number }; // normalized (0..1) selected point inside the element's rect, used by placed markers to reproject against the element's current geometry
}

interface HtmlAnnotationTarget {
  label?: string; // semantic label from the pinpoint hover cascade (e.g. "Button")
  text: string; // capped element text, or an element description when text-less
  anchor?: HtmlElementAnchor; // absent when anchoring failed closed
}

interface Block {
  id: string;
  type: "paragraph" | "heading" | "blockquote" | "list-item" | "code" | "hr" | "table" | "html" | "directive";
  content: string;
  level?: number; // For headings (1-6)
  language?: string; // For code blocks
  alertKind?: "note" | "tip" | "warning" | "caution" | "important"; // GitHub alerts (blockquote subtype)
  order: number;
  startLine: number;
}
```

## Markdown Parser

**Location:** `packages/ui/utils/parser.ts`

`parseMarkdownToBlocks(markdown)` splits markdown into Block objects. Handles:

- Headings (1 to 6 `#` then a space or end of line, CommonMark ATX; `#123 fixed` and `#hashtag` are text) with slug-derived anchor ids
- Code blocks (``` with language extraction)
- List items (`-`, `*`, `1.`)
- Blockquotes (`>`) — a run of consecutive `>` lines is ONE block whose `content` is the quote's own markdown (`>` plus one space stripped per line); `BlockquoteBlock` parses it again and renders fences, lists and nested quotes inside the one quote, with no `data-block-id` on the inner blocks, so the quote stays one annotatable block. GitHub alerts (`> [!NOTE|TIP|WARNING|CAUTION|IMPORTANT]`) set `alertKind` and keep `AlertBlock`
- Horizontal rules (`---`)
- Tables (pipe-delimited) — rendered via `TableBlock` with a `TableToolbar` (copy as markdown/CSV) and `TablePopout` overlay
- Raw HTML blocks (`<details>`, `<summary>`, etc.) — rendered via `HtmlBlock` through `marked` + DOMPurify
- Directive containers (`:::kind ... :::`) — rendered via `Callout`
- Paragraphs (default) with inline extras: bare URL autolinks, `@mentions` / `#issue-refs`, emoji shortcodes, smart punctuation

`exportAnnotations(blocks, annotations, globalAttachments)` generates human-readable feedback for Claude. Images are referenced by name: `[image-name] /tmp/path...`. Annotations with `diffContext` include `[In diff content]` labels.

## Annotation System

**Selection mode:** User selects text → toolbar appears → choose annotation type
**Redline mode:** User selects text → auto-creates DELETION annotation

Text highlighting uses `web-highlighter` library. Code blocks use manual `<mark>` wrapping (web-highlighter can't select inside `<pre>`).

**Annotation undo/redo:** each plan, annotate, or code-review app keeps one bounded 50-action stack for the active surface. `Mod+Z` undoes; `Mod+Shift+Z` and `Mod+Y` redo. Only local human annotation mutations are recorded, and a new mutation discards the redo branch. Native inputs, textareas, contenteditable regions, CodeMirror, dialogs/popovers, the Image Annotator, and an open Review Edit Mode session keep ownership of their own history shortcuts. External/agent writes do not enter annotation history; direct source changes, draft/share restore, refresh or diff replacement, identity changes, navigation to another document/message/review context, submission, and other baseline replacements clear it. The Image Annotator keeps a separate stroke undo/redo stack while its overlay is open.

**Images in a document (plan review and annotate).** The light version of the Inbox's one viewer (approval `inbox-image-viewer`, 2026-10-15): the editor's Viewer passes `imageLightboxStepping`, so a click on an image opens `ImageLightbox` with every zoomable image of the rendered document (`collectDocumentImages`: `img.cursor-zoom-in` in document order, each under its nearest heading): full screen, "2 of 4 · in “Options”", ← → and `]` `[` (stopping at the ends with "Last image in this document"), Actual size, and the pill under the image that opens the same `ImagePeek` (rows by section). No pen and no comments: there the person annotates the document itself. The lightbox's capture-phase key listener hands keys to the open peek (`ImagePeekHandle.handleKey`), so Esc closes the peek first, then the viewer, and Mod+Enter stays swallowed. Without `images` (every other caller, and hosts) `ImageLightbox` is the single-image overlay it always was. The lightbox zooms in both forms, stepping and single (#2067, `ImageZoomStage` over the pure `imageZoom.ts`; the image moves by transform only): Ctrl/⌘ + wheel, a trackpad pinch (Ctrl + wheel in Chrome and Firefox, gesture events in Safari) and two fingers zoom about the pointer; a plain wheel scrolls an image larger than the stage and zooms one that fits (one wheel gesture keeps the meaning it started with, `WHEEL_LATCH_MS`); mouse or one-finger drag pans; a double click or tap on the image toggles Fit and 2× Fit; Fit (never above 100%) to 800%. Actual size shows the image's own pixels from its top-left and pans (wheel, drag, or the browser's scroll keys while the focusable stage has focus: ↑ ↓, Page Up / Down, Home / End, Space, plus ← → in the single overlay; ← → still step in the stepping one); there are no native scrollbars. The stepping header shows the scale ("Zoom 151%" to a screen reader) beside Fit / Actual size, which reset it; stepping starts at Fit; Fit, Actual size and double click ease 180 ms unless reduced motion. The single overlay closes from the click that follows a tap beside the image, not from the pointerup, so a touch's synthesized click never lands on the page beneath. Ctrl + wheel and Safari gesture events anywhere over the lightbox are prevented, so the page never zooms. No keys were added.

**Cross-file annotations (multi-document annotate sessions).** A folder session — a review of several files (bundle), and any session whose linked documents carry feedback — spreads one body of feedback over many documents, so the annotations panel has a scope toggle in its header: **This file | All files**. It appears only when feedback exists outside the open document (`isMultiDocumentSession` in `packages/editor/App.tsx`); message multi-select keeps its own cross-message surface and is excluded. The toggle replaces the old `+N in M other files` flash affordance as the primary answer to "there are comments elsewhere"; the flash survives as a "Show in files" link at the foot of the All files view, and the header keeps a quiet `+N elsewhere` count while the scope is This file.

*Default rule* (`resolveInitialAnnotationScope`, `packages/ui/utils/annotationScope.ts`): the saved preference wins, except that a document with **no feedback of its own while other documents have some** opens on All files — that is the frustration the view exists for. It is re-resolved on every document change (keyed on the open document only, so a toggle is never yanked away mid-document), and the explicit choice persists per browser in the `plannotator-annotation-scope` cookie. One exception: arriving by clicking a card in the All files list keeps the All files scope, because that list is where the reviewer was.

*Grouping* is `groupAnnotationsByDocument` (pure, same file): one collapsible group per document that actually carries feedback, the open document first and the rest by path (in a bundle: the bundle's own order, the open file in its place, anything else after), labelled relative to the deepest session root the file browser knows. Cards are the same `AnnotationCard` the single-document timeline renders, so quote, comment, type, images, replies, Edit and Delete behave identically.

*Editing another document's comments* writes straight into that document's stored annotations through `useLinkedDoc`'s `updateStoredAnnotations` (the linked-doc cache, or the stashed source document); the active document is refused outright, since its annotations are host state. The export reads the same store, so a cross-file delete is reflected in what is submitted. *Export split:* `getDocAnnotations()` also carries the OPEN document's live state (for counts and the panel), so an export must never read it beside the host's live annotations — that printed the open document twice (every folder session, and any session submitted while a linked document was open). Every export goes through `useLinkedDoc.getFeedbackDocuments()` (`{ root, documents }`: the stashed root while a linked document is open, else null, and every other document once by path) and `resolveFeedbackSections` (`packages/editor/feedbackDocuments.ts`): the root (plan, file, or folder-level comments, plus SSE externals) under the session heading, every other document under its own path. A folder session titles that second section `Folder Document Feedback` ("files in the reviewed folder"), not the plan wording. Every document's entries are rendered by the ONE renderer `exportAnnotations` uses (`renderAnnotationEntries` in `packages/ui/utils/parser.ts`: document order, `[In diff content]`, quick labels + tip + Label Summary, threaded replies), so a document reads the same whichever section carries it. A cache entry under the root's own path (the root opened from itself, e.g. an HTML "Home" link) is a separate copy and is exported under its path, never dropped. **These cross-file mutations are deliberately not undoable:** the annotation history stack describes the open document's surface, and an entry that undid into a document the reviewer is not looking at would restore invisible state. `Mod+Z` still covers everything done in the open document.

*Jumping* (`useAnnotationJump`, `packages/editor/hooks/`) navigates through the file browser's own selection path — so the active file, the doc URL and the linked document stay in step — waits for the commit that makes the target the open document, then selects it, which is what scrolls markdown highlights and drives the HTML viewer's marker selection. A navigation that never commits drops the request rather than selecting an id into whatever document is open later. An HTML destination is opened with `revealSidebar: false`, exactly like a link click between HTML documents (#1532): that surface's page owns the viewport and the header carries its own Back, so arriving there must not pop the left sidebar. Both callers ask the same shared predicate, `documentRendersHtml` in `packages/ui/utils/htmlLinkNavigation.ts`.

*Counts:* the panel header shows the scoped count, but the session total the decision control runs on (`feedbackAnnotationCount`) is computed from session state and is unaffected by the toggle — switching scope never changes what is submitted. Not covered: code review, single-document plan review, and live-app multi-page sessions (which already group their export by page). The compact/touch sheet reuses `AnnotationPanel`, so it gets the same toggle in its own header bar. Every panel prop is optional and additive, so a host that passes none of them (Workspaces) renders the previous panel, legacy affordance included.

**Diagram comments (Mermaid and Graphviz fences).** A comment composed on a rendered diagram part — a click on a node, edge or cluster in the inline canvas or the popout — becomes an `Annotation` on the document with ONE additive field, `diagramAnchor` (`DiagramAnchor` from `@plannotator/core/diagram-anchor`, the `htmlAnchor` precedent): `{ v: 1, family, kind, id | from + to, label, sourceLine }` (families: flowchart, state, class, er, requirement, sequence, other, graphviz; kinds: node, edge, cluster, and `diagram` for the whole diagram, which has no id), where the anchor is the diagram's OWN id for the part (sequence parts carry classes, not ids, so the codec's ids are the actor's `name`, `msg-<n>`, `note-<n>`, `frame-<n>` by document order, restored with a label check because an ordinal moves) (never the rendered element id with its trailing counter, never geometry) and `sourceLine` names 1-based DOCUMENT lines (the offset is `Block.diagramSourceLineOffset ?? Block.startLine`: a fence's opening line sits one above the diagram's first line, so a fence uses its `startLine`, while a whole-file diagram source sets the offset to 0 because its first line IS document line 1). The annotation carries the fence's `blockId`, `startOffset`/`endOffset` 0, the label as `originalText`, `type: COMMENT` and the tater identity, so it lists in the annotations rail beside text comments, exports, persists in drafts (opaque JSON), and restores after a reload: `useAnnotationHighlighter` skips rows carrying `diagramAnchor` (neither attempted nor unanchored), and `DiagramBlock` re-resolves them against every render through the engine's finder — id, then label, then unanchored — and reports through `Viewer.onRestoreReport` with its own comments as `attempted`, so App's `markdownUnanchoredIds` shows the same "Unanchored" chip a text comment gets. All three export paths (`exportAnnotations`, `exportLinkedDocAnnotations`, `exportAnnotationEntry`) print the location line `Diagram node <label> (<id>), line <n>` (whole diagram: `Diagram (<family>), lines a–b`) under the comment's heading; a WebMCP reply inherits its parent's `diagramAnchor`; the diagram block is `annotation-exclude`, so text restore can never wrap a `<mark>` inside the svg. The line comes from (`diagramAnchorLocationLine`; edges name both ends); the feedback archive records the validated anchor as `diagramAnchor`; `POST /api/external-annotations` accepts a validated `diagramAnchor` on plan comments (both runtimes, `400` when malformed; such rows carry `blockId: "external"`, and like a comment whose fence was deleted they are resolved BY ANCHOR against every diagram block through `DiagramAnchorClaims` (`components/diagram/anchorClaims`, provided by `Viewer`): the first block in document order whose finder resolves it shows it, and when every block answered and none did it is reported unanchored); share links drop the anchor exactly like `htmlAnchor` (`sharing.multiTarget.test.ts`). Every renderer read of the field is nullish-safe (`ann.diagramAnchor != null`, `?.family`): a row reaches the renderer from several local ingests, and a malformed anchor must list as unanchored, never throw during render. Selecting a diagram comment in the rail pulses its ring, pans it into view and scrolls the block into view. Plannotator passes `maxAdditionalTargets` 0 (one part per comment; the viewer's shift-click multi-select is a host opt-in) and no `onSave` (no Source pane; the in-block Show-source toggle keeps the fence readable). Read-only documents (archive) open no composer. The composer also offers **Ask AI** (same handler, label, disabled-until-text rule and no key binding as the markdown composer's; Enter stays Comment) wherever the document's Viewer gets `onAskAI`: `DiagramBlock` sends a `CommentAskAIContext` built by `diagramAskAIContext` (`packages/ui/utils/diagramAskAI.ts`) whose `detail` carries the export's location line, the engine and family, and the diagram source in document lines (bounded to 40 lines / 4000 chars, grown outward from the part's line so the part is always in it; a single line over the budget is cut with `…`), so the identity rides the user message ahead of the question for SDK providers, Ask this session and the agent terminal alike. Asking from the popout closes the popout, which would otherwise cover the panel the answer streams into.

**Diagram files (annotate `.mmd`/`.mermaid`/`.dot`/`.gv`).** `plannotator annotate flow.mmd` opens the FILE as one diagram in the same engine — `DiagramBlock` → `DiagramViewer` → `DiagramPopout`, themed, click-to-comment on nodes/edges/clusters/the whole diagram, drafts, export, per-file version history — rather than refusing it or rendering it as text. Three pieces, one decision each:

1. **Core** (`packages/core/annotatable.ts`): the four extensions join the annotatable plain-text and doc sets (they ARE UTF-8 text, so CLI resolution, the 2MB `MAX_ANNOTATABLE_FILE_BYTES` cap, folder discovery, the file browser and `/api/doc` need no special case), and `diagramRenderKindForPath` is the single predicate that names the engine. They are not markdown: `shouldStripFrontmatter` returns **false** for them, because Mermaid's own `--- … ---` config block is diagram content, and `normalizeMarkdownExtensions` can never re-register them.
2. **Servers** (`packages/server/annotate.ts` + `reference-handlers.ts`, mirrored in `apps/pi-extension/server/serverAnnotate.ts` + `reference.ts`): `/api/plan` and `/api/doc` set `renderAs` to `"mermaid"`/`"graphviz"` and keep the file's RAW text as the body. The session-level guard is the shared pure `annotateDiagramRenderKind`, so both runtimes exclude raw-HTML, converted, URL, folder, message and live-app sessions identically. Version history is unchanged (diagram text is text).
3. **Editor** (`packages/editor/App.tsx`): `renderAs` widens to `DocumentRenderAs` (`'markdown' | 'html' | DiagramRenderKind`) and the `blocks` memo becomes `diagramDocumentBlocks(text, kind)` (`packages/ui/utils/parser.ts`) — ONE `code` block whose language routes to the engine, so `Viewer`, `diagramAnchor` comments, `useAnnotationHighlighter` skipping, the export, drafts and restore are the fence path unchanged. The block sets `startLine: 1` + `sourceLineCount` (so the export's `(lines a–b)` label names the file's real span) and `diagramSourceLineOffset: 0` (so a comment's `sourceLine` is the file's own line — a synthesized ```` ```mermaid ```` wrapper would report every line one too high). Edit Mode and the Select/Markup input-method strip are excluded with HTML: the block is `annotation-exclude`, so there is no text to drag-select.

Share links carry the FENCED form in the payload's `p` (`shareableDocumentMarkdown`, `packages/ui/utils/sharing.ts`): the portal has no server to tell it `renderAs`, and fencing needs no portal change and no new payload flag. Diagram comments themselves still degrade to text comments in a share link, exactly as they do from a fence (`diagramAnchor` is dropped like `htmlAnchor`).

**Raw-HTML annotate:** the sandboxed viewer never mutates the visited page's DOM. Committed annotations render as numbered placed comment markers plus overlay-projected highlight rectangles inside a shadow-rooted fixed overlay host: the durable anchor data (element selector, text snapshot, normalized selected point) is persisted, and the markers/highlights are disposable projections re-resolved from it on every reconcile. Shift-click multi-select joins additional elements to one comment (`htmlAdditionalTargets`).

**Element context (agent-facing).** A pinpoint also captures a bounded description of the element at click time, `elementContext` on the annotation (`HtmlElementContext` in `packages/ui/types.ts`; extra targets carry a smaller one as `context`), built by `buildElementContext` in the bridge and re-validated at the parent trust boundary by `parseHtmlElementContext`, which lives in `packages/core/html-anchor.ts` beside `parseHtmlElementAnchor` (#1549); `useHtmlAnnotation.ts` imports and re-exports it rather than mirroring it, and the host persistence helpers in that same core module (`buildPersistedHtmlAnchor`, `projectHostThreads`) run it too, so a host that persists and projects through core keeps the field instead of dropping it on save. It is purely descriptive, never read by restore. Fields: tag, id, author classes, an ancestor `path`, explicit-or-implicit `role`, accessible `name`, an ALLOWLISTED attribute set (href/src scrubbed of query and fragment, `data:` truncated to its media type), rendered `text` (300), a collapsed HTML `outline` (600 chars; two child levels, then one, then a per-tag count, whichever first fits), child count, viewport `rect`, nearest `landmark` and `heading`, a `component` hint from `data-component`/`data-testid` ancestry (deliberately no React fiber reads), and in live-app sessions the `page` route and title. Never captured: form values, `on*` handlers, `style`, script/style/template contents, full innerHTML. Hard cap 2 KiB serialized per primary (1 KiB per extra target), shedding outline → text → attrs → classes → path → heading → landmark → component → sourceName (one order, `ELEMENT_CONTEXT_SHED_ORDER` in core, mirrored by the bridge's `CTX_SHED_ORDER`; a test keeps them equal). Under the persisted anchor's own 16 KiB budget `buildPersistedHtmlAnchor` sheds contexts — per-target first, from the end, then the primary — BEFORE it drops any target, since a context is descriptive and re-derivable on the next click while a dropped target loses a marker the reviewer placed; `DEFAULT_HTML_ANCHOR_MAX_BYTES` is unchanged and the dropped-target counts still count targets only. The export (`elementContextExportBlock` in `packages/ui/utils/parser.ts`) prints a 4-backtick `html` fence of the outline plus `selector` / `path` / `role` · `name` · `component` / `attrs` / `text` / `box` / `near` lines under the comment; a text-less pinpoint's placeholder quote names WHICH element it is, not just its kind: the hover label plus the accessible name (`ctxName`: aria-label, alt, title, …) plus, for media (`img`, `video`/`audio` and their `<source>`, `iframe`, `embed`, `object`, `input type=image`, svg `<image>`), the source FILE name through the same `ctxScrubUrl` scrub (`[element: Image "Team photo" (team.jpg)]`, `[element: Image (data:image/png)]`; brackets and double quotes are swapped so it stays one token; `describeTextlessElement` in the bridge, used for the primary and every shift-click extra target). Restore never reads that quote: a text-less element is bound by its anchor, which it gets through an `#id` or `data-*` identity rung or, for media, through its source (`anchorSourceSnapshot` in the bridge: the author's reference to the resource, relative to the document's base when it lies under it (so a pin saved in one session restores in the next, whose asset route has another port and token), else root-relative on the document's own origin, else origin and path; the query and fragment count only as an 8-hex FNV digest, never in plain text, so `/_next/image?url=a.jpg` and `?url=b.jpg` are different sources while a token stays out of the annotation, and a source re-signed per load does not restore; no anchor for a `data:`/`blob:` source or for a source another element of the same kind shows, so identical siblings still fail closed). A media anchor whose selector no longer lands on its element is found again by that source (`relocateBySource`; two matches resolve nothing), and an element whose source changed is not bound (the pin is reported Unanchored). An `href`/`alt` selector rung can still carry a raw attribute value, as for text-bearing elements. So pins saved with the older bare `[element: Image]` keep restoring. The export rewrites the placeholder to `Feedback on the <nav> element — "Primary"` in the heading, plus the media file name (`Feedback on the <img> element (jane.png)`), read from the context's `sourceName`: the bridge records the file `describeTextlessElement` names (src, a lazy `data-src` over a `data:` placeholder, `srcset`, `<picture><source srcset>`, a video's `<source>` or `poster`, scrubbed the same way), so the heading and the composer quote always name the same file; contexts saved without `sourceName` fall back to the scrubbed `src` attribute, while a pinpoint with real quoted text keeps its quote line and gains the block. In srcdoc sessions `ctxScrubUrl` also drops the session's `/api/html-assets/<token>/` prefix, so a `src` reads as the author's own document-relative path, percent-decoded (`jane doe.png`). **Ask AI** carries the same identity: a question asked from a pinpoint composer sends `elementIdentityForAskAI(draftTargets)` (`packages/ui/utils/parser.ts`, the identity lines of `elementContextExportBlock` with `includeOutline: false`, numbered per element) as the scope's `detail`, which `buildDefaultPrompt` appends under "Selected element:" and the chat never displays; SDK providers, "Ask this session" and the agent terminal all send that prompt. It carries no query strings: the live route and an `href`/`src` selector rung are scrubbed to `?…` there (the persisted annotation keeps them). Annotations without the field export byte-identically. The grouped live-app export omits the `route` line (the `## Page:` heading carries it); `exportAnnotationEntry` (one annotation, no number) includes it; it is a pure helper for hosts and tests, and the annotation panel's card chrome is unchanged. Both helpers also take `includeOutline` (default `true`): `false` prints the identity lines without the fenced outline, for model turns where the 600-char outline is the expensive part per annotation. Share links drop `elementContext` exactly like anchors. The feedback archive records identity only (`elementTag`, `elementSelector`, `elementPath`, `elementRole`, `elementName`, `pageUrl`), never the outline. No `BRIDGE_PROTOCOL_VERSION` bump: the field is additive in both directions.

**HTML and live-app interaction model:** raw-HTML sessions and live app sessions (`mode: "annotate-app"`) share one contract. Both open with pinpoint **armed** (`htmlAnnotateArmed` defaults to `true`, `packages/editor/App.tsx:493`; live sessions open armed like every other HTML surface, `App.tsx:2871`). `Esc` walks a ladder instead of exiting outright: a pending draft closes first, then the pinpoint hover outline clears, and only then does `Esc` drop the surface to **Interact**, where the bridge goes passive so clicks, forms, text selection, and SPA navigation reach the page natively (`packages/ui/components/html-viewer/bridge-script.ts:3066-3080`; committed markers stay visible and a marker click still opens its comment, and in Interact an open drag-comment draft still closes before `Esc` is handed back to the page). Vim owns its own ladder and is skipped here. The header **pen** button toggles Annotate/Interact (`packages/editor/components/AppHeader.tsx:386-404`, `aria-pressed`), as does `Mod+Shift+A` (`packages/ui/shortcuts/plan-review/htmlAnnotate.shortcuts.ts`) — a real toggle in BOTH directions, which is what makes it the answer to "Esc dropped me to Interact, how do I get back?". Disarming through either path tears down any pending draft, because the bridge's `set-annotate-mode(false)` handler clears every pending affordance (`bridge-script.ts:719-739`), exactly as the Esc ladder does. The bridge mirrors the chord inside the iframe on the capture phase and forwards it to the parent, so it works whichever document owns focus. Text drag-selection commenting is **always live**, on both surfaces and in both states, ungated from the armed flag and from the input method (`bridge-script.ts:384-386`, `:1420-1436`): while armed, a click pins an element (a link only with `Cmd`/`Ctrl` held: a plain click on a link follows it, see "Links between local HTML documents") and a drag selects text at the same time, and the one-shot `dragEndedClick` guard stops a completed drag's trailing click from re-pinning (`bridge-script.ts:1381-1390`).

These surfaces are **comment-only**. `redline` (auto-DELETION) and `quickLabel` are clamped at the trust boundary, which is the parent's postMessage ingest rather than the server, covering the host mode and a page-supplied `modeOverride` alike so a hostile page cannot force a DELETION (`packages/ui/components/html-viewer/useHtmlAnnotation.ts:535-547`). Only CREATION is restricted: persisted DELETION annotations still restore and still render their deletion styling (`useHtmlAnnotation.ts:903`). The selection toolbar drops Delete and the label picker behind a `commentOnly` seam and keeps exactly one label affordance, the hardcoded 👍 "Looks good" for text selections (`HtmlViewer` filters its `onQuickLabel` handler to `THUMBS_UP_LABEL`); markdown surfaces keep the full toolbar. A pinpoint click opens the comment composer directly and never shows that toolbar, so the composer carries the same one-click 👍: an emoji-only button beside Save (`aria-label` and tooltip "Looks good", `data-quick-look-good`), passed by `HtmlViewer` as `CommentPopover`'s `onQuickLookGood` (absent on markdown and global composers). It goes through the same commit path as a typed comment (`commitComposerDraft` in `useHtmlAnnotation`), so the result is the toolbar's `THUMBS_UP_LABEL` quick-label COMMENT on the pinned element with its anchor, element context and shift-click extra targets. It is disabled once anything is typed or attached (a click never discards a draft) and takes no key: Mod+Enter still saves the typed comment. HTML surfaces also pin the viewer input method to pinpoint (`App.tsx:5480`), so there is no floating input-method toolstrip on them at all (`toolstripVisible` is gated on `!isHtmlSurface`, `App.tsx:2788-2793`) and the `Shift+1`-`4` annotation-mode shortcuts cannot fire there. A header **eye** button immediately left of the pen toggles Show/Hide tools, as does `Mod+Shift+X` (same scope, same bridge forwarding as the pen chord — the binding is deliberately un-mnemonic because every mnemonic letter is a browser chord: H is Chrome Home / Firefox history, E/I/J/K/C devtools, B/O bookmarks, V paste-as-plain-text, T reopen tab): hiding REMOVES all floating chrome over the page from the DOM (the sidebar tongue tabs and the comment/attachments cluster) rather than merely hiding it (`AppHeader.tsx:364-385`, `App.tsx:5193`, `HtmlViewer.tsx:810`). These surfaces **open with the tools hidden** — `DEFAULT_HTML_CHROME_STATE.toolsHidden` is true and `App.tsx` seeds `htmlToolsHidden` true so nothing flashes before the restore effect — because an HTML document is authored to fill the viewport. A fresh persisted record still wins in both directions, so a reviewer who showed the tools keeps them — in a folder annotate session too, which restores and records the `toolsHidden` half while leaving the sidebar/panel halves alone, since its file browser owns the sidebar for the whole session (`mergeHtmlChromeState`). The toggle lives in the header (and in the compact Options menu), so hidden — default or restored — always has a way back, which is what makes both honoring the persisted `toolsHidden` cookie and defaulting to hidden safe (`packages/ui/utils/htmlChrome.ts`). Note the version-diff "Show changes" control lives in that floating cluster, so it is behind the eye on a fresh session. All three header controls (eye, pen, Refresh) describe themselves through the app's `Tooltip` rather than a native `title` (`packages/ui/components/HtmlSurfaceControls.tsx`): two lines, the control's description — still the host-overridable `labels` string — over its shortcut as keycaps from `formatShortcutBindingTokens`, so the chord is never a hardcoded "Cmd". Because `title` no longer supplies the accessible name, the pen carries an explicit `aria-label` (defaulting to its description), the eye keeps its sr-only text and the Refresh its `aria-label`; the shortcut is additionally attached as a persistent `aria-describedby` span, because this Base UI build tags the popup with no ARIA at all. Refresh has no chord and renders no keycap row; `shortcuts` on the component overrides the bindings per control, defaulting to the `html-annotate` scope so the tooltips cannot drift from what the app dispatches.

**HTML Refresh (#1232).** A local rendered-HTML session can re-read its file from disk without reloading the tab, for the loop where an agent edits the page while the reviewer keeps annotating. The header **Refresh** button (left of the eye, `data-html-refresh`, titled "Refresh HTML from disk") fetches the active document through `/api/doc`, hands the bytes to the app, and remounts the viewer under a bumped `reloadGeneration` key (`packages/editor/App.tsx`, viewer `key`). The engine is the published `useHtmlRefresh` (`packages/ui/hooks/useHtmlRefresh.ts`: superseded and cross-document fetches are dropped, one restore acknowledgement per generation) and Plannotator's binding over `fetchHtmlDocumentSnapshot` is `packages/editor/hooks/useHtmlRefresh.ts` (toasts for refreshed, missing, and unavailable). Committed annotations survive on their durable anchors: the remounted viewer re-resolves every element selector and text snapshot against the new page, and the ones it cannot re-anchor are reported once (`onUnanchoredChange` to `reportAnnotationRestore`), toasted, and marked with an **Unanchored** chip in the annotations panel (`htmlUnanchoredIds` in App, cleared when the document changes); their comments stay in the panel and still export. A refresh keeps the version diff: for the root document `/api/doc` carries `previousPlan`/`versionInfo`/`diffHtml` recomputed against the bytes just read (see the annotate `/api/plan` row), `applyRefreshedHtml` sets them and resets `isPlanDiffActive`, so the view returns to normal mode with "Show changes" still available; a tab reload converges on the same state because `/api/plan` serves the current bytes and recomputes the same diff. `/api/share-html` shares the current bytes too. Only local files refresh: `canRefresh` is false for `http(s)` paths and live-app sessions, and the control is absent on read-only (archive) documents. The compact touch shell renders no header controls (`HtmlSurfaceControls` returns null when `compact`), so its Options menu offers "Refresh from disk" beside the Show/Hide tools and Interact/Annotate actions (`compactDocumentActions` in App, disabled while a refresh is in flight); a host that passes `canRefresh` and `onRefresh` to `HtmlSurfaceControls` gets the Refresh button with or without the eye.

**Links between local HTML documents.** A srcdoc document has no URL of its own — its base URL is the PARENT page's, which is the Plannotator server — so an ordinary `<a href="02-detail.html">` used to resolve onto the server, hit the catch-all, and render the whole editor inside the annotated frame; an in-page `#section` link navigated for the same reason. The bridge therefore **never lets the srcdoc frame navigate itself**: a capture-phase click handler registered before the pinpoint handler (never stopping propagation, so the pinpoint handler still sees the clicks that pin) `preventDefault`s every link click, scrolls in-page `#fragment`s locally, and posts the RAW href to the parent as `link-click`, only for a person's click (`event.isTrusted`, in both modes: a page's own `a.click()` never navigates the viewer or pushes the Inbox's history). `javascript:` hrefs are left to the page. The parent is the trust boundary: `parseBridgeMessage` bounds the href (2048 chars, no control characters) and `resolveHtmlLinkIntent` (`packages/ui/utils/htmlLinkNavigation.ts`, pure) decides what it means — a relative or `../` path resolves against the CURRENT document's directory and opens as a **linked document** through `/api/doc` exactly like a relative markdown link, a root-relative path (and the same path spelled with the server's own origin, the shape an author writes as `http://localhost:<port>/01-entry-point.html`) resolves against the directory the session was opened from, another origin opens in a **new tab** (`noopener,noreferrer`, the frame never navigates), a link to a local **image** (`png jpg jpeg gif webp svg avif bmp ico apng`, the set code review previews, `isReviewImagePath`) opens in the shared `ImageLightbox` (`packages/ui/components/ImageLightbox.tsx`, the same overlay the markdown Viewer uses), read through the page's OWN `/api/html-assets/<token>/…` route taken from the `<base href>` the server installed (`htmlAssetRouteFromDocument`) so nothing becomes readable that the page could not already load, and only when the image resolves inside the current page's directory (one reached by `../` or a root-relative path outside it toasts "Images open only from this page's own folder"; a page with no asset route, such as a share link, toasts too). The lightbox shows the image only through `<img src>` (an SVG never runs), takes focus when it opens (pulling it out of the iframe), and swallows every key on the window's capture phase while open, so `Esc` closes it before the HTML Esc ladder runs and `Mod+Enter` cannot submit a decision behind it. Any other local file outside the annotatable set (`.pdf`, `.zip`) raises a toast and is never fetched, and every other scheme (`data:`, `file:`, `mailto:`, `blob:`) is dropped. The query string is stripped and the fragment is kept: it rides to the new document as `HtmlViewer`'s `initialFragment` and is replayed once that document's bridge is ready (`scroll-to-fragment`). Folder sessions route the open through the file-browser selection handler so the active file, the sidebar and the linked doc stay in step. Annotations stay per document (the `useLinkedDoc` cache), and the Interact/Annotate state and the chrome rules keep applying. **Navigating between HTML documents never opens the sidebar**: the page owns the viewport on this surface (it opens with the tools hidden and the sidebar closed), so a link click leaves the sidebar exactly as the reviewer had it — closed stays closed, open stays on its tab. `useLinkedDoc.open` / `openLoaded` take `revealSidebar` for this (default `true`, so every markdown caller is unchanged), and App passes `false` only when the target renders as HTML — `resolveHtmlLinkIntent`'s `rendersHtml`, which is false for markdown targets and for `.html` under `--markdown`, so a markdown target keeps the markdown convention of opening the Contents tab. The way back is therefore a **Back control in the header** (`data-html-back`, leftmost of the HTML surface controls, before Refresh/eye/pen), rendered only while a linked HTML document is open and named after the document it returns to ("Back to index.html"; `useLinkedDoc` keeps one root snapshot rather than a stack, so Back from any depth lands on the session's root). It deliberately claims **no keyboard shortcut** — `Alt`+`Left` and the browser's own Back belong to the user — and the compact touch shell offers the same action in its Options menu. The sidebar's "Viewing / Back to …" header still works for anyone who opens the sidebar, and `TableOfContents` now renders it even when the document has no headings at all, the normal case for raw HTML. The chrome restore-on-entry effect does not re-run on html→html navigation (`shouldRestoreHtmlChrome` in `packages/ui/utils/htmlChrome.ts` is false whenever the previous surface was HTML), so following a link cannot slam the tools back to hidden or re-apply a remembered sidebar state mid-session. **A plain click on a link follows it in both states** (owner's ruling `html-link-click`, 2026-10-20, one rule for annotate, plan review's raw HTML and the Inbox): the frame never navigates, and the bridge posts `link-click` armed or not. Only a link with a real destination is followed (`isFollowableHref`): no href, `href=""`, `href="#"` and `javascript:` go nowhere, so while armed a plain click pins them as any element (agents' mocks use `<a href="#" class="btn">` for buttons). While armed, a followable link shows no pin outline or label and keeps the pointer cursor until `Cmd`/`Ctrl` is held (read from the key and from each pointer move, `data-plannotator-pin-modifier` on the page's body; SVG links with only `xlink:href` included), so the outline always matches what a click will do. In annotate and plan review, following a link to another document while a comment is being typed waits: the draft stays, focus returns to it, and a toast says so (`packages/editor/htmlLinkDraftGuard.ts`, `App.htmlLinkDraft.test.tsx`); the Inbox asks through its pane's unsaved-comment question. **While armed, `Cmd`-click (`Ctrl`-click off macOS; the bridge takes either modifier, `armedClickPins`) pins the link** for a comment through the pinpoint handler, with its anchor as for any element, and so does a shift-click that adds the link to an open multi-select draft; a drag that selected text and ended on a link neither follows nor pins (`dragEndedClick`). Keyboard: Enter on a focused link fires a plain click, so it follows. Image links follow the same rule (a plain click opens the lightbox, the modifier pins the thumbnail). While armed a link keeps the pointer cursor instead of the crosshair. In Interact the modifier changes nothing (the link follows). Live app sessions (`mode: "annotate-app"`) keep navigating for real: the interceptor lives inside the bridge's `!LIVE` guard, and there the pinpoint handler leaves a plain link click to the browser (native navigation of the proxied app), pins it with the modifier, and prevents a drag's trailing click on a link. **On touch** (the owner's amendment, 2026-10-20) the same rule holds on every one of these surfaces, live apps included: a TAP on a link follows it (it reaches the click handlers as a plain click), and a PRESS-AND-HOLD of 500 ms (`HOLD_PIN_MS`) pins it for a comment with the same shape a Cmd-click makes (the link's words as a text range). A finger that moves more than 10 px (`HOLD_SLOP_PX`), a second finger or a scroll cancels the hold. The release of a hold that pinned never follows the link and never reaches the page: the bridge's window-capture listeners (registered before a live app's own, since the proxy injects the bridge first in `<head>`) stop that gesture's touch `pointerup` and `touchend` with `stopImmediatePropagation`, cancel `touchend` (no synthesized click), and swallow one click that still arrives. So that the page still sees the press end (React Aria's `usePress`, Motion's `whileTap` and dnd-kit would otherwise keep it open), the bridge dispatches a `pointercancel` (same `pointerId`, `pointerType: "touch"`, `isPrimary`) and a `touchcancel` on the element the finger went down on in place of the stopped release; its own listeners ignore those two (a `WeakSet` of the events it made). A pointer the browser cancelled itself gets no second cancel. That swallow ends at the next touch, mouse or pen press, or key, and a release the bridge never saw (a page that stopped `touchend`) is bounded at 10 s (`HOLD_SWALLOW_MAX_MS`) and also ends at the next touch, so it never eats an unrelated click. iOS's link callout is off on links while armed (`-webkit-touch-callout: none` under `body[data-plannotator-pinpoint-cursor]`, scoped to `[data-plannotator-touch]`, set on the first touchstart, or `@media (hover: none)`); that is all those rules do, so link text stays selectable and a mouse or trackpad drag across a link still quotes its words, on a touchscreen laptop or an iPad with a trackpad too. Link text is unselectable (`user-select: none`) only while a hold on a link is in progress (`body[data-plannotator-link-hold]`, from that touchstart to its release or cancel), so the platform's long-press starts no native selection under the finger; the hold turns it back on for the moment it pins, so the pin carries the text. Android's long-press `contextmenu` during a hold is cancelled and fires the hold at once. Interact keeps the platform's own long-press. Proved in `srcdoc.test.ts` and `htmlLiveProtocol.test.tsx` (touch cases: the swallow ended by a mouse press, a key or a new touch; an unseen release; a hold's release kept from a live app's own `pointerup`/`touchend`/`click`), `tests/e2e/inbox-html-links.spec.ts` and `tests/e2e/annotate-html-links.spec.ts` (WebKit iPhone 15 and Chromium Pixel 7: a real DevTools-protocol touch in Chromium, the page's touch events in WebKit; plus a desktop local HTML file and a live app on a loopback server: a plain click follows, Cmd/Ctrl-click pins; and a touch-capable desktop where a mouse drag across a link after a touch quotes the link's words). Tests: the `link navigation` block of `srcdoc.test.ts`, the live link cases in `htmlLiveProtocol.test.tsx`, `htmlLinkProtocol.test.tsx`. Known limitation for LINKED documents outside a folder session (`/api/doc` mints a token per HTML file's own directory and refuses `..`, so `sub/page.html` opened as a linked document loads assets below it but not ones it reaches with `../`); a folder session does not have it, since every HTML document inside the selected folder shares one token rooted at the folder (`htmlAssetContext`, #1568), and **embedded** documents are not affected, because they load from the embedding page's token root — see the next paragraph.

**Embedded local documents.** The same "a srcdoc has no URL of its own" fact broke `<iframe src="prototype.html">` far worse than it broke links: the embed resolved onto the server, the catch-all answered with the app, and every embed in a report rendered a second Plannotator (#1554 — five of them, cookie-less because a nested context inherits the parent's sandbox flags). Links could be fixed by intercepting clicks; embeds cannot, because the `src` is routinely assigned by SCRIPT at runtime (`<iframe data-src="…" loading="lazy">` plus a loader) and may carry a query string, so no serve-time attribute rewrite ever sees it. The fix changes **resolution** instead of markup: `rewriteHtmlAssetReferences` installs a `<base href="/api/html-assets/<token>/">` first in `<head>`, so every relative URL the document produces — `<iframe>`, `<embed>`, `<object data>`, `<frame>`, a runtime `el.src = …`, a `fetch('./data.json')`, a `new URL(x, document.baseURI)` — lands in the document's own directory whatever writes it and whenever. The base is root-relative because a srcdoc resolves its own `<base href>` against the parent's URL (this server), so the port need not be known; an author's own `<base href>` is re-anchored when relative and left untouched when absolute or root-relative (they pinned an origin deliberately). `/api/html-assets` now serves `.html`/`.htm` as real documents, so an embedded page's own relative assets and nested relative embeds resolve against ITS position under the token root — including `../` back up to the root, which is why the linked-document limitation above does not apply here. Query strings and fragments survive to the embedded document untouched (`mock-decisions.html?step=result` sees its own `location.search`); the route only ever reads `url.pathname`.

*Security.* Embedded pages are untrusted author HTML served from the Plannotator server's origin. Inside the annotate surface the primary document's `sandbox="allow-scripts allow-modals"` iframe (`HTML_VIEWER_SANDBOX` in `HtmlViewer.tsx`; `allow-modals` since #2063 so alert/confirm/prompt open, pinned with no `allow-same-origin` by `iframeIsolation.test.ts`) already protects them: sandboxing flags are inherited and intersected by every nested browsing context, so an embed runs at an opaque origin with no `allow-same-origin` and its `fetch('/api/plan')` fails as cross-origin (verified in the browser, before AND after this change — the pre-fix nested Plannotator was already origin-`null`, which is exactly why the owner saw "no cookies in it"). Defense in depth for the case with no parent sandbox — a reviewer pasting an asset URL into a top-level tab — is on the response: every HTML response from the asset route carries `Content-Security-Policy: sandbox allow-scripts allow-modals` (`HTML_ASSET_DOCUMENT_CSP`, never `allow-same-origin`; `allow-modals` since #2063, owner-approved, so a page's alert/confirm/prompt open, matching the srcdoc frame's `HTML_VIEWER_SANDBOX`) plus `X-Content-Type-Options: nosniff`, and no cookies are involved. Embeds reach nothing their page's own assets could not: the same token root, the same `..` refusal, the same `isWithinDirectory` symlink check. That root is the document's own directory, except in an `annotate-folder` session, where it is the selected folder: every document inside it gets that one root, with its own directory as the `<base href>` beneath it, so `../assets/x.css` resolves (#1568). Because that root hands the page the whole folder, each folder-session token names its page's directory too (one token per page directory) and an asset is served when either (a) it resolves inside that directory, hidden segments included, exactly as when the directory was the root (`site/page.html` → `.vendor/x.css`), or (b) it resolves elsewhere in the folder and no segment of its path under the folder, as requested and by realpath, starts with `.` or is in the dotenv family (`folderSessionAssetAllowed`, the same hidden rule as the Inbox; on the route and in share links). A symlink in the page's directory that leads elsewhere in the folder is judged by (b). A document that itself sits in a hidden folder (`.drafts/page.html`) is not widened and keeps its own directory as its root. In a folder session, then, any page in the folder can read the folder's other non-hidden files of an allowed asset type (the asset route answers CORS `*`), so `plannotator annotate ~` exposes that much of the home folder to the pages under review. HTML documents additionally honour the 2MB `MAX_ANNOTATABLE_FILE_BYTES` annotate cap rather than the 50MB asset cap. The decision is single-sourced in `resolveHtmlAssetRoute` (`packages/shared/html-assets.ts`, vendored to Pi) so the Bun route and the Pi mirror cannot drift.

*Never the app in a frame — but only for a path that could BE a file.* Under the assets prefix, a request whose `Sec-Fetch-Dest` is `iframe`/`frame`/`embed`/`object`, or any `.html` path however it was made, gets a small plain 404 document naming the missing file instead of a JSON blob; ordinary asset misses keep their JSON shape. The annotate **catch-all** applies the same 404 document, but only when BOTH conditions hold (`isFramedEmbeddedDocumentRequest` = `isFramedFetchDest` && `pathNamesEmbeddedDocument`, `packages/shared/html-assets.ts`, vendored to Pi and used by both runtimes): the destination is framed, AND the path is not `/` and either its last segment carries an extension (`/prototype-slash.html`) or it sits under a directory segment (`/assets/frame`). `/` and a bare single-segment word (`/settings`) are served the app as always, so a framed session URL and any future SPA route cannot 404. The rule keys on the **shape of the path, not `Sec-Fetch-Site`**: an annotated page is a sandboxed srcdoc with an opaque origin, so its nested-document requests are `cross-site` — the same value the VS Code webview wrapper produces, and `none` on both sides for a pasted URL — so site can never separate the two, while the path can, because the app only ever loads at `/` and a relative embed is anchored at `/api/html-assets/<token>/` by the `<base href>` (with its own 404); only a root-relative embed reaches the catch-all at all. Scoping it this way is the #1561 regression fix: the VS Code extension renders the session URL inside an `<iframe>` behind its cookie proxy (`apps/vscode-extension/src/panel-manager.ts`, `cookie-proxy.ts`, which forwards headers verbatim) and every subcommand launched from a VS Code terminal is routed there by `PLANNOTATOR_BROWSER`, so the unscoped guard made an annotate session opened from the editor show "404 Not found" and its one auto-reload 404 again. A NON-framed request for a missing path is untouched and still gets the app, exactly as before #1561. Plan and review servers carry no such guard.

*Pinpoint on an embed.* The bridge is **never** injected into a nested frame, so an embed is one pinpointable element from the outer page's perspective. While pinpoint is armed, frames are `pointer-events: none` (`body[data-plannotator-frame-inert]`, set by `updatePinpointCursor` for srcdoc sessions only — live-app sessions are untouched, since their nested frames belong to the user's app), which is what lets the click reach the outer document at all; hit-testing would then pass through to the container behind, so `preferInertFrameAt` resolves a point inside a frame's own rect back to the frame. Interact (`Esc`, the header pen, `Mod+Shift+A`) restores native interaction inside the embed — which is also the only state a link inside an embed can be followed from, exactly like the rest of this surface. An embed carries no text, so it takes the text-less media anchor rule (see "Element context" above): the comment and its element context (tag, ancestor path, the frame's `title` as the accessible name) are recorded and exported, and the placed marker restores across a reload or an HTML Refresh through the frame's `id` / `data-testid`, or else through its `src` when no other frame on the page shows the same source (`proto.html?step=1` and `proto.html?step=2` are different sources); two frames with one source fail closed and do not restore. Text-carrying pins on the page around it restore normally.

*Portable export and share links.* Embeds do not travel. `inlineHtmlLocalAssets` inlines assets as `data:` URLs but a sibling document is a second page with its own relative assets, so it is not inlined; instead a document that contains any frame gets `<base href="about:blank">`, which makes its embeds render **empty** rather than resolving onto the share portal's own catch-all and reproducing this bug there. Everything else about a share link is unchanged.

Known limitations: printing a raw-HTML annotate session prints highlight stripes from a best-effort absolute-coordinate layer and is degraded inside the iframe (pre-existing); element-only targets (SVG anchors, multi-select additional element targets) have no print representation. Annotation undo/redo listeners live in the parent document, so they are unavailable while focus is inside a raw-HTML or live-app iframe; the framed page keeps its own `Mod+Z`. Focus the editor chrome or annotation panel first. Forwarding this safely would require synchronizing parent history availability without stealing native or live-app undo; only the two reserved chords are currently forwarded: `Mod+Shift+A` (annotate toggle) and `Mod+Shift+X` (show/hide tools).

## Question blocks

An agent can ask the reviewer a question inside a plan or document with a `:::question` (pick one), `:::question-multi` (pick any) or `:::question-text` (free text) directive; the reviewer answers on a card in place. Approved design: a spec plus the owner's approval, which overrides it (design record, not in this repo). Shipped as core+ui (#1637), editor (#1638) and the agent side (prompt, skill, archive, WebMCP).

- **Grammar and data** live in `@plannotator/core/question-block` (shim `packages/shared/question-block.ts`, vendored to Pi): `parseQuestionBlock` (tolerant, returns null rather than throwing; an unparseable block falls back to the ordinary `Callout`), `indexQuestionBlocks`, `questionKey` (`q-` + hash8 of kind + prompt, so a reworded prompt is a new question), `QuestionAnswer` + the fail-closed `parseQuestionAnswer`, `questionStatus`, `formatQuestionAnswersSection`, and `QUESTION_AUTHORING_GUIDE`. `- [x]` means **settled** (the agent's echo of an earlier answer), `Recommended:` names the recommendation, "Other…", note and skip are always offered, and nothing is required. A `Replaces: <message id>/<key>` line (the Inbox's replaced questions) is read into `replaces` only when every token on it is id-shaped; it is then never the prompt or context and does not change the key, and any other `Replaces:` line stays prose. A picked label is kept whole: `parseQuestionAnswer` caps each `selected` label at `MAX_QUESTION_SELECTED_CHARS` (the body cap), never at the 200-character `MAX_QUESTION_CHOICE_LABEL_CHARS` (that one only shortens a plain-bullet label at a sentence end), because task-list labels are never cut and a shorter cap made a long choice unpickable (the Inbox answered `422 … is not one of the question's choices`; fixed after 0.28.17). `canonicalQuestionAnswer` maps an answer cut at 200 by an older build back to its one choice.
- **An answer is one annotation** (`Annotation.questionAnswer`, id `ann-question-<key>`), so drafts, reload, undo, the panel and host persistence carry it with no second store. The highlighter skips these rows; every exporter prints them first under "Answers to your questions" (with an "Unanswered" list) and excludes them from the numbered feedback count. The editor adds the "N/M answered" header chip, the Questions section in the annotations panel, and plan review's **Send answers** primary of the decision control (`isAnswersOnlyFeedback` in `packages/editor/questionDecision.ts`; see "Plan review header decision control").
- **`plan.answered`.** Send answers posts `/api/deny` with `answersOnly: true` (`planDenyFeedbackFields`) and an unframed export. Both plan servers pass the flag onto the decision only when it is boolean `true`; every plan-deny consumer (the Claude Code / Codex / Gemini / Copilot / Vibe hook outputs and the `opencode-plan` JSON in `apps/hook/server/index.ts`, OpenCode 1 and 2 through `submit-plan-executor.ts`, Pi's `index.ts`) builds its message with `composePlanDeniedMessage` (`packages/shared/prompts.ts`), which picks `prompts.plan.answered` (default `DEFAULT_PLAN_ANSWERED_PROMPT`: "The user answered the questions in your plan…", plus the remove-or-`[x]` resubmit rule) for an answers-only deny and the unchanged denied prompt otherwise. A custom `plan.denied` does not replace the answered prompt. A deny that mixes answers with comments or edits keeps the denied prompt. Compatibility: a server that predates the flag ignores it and wraps the same export in its denied prompt; an older UI never sends it.
- **Claude Code's classic hook drops answers on Approve** (its allow carries no message), so its plan server advertises no approval notes and the only approve row with answers waiting is "Approve, discard N answers…", whose confirm names Claude Code. The Claude Code mod delivers them ("Approve with notes"). No workaround for the classic hook (owner decision 1).
- **Agents learn the syntax** from the `plannotator` skill's "Asking the reviewer questions" section, which must equal `QUESTION_AUTHORING_GUIDE` byte for byte (`apps/hook/server/plannotator-skill-reference.test.ts` fails otherwise: edit the guide, then paste it into the skill), from the opt-in PFM reminder, and from the `plan.answered` prompt itself.
- **Feedback archive** records the validated answer per annotation as the additive `questionAnswer` field (`packages/shared/feedback-archive.ts`). Plan decisions archive no annotations array (pre-existing), so plan answers archive only inside `feedback`; annotate surfaces carry the structured field.
- **WebMCP** exposes questions read-only: `read_document` returns `questions` (number, key, kind, prompt, context, section, options with recommended/settled, status, the answer and its annotation id; orphaned answers with `q: null`) only when the document has any, and answer rows in `annotations` carry `answersQuestion`. No tool writes an answer, agent comments never carry `questionAnswer`, and `POST`/`PATCH /api/external-annotations` drop the field (owner decision 5).
- **Not covered in v1:** raw HTML, live apps, diagram files, code review, share links (an answer shares as a plain comment), and carrying answers across a resubmit other than through the agent's `[x]` echo.

## WebMCP (browser-agent tools)

The design document lives outside the tree (it is not checked in); the user-facing reference is `apps/marketing/src/content/docs/reference/webmcp-tools.md`. Phase 1 makes plan review and every annotate surface a WebMCP **provider**: a browser-integrated agent (Chrome/Edge origin trial, `chrome://flags/#enable-webmcp-testing` or `--enable-features=WebMCPTesting` locally; agent-embedded browsers unflagged) calls in-page tools instead of scraping the DOM. Code review (phase 2) and consuming the annotated app's own tools (phase 3) are not built.

**Shape (mirrors the shortcut system).** Engine in `packages/ui/webmcp/`: `modelContext.ts` is the ONLY file that spells `document.modelContext`, `registerTool`, `getTools`, `executeTool`, `toolchange` and the annotation hints (local structural types, no `webmcp-types` dependency, no `declare global`); `toolset.ts` (tool specs, the `{ ok, data, nudges, error? }` envelope, `runTool`, a per-document registry with reconcile-by-name and one `AbortController` per tool, since unregistration is only by abort); `changes.ts` (per-annotation `seq`, tombstones, per-tab watermark with `since` override, `claimOwn` so the agent's own writes are never "new" to it); `nudges.ts` (the twelve codes: `annotations_new`, `annotations_removed`, `replies_new`, `composer_open`, `source_stale`, `document_edited`, `comment_only_surface`, `page_changed`, `other_document_active`, `pending_unsent`, `session_decided`, `truncated`; messages are static strings, document and comment text never enter a message); `useToolset.ts` (React hook; handlers read through refs so a re-render never touches `registerTool`); `policy.ts` (the `webmcp` seam on `configurePlannotatorUI`, `{ enabled, namePrefix }`, default enabled with prefix `plannotator.`). Catalog in `packages/editor/webmcp/`: `documentTools.ts` builds the tools over a narrow `DocumentToolAdapter` (never imports App), `documentText.ts` holds the pure outline / windowing / quote-resolution helpers, `useDocumentWebMcp.ts` builds the adapter over App state through one ref.

**What is exposed.** `read_document` (the whole situation in one zero-argument call: session, text windowed at 16k chars cut at a block boundary with `textRange.nextOffset`, outline with per-section counts, every annotation with quote, context, `isNew` and thread ids, `otherDocuments`, nudges; `readOnlyHint` + `untrustedContentHint`), `add_comments` (1..20 items; anchoring cascade `inReplyTo` inherits the parent anchor, then `quote` resolved by text search with `section` to disambiguate, `ambiguous` returns candidate contexts, then `section` alone anchors on the heading, else a document-level note; `requestId` idempotency), `update_comment`, `remove_comments` (`destructiveHint`, ignored by today's dictionary on purpose), `reveal`, `nudge_user` (one transient banner, 280 chars, not persisted, not exported, dismissible), and `list_documents` in folder sessions only. Write tools are absent on archive and after the human's decision. Every tool-created comment is stamped `author` and `source: "browser-agent"` and renders exactly like an external-annotation comment.

**Rules.** (1) Decisions are human: there is no tool that approves, denies, submits feedback, closes the session, stages files or marks viewed, and there is no confirmation seam; the catalog test pins the names. (2) Ownership: the agent may update or remove only comments the tracker `claimOwn`ed in THIS page load (`AnnotationChangeTracker.isOwn`), never merely comments whose `source` reads `browser-agent`: `POST /api/external-annotations` accepts any `source`, so a stamp alone would let another tool's findings become agent-editable. Consequence: after a reload, the agent's earlier comments (restored from the draft) are read-only to it, like the human's; it replies instead. A `requestId` replayed after the human removed the comment it created answers `conflict` and never re-creates it. (3) Zero footprint without WebMCP: `resolveModelContext` runs once per mount; when `document.modelContext` is absent nothing is built, registered, rendered, fetched, scheduled or written. The opt-out is deliberately NOT a settings-registry entry: `configStore.ensureLoaded` seeds every registry default into a cookie on first settings access, on every surface including the guides.show viewer, so the preference lives in `packages/ui/webmcp/preference.ts`, is read lazily, and writes `plannotator-webmcp-tools=false` only when the user opts out (turning the tools back on removes the cookie). The phase-1 PR's A/B proof compared DOM shell, requests, console, timer counts and the cookie jar between the main and branch builds in a browser without the API and found no difference, and the portable viewer bundle is byte-identical to main. (4) Indicator policy: nothing visible appears merely because the API exists; only after the first successful tool call does the header show the small "Agent" affordance (`data-webmcp-indicator`). (5) Iframes: Plannotator never registers tools inside the untrusted frames, the srcdoc viewer keeps `sandbox="allow-scripts allow-modals"` with no `allow` attribute and the live-app iframe gets no `allow="tools"`, so a framed page cannot register or impersonate tools (`packages/ui/webmcp/iframeIsolation.test.ts` pins this at source level; in Chrome both frames answer `NotAllowedError` for `getTools` and `registerTool`). (6) Opt-out: Settings > General > "Agent tools" (row shown only when the API exists) aborts every registration when off. (7) No server changes: the Pi and OpenCode builds get the feature through the built HTML.

**Folder sessions.** `list_documents` walks the file browser's loaded directories (`fileBrowser.dirs`, absolute path = `${dir.path}/${node.path}`, vault dirs excluded) so every document is listed, not only the ones already visited. The agent learns that the human navigated from `document.path` on its next response, not from a sibling flag: siblings exclude the open path, and after a sidebar click `fileBrowser.activeFile` equals `linkedDoc.filepath`, so a sibling with `open: true` (and with it `openedSinceLastRead` and the "opened" branch of `other_document_active`) exists only transiently, during the load window between the click and the document commit. `reveal { path }` answers `not_found` at once for a path that is neither in the folder tree nor in the linked-doc cache; otherwise it navigates (folder sessions through App's file-browser selection handler, so the active file, the doc URL and the linked document stay in step) and WAITS for the commit that makes that path the open document (an effect settles the waiter, and the linked-doc `error` state settles it early when the load fails, so a bad path never runs out the 5s timeout) before looking the comment or section up; reading state right after the `await` would see the pre-navigation document. After a tool mutation the adapter overlays the pending write on the last committed annotation list (`applyOverlay`) so the response's nudges and the new comment's `seq` reflect the mutation even though `setAnnotations` has not committed yet; the agent's own removals are claimed (`claimRemoved`) so they are never reported back to it as `annotations_removed`. Still not reachable in phase 1: `composerOpen` for a sibling (the composer is detected from the DOM of the open document only, so `other_document_active` never fires for a composer in another document), and writes to a sibling that is not open (see below).

**`inReplyTo`.** One additive field on `Annotation`: a reply inherits its parent's anchor, renders indented under it in the annotations panel (`threadReplies` in `AnnotationPanel.tsx`), and exports nested under the parent's entry (`**Replies:**` block in `exportAnnotations`); an annotation without it renders and exports byte-identically to before. The threading rule is shared (`resolveReplyParents` in `packages/core/annotation-threads.ts`): an annotation is a reply only when its target is a different annotation in the same list and the parent chain never returns to it; orphans, self-references, and every member of a cycle render and export as roots in original order, so nothing is ever dropped and the export's header count equals what is emitted. `PATCH /api/external-annotations` refuses an `inReplyTo` that is self, missing, or would close a cycle (`validateReplyTarget`, both runtimes, `400`). Drafts carry it (annotations are opaque JSON to the draft transport); share links deliberately do not (a reply shares as a plain comment on the same quote, the existing text-restore contract, pinned by `sharing.inReplyTo.test.ts`). Known limitation: comments on a sibling document that is not open answer `not_available` with a hint to `reveal { path }` first, because the linked-doc cache is a copy.

Docs: `apps/marketing/src/content/docs/reference/webmcp-tools.md` (the user-facing reference) and the manual five-flow checklist in `tests/UI-TESTING.md`.

## Keyboard Shortcuts

**Location:** `packages/ui/shortcuts/` (engine + scope data), `packages/editor/shortcuts.ts` and `packages/review-editor/shortcuts.ts` (per-app surfaces).

The shortcut system has three layers:

1. **Engine** (`packages/ui/shortcuts/{core,runtime}.ts`) — parser for declarative bindings (`Mod+Enter`, `Alt Alt` double-tap, `Alt hold`), dispatcher, platform-aware formatter (mac glyphs vs. `Ctrl`), validator, and the `useShortcutScope` / `useDoubleTapShortcuts` React hooks. Truly shared — both apps use it as-is.
2. **Scopes** — `defineShortcutScope({ id, title, shortcuts: { actionId: { bindings, description, section, ... } } })`. One scope per UI surface (annotation toolbar, comment popover, file tree, etc.). App-specific scopes live in `packages/ui/shortcuts/{plan-review,code-review}/` — **the subfolder names which app's UI the scope serves** — while genuinely cross-app scopes such as `history.shortcuts.ts` and `decisionControl.shortcuts.ts` (the header decision control's note-composer chords, mounted identically by both apps) live at the shortcuts root. Components/Apps wire handlers to a scope via `useShortcutScope({ scope, handlers: { actionId: () => ... } })`.
3. **Surfaces** (`packages/editor/shortcuts.ts`, `packages/review-editor/shortcuts.ts`) — each app composes its scopes into a `ShortcutSurface` (`planReviewSurface`, `annotateSurface`, `codeReviewSurface`). Surfaces feed both the in-app help modal and the marketing site's auto-generated docs page.

**Convention for adding new shortcuts:** define the action in the relevant app-specific subfolder (`plan-review/` or `code-review/`), or at the shortcuts root when both apps share the same action and semantics. Declare the binding(s) and description, then wire a handler at the call site with `useShortcutScope`. The marketing docs page picks it up automatically at next build. Unit tests in `packages/ui/shortcuts.test.ts` enforce normalized binding tokens (`Mod`, `Shift`, `Alt`, `A-Z`, `1-0`, named keys, `F1`–`F12`) and unique scope ids.

**The Inbox** (`packages/inbox/shortcuts/`) composes its own surface the same way, `inboxSurface` (`inbox-search` ⌘K, `inbox-thread` E / Z, `inbox-file-viewer` Escape's ladder, `]` `[` `→` `←` and the full-screen ⌘⇧X, which reuses the html-annotate binding), wired with `useShortcutScope` (which takes `capture: true` for a guard that must run before the focused component, and `target: 'document'` for a rung that runs after the element handlers but before the window's). Its scope data lives with the Inbox, not in `packages/ui/shortcuts/`, because its `when` rules read the Inbox's DOM; the rules every Inbox key shares (typing, IME composition, repeat, ⌘ / Ctrl / Alt, a modal or the image annotator over the window) are in `packages/inbox/shortcuts/guards.ts`. `packages/inbox/shortcuts.test.ts` validates the registry and pins the only bare letters to E and Z (the owner's rule: no new Inbox letter keys until the shared system lists them). Not listed by the marketing page or a help modal yet; the Inbox keys still on hand-written listeners (Escape closing the thread, j / k / n, ⌘B) are named at the end of its `index.ts`.

**Marketing docs auto-generation:** `apps/marketing/src/lib/shortcutReference.ts` reads the three surfaces and `apps/marketing/src/components/ShortcutReference.astro` renders them as tables. The `/docs/reference/keyboard-shortcuts` page is special-cased in `apps/marketing/src/pages/docs/[...slug].astro` to render the component instead of the markdown body.

## URL Sharing

**Location:** `packages/ui/utils/sharing.ts`, `packages/ui/hooks/useSharing.ts`

Shares full plan + annotations via URL hash using deflate compression. For large plans, short URLs are created via the paste service (user must explicitly confirm).

**Payload format:**

```typescript
// Image in shareable format: plain string (old) or [path, name] tuple (new)
type ShareableImage = string | [string, string];

interface SharePayload {
  p: string; // Plan markdown
  a: ShareableAnnotation[]; // Compact annotations
  g?: ShareableImage[]; // Global attachments
  d?: (string | null)[]; // diffContext per annotation, parallel to `a`
  s?: (string | undefined)[]; // source per annotation (external tool identifier), parallel to `a`
  h?: string; // Raw HTML content (direct HTML rendering mode)
  r?: 'html'; // Render mode flag (omitted = markdown)
}

type ShareableAnnotation =
  | ["D", string, string | null, ShareableImage[]?] // [type, original, author, images?]
  | ["C", string, string, string | null, ShareableImage[]?] // [type, original, comment, author, images?]
  | ["G", string, string | null, ShareableImage[]?]; // [type, comment, author, images?]
```

**Compression pipeline:**

1. `JSON.stringify(payload)`
2. `CompressionStream('deflate-raw')`
3. Base64 encode
4. URL-safe: replace `+/=` with `-_`

**On load from shared URL:**

1. Parse hash, decompress, restore annotations
2. Find text positions in rendered DOM via text search
3. Apply `<mark>` highlights
4. Clear hash from URL (prevents re-parse on refresh)

Known limitation: share links intentionally do not carry HTML element anchors or additional multi-select targets. Restore on the raw-HTML surface is text-search based; this is the contract asserted by `sharing.multiTarget.test.ts`.

## Settings Persistence

**Location:** `packages/ui/utils/storage.ts`, `planSave.ts`, `agentSwitch.ts`

Uses cookies (not localStorage) because each hook invocation runs on a random port. Settings include identity, plan saving (enabled/custom path), and agent switching (OpenCode only).

## Syntax Highlighting

There is **one** highlighter in the app: the Shiki instance `@pierre/diffs` already runs for the code-review diff pane, driven by Shiki's **JavaScript regex engine** (`preferredHighlighter: 'shiki-js'`). `highlight.js` is gone. The wrapper is `packages/ui/utils/codeHighlight.ts`:

- `applyHighlight(el, code, lang, theme)` — imperative drop-in for the old `hljs.highlightElement(el)`. Writes plain text immediately (final size on first paint, no layout shift), then swaps in highlighted markup once the grammar is attached; already-attached grammars highlight synchronously, so there is no flicker on cached highlights. It also enforces that the rendered text is byte-identical to the source and falls back to plain text otherwise, because the annotation layer addresses code blocks by text offset.
- `highlightToHtml(code, lang, theme)` / `ensureHighlight(lang, theme)` — the sync/async pair behind it, for callers that need HTML strings (the code-file hover preview).
- `codeBlockClassName(lang)` — the `pn-code font-mono language-{lang}` class every fenced `<code>` carries. **`pn-code` replaced the old `hljs` class** and is the structural hook `blockTargeting`, vim navigation and `print.css` use (`pre > code.pn-code`); `language-*` is how `blockTargeting` reads a block's language back out of the DOM.
- `onCodeHighlightSwap(listener)` — observes every write `applyHighlight` makes, SYNCHRONOUSLY, immediately after it. Each write replaces the element's children, so it also destroys whatever the annotation layer wrapped inside the fence.

**Code-block annotation marks and highlight swaps.** `web-highlighter` cannot select inside a `<pre>`, so a fenced block is annotated all-or-nothing: one `<mark data-bind-id>` that is the `<code>` element's only child, painted by `paintCodeBlockMark` (`packages/ui/utils/codeBlockMark.ts`) — which MOVES the token spans into the mark rather than flattening them to text, so annotating or re-theming a block never costs it its colours. `Viewer` subscribes to `onCodeHighlightSwap` and re-paints that mark right after any swap, which is what keeps a palette or dark/light change from wiping code-block annotations. Being driven by the swap is also what makes the share/draft restore race safe **by ordering rather than by timing**: a restore that painted before the swap is re-established in the same task the swap ran in, and one that runs after finds the mark already there. Do not "fix" a mark-eating swap by skipping the rewrite when a mark is present — that leaves annotated blocks in stale theme colours.

**Language-less fences render as plain text and are never guessed at (#1212). There is no auto-detection anywhere.** `HighlightedCode` (review suggestions) derives its language from the caller's file path via `detectLanguage`; an unrecognised extension renders plain.

**Theming:** fences resolve the SAME theme the diff pane resolves, via `resolveFenceTheme` / `resolveSyntaxTheme` in `packages/ui/utils/syntaxTheme.ts` (keyed on `(colorTheme, resolvedMode)`; `packages/review-editor/hooks/usePierreTheme.ts` re-exports them). `useFenceTheme()` (`packages/ui/hooks/useFenceTheme.ts`) feeds the components and re-highlights on palette or mode change. Palettes with no Shiki counterpart fall back to `@pierre/diffs`' own `pierre-dark` / `pierre-light`. Consequence: code blocks follow the active palette in both light and dark instead of always rendering github-dark, so **do not add per-theme `.hljs-*`-style token CSS** — pick the right Shiki theme in `SHIKI_THEME_MAP` instead.

**Mermaid runtime (12.x, lazy):** `@plannotator/ui` pins `mermaid` exactly (12.0.0 since ui 0.40.0; Mermaid 12 lays flowchart/state/class/ER/requirement diagrams out with ELK by default and targets Safari 17.4+ / ES2024 — we take its defaults rather than pinning the 11.x ones). The runtime is loaded lazily on the first diagram through `packages/ui/utils/mermaid.ts`'s own `import('mermaid')`: `packages/editor/App.tsx` deliberately does NOT import `@plannotator/ui/utils/mermaid-eager` (it did through ui 0.39.0), so a plan with no diagram never downloads the ~2 MB runtime + ELK on the share portal or in a host build, and `tests/entry-assets.test.ts` fails if the eager import creeps back into either app. The single-file builds (`apps/hook`, `apps/review`, opencode, the compiled binary) still inline the runtime through `inlineDynamicImports`, so the lazy import saves nothing there and resolves from the bundle itself; the Mermaid 12 cost in those builds is the runtime's own growth. `MermaidBlock` shows the source fence under a "Rendering diagram" status until the first render lands (never the error panel as a placeholder), and `applyMermaidTheme` is keyed on the runtime object, so the lazily loaded runtime is themed on its first render exactly like an eagerly registered one. `mermaid-eager` stays exported for hosts that want the old startup registration. Labels wrap at 140 px (`MERMAID_LABEL_WRAP_WIDTH`, set as `flowchart.wrappingWidth` and `state.wrappingWidth` in `MERMAID_CONFIG`, which the themed config spreads; owner-approved for #2064): Mermaid 12's default of 120 px (11 used 200) split labels of about eight CJK characters at Plannotator's 16 px.

**Diagram engine (ui 0.41.0):** every Mermaid and Graphviz diagram renders through ONE renderer slot and ONE canvas, the viewer moved in from Workspaces (owner ruling: the new engine, not an option). `MermaidBlock` and `GraphvizBlock` are thin wrappers over `packages/ui/components/DiagramBlock.tsx`, which keeps the fence side (`diagramLanguages.ts`, the pending fence under "Rendering diagram…", the error panel with the source, the per-engine Retry epoch, the Show-source toggle, the natural-height box) and renders `DiagramViewer` (`packages/ui/components/diagram/`) inline and again at full size in `DiagramPopout` (the `TablePopout` chrome; one code path). The renderer slot is `packages/ui/utils/diagram-render.ts`: `renderDiagram(kind, renderId, source, theme)` loads the engine through its runtime slot (`utils/mermaid.ts` as before, with `applyMermaidTheme` per (palette, mode) before every render; `utils/graphviz.ts`, new, the same shape, `@viz-js/viz` pinned exactly `3.30.0`), sanitizes the output into a NODE (`sanitizeDiagramSvg` = DOMPurify `parseDiagramSvg` + the in-place `scrubDiagramSvg` belt: no script, no `on*`, no `javascript:`/`data:` reference, no `<a href>` — a Mermaid click binding must never turn a pinpoint click into a navigation), and pairs it with the engine's finder (`utils/diagram-anchor.ts` for Mermaid's id grammar, `utils/diagram-anchor-graphviz.ts` keyed on `g.node > title`, never `nodeN`). A load failure is a value (`runtimeUnavailable: true`), which is the one failure Retry can change; one automatic re-attempt runs after the slot's retry delay. The canvas (`DiagramCanvas`) mounts the node with `replaceChildren` inside a CSS-transformed wrapper — wheel/drag/`+`/`-`/`0`/arrow keys; click-to-select vs drag-to-pan on a pointer-type-aware threshold (4 px mouse, 10 px finger); NO hover targeting on a plain mouse-over (owner ruling: it read as messy and fought the pan hand — the ring under the pointer appears only while the platform modifier is held, `isModKeyHeld`, and disarms on its release, on any other key, and on blur); canvas keys ignore Meta/Ctrl/Alt so browser chords pass through; inline the canvas is `touch-action: pan-y` (a finger scrolls the page past it) and only the popout is `touch-none`; the zoom strip is `data-print-hide` while rings and badges print. Every edge gets an invisible 14 px hit path in ONE layer appended last in the svg root (`widenEdgeHitAreas`: bare geometry, ancestors' transforms composed, no id/class/`data-*`, `diagramHitSource` maps it back) — measured in Chromium, the only thing painted over an edge is its OWN label box, centred on its midpoint, so a label is a target that resolves to its edge, and because the hit layer sits over the nodes the canvas resolves a click by PRIORITY over `elementsFromPoint` (node, then edge, then cluster), never by `event.target`. A click that resolves no part comments on the WHOLE diagram (kind `diagram`), so a click never does nothing. The scrub also scopes every `<style>` to rules under the svg's own root id (`scopeDiagramCss`: no `@import`, no fetching `url(`, no rule that could restyle the page). And the overlay (`DiagramOverlay`) reprojects rings and badges from `getBBox` through `getScreenCTM` each frame (`utils/diagram-projection.ts`), so they keep constant pixel size at every zoom. `components/mermaidSvg.ts` is gone. Under happy-dom DOMPurify is not functional (foreign-realm fragment, mislabelled svg namespaces, a cached `Node.prototype.nodeName` getter), so DOM tests swap the parse step for an inert XML parse through `__setDiagramSvgParserForTests` (`packages/ui/test-setup/diagramSvg.ts`) while the scrub still runs; the DOMPurify parse is proven in Chromium (the parity run in the PR that landed it). Real rendered svgs for the codec tests live in `packages/ui/test-setup/fixtures/diagrams/` with Chromium-measured geometry beside them.

**Diagram theming (Mermaid):** diagrams follow the palette and mode the same way fences do, through ONE dynamic mapping rather than per-palette themes. `packages/ui/utils/mermaidTheme.ts` reads the live CSS tokens off the document element (`readThemeTokens`: `--background`, `--foreground`, `--card`, `--border`, `--muted`, `--muted-foreground`, `--primary`, the accent tokens, `--font-sans`), derives a complete Mermaid `themeVariables` set for every diagram family from them (`buildMermaidThemeVariables(tokens, mode)`, pure; base theme `dark` under a dark resolved mode, `default` under light; node fill from `card`, borders from `border`, edges and arrowheads from `muted-foreground`, text from `foreground`/`card-foreground`, clusters from `muted`, twelve categorical fills for pie/git/mindmap/journey seeded from `primary`, `accent`, `success`, `warning`, `destructive` and normalized to one lightness per page polarity), and `MermaidBlock` runs the global `mermaid.initialize` through `applyMermaidTheme` once per `(palette, mode, shadow amount)` key from `useTheme()` before each render, re-rendering mounted diagrams when the key changes. Every colour handed to Mermaid is opaque hex (its colour library does not read `oklch()`), and a contrast guard (`ensureContrast`) repairs any text-on-fill pair under WCAG 4.5:1 or line-on-canvas pair under 3:1 (plus 0.1 headroom) by the smallest OKLab step toward `foreground`, then `background`, then pure black/white — guarding page-level text and lines against every surface they can cross (the `bg-muted/30` canvas over the document card and over the bare page, `card`, `muted`, `popover`, ER rows), not the page background alone; `mermaidTheme.test.ts` sweeps every palette in `packages/ui/themes` in both modes against that rule, so a new palette cannot regress it. The pure toolkit behind it is `packages/ui/utils/cssColor.ts`. **Node shadow:** Mermaid 12's neo look shadows every node, cluster and actor from its own fixed `drop-shadow(1px 2px 2px rgba(185,185,185,1))` grey, which reads as a halo on a themed page. The look is kept and that one filter is replaced: `buildMermaidThemeVariables` sets `themeVariables.dropShadow` from `buildMermaidShadow(ground, amount)` at `DEFAULT_MERMAID_SHADOW_AMOUNT` (**0.7**, i.e. 70 on the user-facing 0-100 scale, where 100 reproduces Mermaid's own geometry exactly and 0 publishes `dropShadow: false` — plus `nodeShadow: false`, the only thing that reaches a state diagram's inline-filtered start/end dots — which the neo rules render as `filter: none`). The colour is derived from the palette's own ground and its POLARITY follows the page, the same way Mermaid's `insertLookDefs` picks a white flood colour on dark themes: on a dark page the ground lifted 82% toward white at alpha `0.18 + 0.72a`, on a light page darkened 40% toward black at `0.25 + 0.3a`, each asserted to differ from the ground in the direction that reads (white/black as the fallback, Mermaid's grey when the palette yields no usable ground). A black shadow on a near-black ground is a valid filter that paints nothing, which is why polarity — not just alpha — follows the page. The amount is the cookie-only `diagramShadow` setting (Settings → Display → "Diagram Shadow", steps 0/40/70/100, `packages/ui/utils/diagramShadow.ts`), which rides into the renderer as `DiagramTheme.shadowAmount` and into the cache key; at the default the key is byte-identical to the old `(palette, mode)` one. It is a paint-time filter only: fills and label colours are identical at every amount (pinned in `mermaidTheme.test.ts`). **Host fallback:** with no theme tokens on the document `readThemeTokens` returns `undefined` and the runtime keeps the static `MERMAID_CONFIG` (still `securityLevel: 'strict'`, pinned) with no extra `initialize`, so a host without `ThemeProvider`/`theme.css` renders exactly as before — that config carries the same 70 geometry with a fixed light shadow colour, since its own slate theme is dark. A host that wants Mermaid's grey back sets its own `themeVariables.dropShadow` after ours; one that wants no shadow passes `shadowAmount: 0`. Do not add per-palette Mermaid themes or per-theme `.mermaid` CSS — extend the token mapping instead. Graphviz has no theme system, so the renderer slot's `themeGraphvizSvg` recolors the DOT DEFAULTS onto the tokens after the scrub (the white page polygon removed, `fill="none"` → `var(--card)`, default black strokes → `var(--foreground)` on nodes and edges and `var(--border)` on clusters, `lightgrey` → `var(--muted)`, text → `var(--foreground)`) and leaves every author color alone; it needs no per-palette equivalent.

**Printing (light half, one rule):** paper is white, so the whole page prints in
the **LIGHT half of the user's pair** — prose, code and diagrams together.
`ThemeProvider` forces `preferredMode` to `light` while printing
(`packages/ui/hooks/usePrintMedia.ts`), which flows through the existing
`applyThemeClasses` and, because `applyMermaidTheme` is keyed on
`(palette, mode)`, re-renders every mounted diagram in the light palette;
Graphviz follows with no re-render at all, since `themeGraphvizSvg` paints
`var(--*)` tokens. Two signals drive it, because neither covers every path:
`beforeprint` / `afterprint` (a real Cmd+P and print preview — the class write
happens INSIDE the handler, since the print snapshot is taken before React
would flush a state update) and a `matchMedia('print')` change (headless
`page.emulateMedia({ media: 'print' })`, where the async diagram re-render also
lands). The stored preference is never written, and a light-mode user sees no
change. `usePrintMode` shares the subscription, so `.plannotator-print` is
applied under print emulation too.

`print.css` exempts diagram content from its typography rules with
`:not([data-diagram-block] *)` on the blanket `body, div, span, p, …` selector
and its `strong` / `em` / `p` siblings. A diagram colours itself and its own
`<style>` carries no `!important`, so the blanket rule beat it: Mermaid 12
draws node and edge labels as real HTML inside `<foreignObject>`
(`span.nodeLabel > p`, `span.edgeLabel`), which is how a dark-palette flowchart
used to print as empty boxes — near-black text on a near-black node fill. The
zoom strip stays `data-print-hide`; rings and badges still print.

**Bundle note:** Pierre imports Shiki's full bundle, so every grammar and theme is already inlined in the single-file builds; reusing its shared highlighter costs no extra bytes and needs no CDN or runtime wasm fetch. The Oniguruma WASM engine is dead weight under `shiki-js` and is aliased to `build/shiki-wasm-stub.ts` in the review, hook and portal Vite configs (via `resolve.alias`, which — unlike `plugins` — is shared with Vite's worker build).

## Requirements

- Bun runtime
- Claude Code with plugin/hooks support, or OpenCode
- Cross-platform: macOS (`open`), Linux (`xdg-open`), Windows (`start`)

## Development

```bash
bun install

# Run any app
bun run dev:hook       # Hook server (plan review)
bun run dev:review     # Review editor (code review)
bun run dev:portal     # Portal editor
bun run dev:marketing  # Marketing site
bun run dev:vscode     # VS Code extension (watch mode)
```

**Local `plannotator` command:** run `bun link` once in the checkout to make the global `plannotator` command use this repo's source (`apps/hook/server/index.ts`) instead of an installed release binary. Commands like `plannotator review` then reflect local changes immediately. Rebuild the bundled HTML when changing UI code (see Build below).

## Testing Rules

A test must guard a behavior that can actually regress. Before writing one, name the failure it catches; if you can't, don't write it.

- **Pin copy only on purpose, never as a snapshot.** Locking a short user-facing string is legitimate when it is a deliberate decision — an action label ("Approve"), a command name, a legally/UX-critical phrase the maintainer wants frozen so agents can't drift it. Mark it as such in a comment. What is banned is incidentally snapshotting explanatory prose (intro dialogs, setting descriptions, empty-state copy) with `toBe` just because it was on screen when the test was written — that couples wording edits to test churn while guarding nothing. If such a string carries data that must stay truthful (a server-computed size, a language list, a version), assert those facts with `toContain` on the data, not the sentence around them.
- **No round-trip prop tests.** Asserting that a hardcoded string passed as a prop appears in the DOM verifies nothing — any string round-trips. If the only thing worth checking is "this prop renders somewhere," use a sentinel string and one assertion, and say so in a comment.
- **Assert behavior, not implementation echo.** A test that restates what the code obviously does (calls X with Y, sets state to Z) without exercising an observable outcome is noise; it breaks on refactors and catches nothing.
- **Bun runs every test file in one process.** Never mutate `process.env`, `~/.plannotator`, or any global at module scope; mutate inside tests with restore in `finally`/`afterEach`, and sandbox all server/data-dir interaction under a temp `PLANNOTATOR_DATA_DIR`. Never read or write the real user config.
- **Tests and dev scripts never reach the real Inbox or data dir.** Bun reads only the `bunfig.toml` of the folder `bun test` runs from, so the preload sandbox is mirrored into every folder people run tests from (`tests/package-bunfig.test.ts`), and the Inbox test helpers sandbox on import as well (`tests/setup/sandbox-data-dir.ts` does what the preload does: `PLANNOTATOR_DATA_DIR` becomes a fresh temp folder unless it already is a scratch folder, inside the OS temp dir or `/tmp` or the `PLANNOTATOR_TEST_SANDBOX` the preload marks). Only scratch folders count because a relocated data dir (`PLANNOTATOR_DATA_DIR=/custom` in the person's shell) is just as real as `~/.plannotator`; `tests/helpers/real-data-dir.ts` also works out the default like the product does, for both `$HOME` and the account's own home, `$XDG_DATA_HOME` included. Dev scripts that start an Inbox (`scripts/dast/target.ts`, `scripts/inbox-sim.ts`, `tests/helpers/inbox-dom-server.ts`) accept only a scratch data dir, and point `PLANNOTATOR_DATA_DIR` at it (the Inbox reads `config.json` through the env even when given `dataDir`). Signal an Inbox only through `tests/helpers/inbox-process.ts` (or `signalInbox` / `stopInbox` in `tests/helpers/inbox-world.ts`, `stopScratchInbox` in the e2e specs), never `process.kill` on a pid read from a registry; write `apps/hook/dist` stubs only with `tests/helpers/hook-dist-stub.ts`, which removes exactly the stubs it wrote and never the folder. `tests/never-touch-the-real-inbox.test.ts` scans every test and script (`tests/helpers/real-inbox-scan.ts`, comments stripped) for a signal in Inbox code (`process.kill`, a `kill`/`pkill` spawn or shell string, `kill` taken off `process`; a test's own non-Inbox child may carry an `inbox-guard: own child` comment), a path from the home dir to `.plannotator` (any line, a multi-line `join`, a variable from `homedir()`, the literal `~/.plannotator` used as a path), and a `startInboxServer` call without `dataDir` (or, in a script, without pointing `PLANNOTATOR_DATA_DIR` at it). The proof (`provenInbox`) also requires the test's folder to be a scratch folder and the Inbox's working directory inside it whenever it can be read.
- **Tests and dev scripts never open a browser, and never with a sentinel.** Set `NO_BROWSER` from `tests/helpers/no-browser.ts` (an absolute path to a program that exits at once: `/usr/bin/true`, `/bin/true` or `true` on PATH; `whoami.exe` on Windows), never `PLANNOTATOR_BROWSER=none` (or `true`, `false`, `0`, `1`, `:`). A current build opens nothing for those values, but a binary from before that change (the version matrix, an older installed `plannotator` a test may reach) reads them as unset (#756) and opens the system default, i.e. real tabs on the developer's screen; and a mistake in the "none" handling itself would do the same. The bun test preload sets `NO_BROWSER` for every test and every child that inherits the env; a spec or helper that builds a child env from scratch sets it itself. `tests/no-browser-sentinel.test.ts` scans tests, scripts, `package.json` files and the workflows for a sentinel value (`tests/helpers/no-browser-scan.ts`); a line that tests the sentinel handling (in process, or in a child whose PATH holds only stand-in openers, as `packages/server/browser-intent-launch.test.ts` does) may carry a `no-browser-guard: sentinel under test` comment.

## Build

```bash
bun run build:hook       # Single-file HTML for hook server
bun run build:review     # Code review editor
bun run build:opencode   # OpenCode plugin (copies HTML from hook + review)
bun run build:portal     # Static build for share.plannotator.ai
bun run build:marketing  # Static build for plannotator.ai
bun run build:vscode     # VS Code extension bundle
bun run package:vscode   # Package .vsix for marketplace
bun run build            # Build hook + opencode (main targets)
```

**Important: Tailwind `@source` paths.** When creating new directories that contain `.tsx` files with Tailwind classes, add a matching `@source` entry to the app's `index.css`. Tailwind only generates CSS for classes it finds in scanned files — missing paths means classes appear in the DOM but have no effect.

**Important: Build order matters.** The hook build (`build:hook`) copies pre-built HTML from `apps/review/dist/`. If you change UI code in `packages/ui/`, `packages/editor/`, or `packages/review-editor/`, you **must** rebuild the review app first, then the hook:

```bash
bun run --cwd apps/review build && bun run build:hook   # For review UI changes
bun run build:hook                                       # For plan UI changes only
bun run build:hook && bun run build:opencode             # For OpenCode plugin
```

Running only `build:hook` after review-editor changes will copy stale HTML files. When testing locally with a compiled binary, the full sequence is:

```bash
bun run --cwd apps/review build && bun run build:hook && \
  bun build apps/hook/server/index.ts --compile --no-compile-autoload-bunfig \
  --define "__CLI_VERSION__=\"0.0.0-dev\"" --outfile ~/.local/bin/plannotator
```

These are the flags `.github/workflows/release.yml` compiles with; without the `__CLI_VERSION__` define `plannotator --version` falls back to `plannotator dev` and the binary cannot be told apart from any other local build. On macOS build with bun >= 1.3.14 (what CI pins): 1.3.12 loses the linker signature and the compiled binary is SIGKILLed on launch with no error (#541).

Running only `build:opencode` will copy stale HTML files.

## Marketing Site

`apps/marketing/` is the plannotator.ai website — landing page, documentation, and blog. Built with Astro 5 (static output, zero client JS except a theme toggle island). Docs are markdown files in `src/content/docs/`, blog posts in `src/content/blog/`, both using Astro content collections. Tailwind CSS v4 via `@tailwindcss/vite`. Deploys to S3/CloudFront via GitHub Actions on push to main.

The `/docs/reference/keyboard-shortcuts` page is auto-generated from the shortcut registry at build time — see the Keyboard Shortcuts section above. Editing the markdown body has no effect; update the scope files instead.

## Test plugin locally

```
claude --plugin-dir ./apps/hook
```