@xingular/harness 0.1.7 → 1.1.1

package/docs/architecture/proposals/PROP-0014-fullscreen-browser-tabs.md

@@ -0,0 +1,58 @@
+---
+id: PROP-0014
+title: Full-screen resource browser with persistent section tabs
+status: Implemented
+created: 2026-10-23
+updated: 2026-10-23
+affects: [11-terminal.md, terminal-tui.md]
+---
+
+# PROP-0014: Full-screen resource browser with persistent section tabs
+
+Accepted by the user's request to implement the agreed plan on 2026-10-23.
+
+## Problem
+
+The browser's centered panel, section dropdown and wide sidebar consume space and hide
+navigation when inspecting a resource. The user requested a full-page screen with component tabs.
+
+## Affected rules
+
+The terminal guide states: “The browser keeps the centered dialog size policy.”
+This proposal replaces that browser layout contract. INV-TUI-1 through INV-TUI-6 remain intact.
+
+## Proposal
+
+Every resource-browser command opens the full terminal. Overview, Foundation, Variant, Skills,
+Plugins, Connections, Tools and Library occupy a persistent top tab strip. Narrow terminals
+show the active tab and previous/next navigation. Tab moves focus; arrows change the focused tab;
+mouse selection selects a tab directly. Each section retains search and resource selection.
+
+At 88 content columns, inventory and inspector share the screen; details, actions and content
+stay beside the list. Narrow screens show details and content within the active tab. Escape
+returns through content, inspection and search before closing. Other command pages retain
+centered presentation. Browser actions retain existing confirmations and protected services.
+
+## Alternatives
+
+Keeping the centered browser leaves insufficient working space. Full-width lists with replacement
+detail views hide useful context on wide terminals. A c1–c8 primary tab strip was considered;
+the user selected resource sections instead.
+
+## Consequences
+
+This is foundation UI behavior. TerminalPage gains optional presentation and direct tab selection.
+There is no server protocol, stored data, account, loader or gate change.
+
+## Migration
+
+Existing command destinations and resource state are preserved. No migration is needed.
+The UI change is reversible without touching stored data.
+
+## Checks
+
+Cover page geometry, keyboard and mouse tab selection, inspection, scrolling, responsive resize,
+shortcut destinations, and draft preservation. Run typecheck, tests, build, the isolated browser
+PTY suite and the consuming application's required checks. No real model requests are needed.
+
+Related decision: [ADR-0016](../../decisions/ADR-0016-fullscreen-browser-tabs.md).

package/docs/architecture/proposals/PROP-0015-one-capability-surface.md

@@ -0,0 +1,88 @@
+---
+id: PROP-0015
+title: One capability surface — the Harness terminal and every host offer the same capabilities
+status: Accepted
+created: 2026-10-23
+updated: 2026-10-23
+affects: [INV-BND-2, new INV-PAR-1..4, 00-overview.md, 11-terminal.md, new 14-surfaces-and-parity.md, AGENTS.md]
+---
+
+# PROP-0015: One capability surface
+
+Accepted by the user's approval of the parity plan on 2026-10-23. Related decision:
+[ADR-0017](../../decisions/ADR-0017-one-capability-surface.md).
+
+## Problem
+
+Two front ends sit on the same harness: the Harness-owned terminal (`xharness`) and the App.
+Capabilities a person uses grew in the App alone (web annotations, managed worktrees, agent
+organizations, delegated work), so the terminal cannot do what the App does, and a reader cannot
+tell which repository owns a feature. The App also carried an orchestration layer (agents as
+product objects, routed chats, group chats, a reporting tree, delegated work queues) that no other
+host could reuse and that was never verified in a running app.
+
+The owner decided on 2026-10-23 that the App is a richer presentation of the Harness and that the
+terminal and the App offer the same capabilities, with room reserved for future host-only
+surfaces such as interactive agent output ("OpenUI").
+
+## Affected rules
+
+- 00-overview "Stays in the application: agents, groups, conversations, tasks and coordination,
+  projects and worktrees, App browser UI and tab sharing, computer use, windows, the PTY, the
+  keychain, and application UI."
+- `INV-BND-2` lists "worktree" among application concepts.
+- 11-terminal describes the terminal as one frontend, with no parity obligation.
+
+## Proposal
+
+A new page, [14 Surfaces and parity](../14-surfaces-and-parity.md), states four invariants:
+
+- **INV-PAR-1** Every capability a person can use in a host is a Harness capability: a foundation
+  service, a `WorldPart`, or a first-party plugin, reachable through server methods. The standalone
+  terminal surfaces it. A host is a presentation of it.
+- **INV-PAR-2** A capability is complete only when its terminal surface and its host surface both
+  pass acceptance. It lands in the Harness first, together with its terminal surface.
+- **INV-PAR-3** A host-backed capability needs an operating-system object only a host has (a
+  WebKit tab, a native computer bridge, a keychain). The Harness defines its generic contract and a
+  terminal fallback. Without a fallback, the terminal shows the capability as unavailable with the
+  reason, in `/doctor` and `/tools`.
+- **INV-PAR-4** A host-only surface is presentation that cannot exist in a terminal. It owns no
+  capability: its actions are Harness methods or tools, its data lives in Harness records, the
+  terminal shows a text fallback, and each one is listed in the host's register by an owner
+  decision. A generic rich-output event for such surfaces needs its own proposal; the name is
+  reserved, nothing is designed.
+
+00-overview changes:
+
+- "Belongs in the harness" gains managed worktrees (PROP-0016) and page annotations (PROP-0017).
+- "Stays in the application" becomes: windows, the PTY, the keychain, native operating-system
+  bridges (WebKit tabs, computer control), presentation, and registered host-only surfaces.
+- `INV-BND-2` no longer lists "worktree" as an application concept once PROP-0016 lands.
+
+A non-binding register, [`docs/parity.md`](../../parity.md), lists every capability with its
+Harness owner, its terminal surface, its host surface and its status.
+
+## Alternatives
+
+- **Keep the App as the full product and the terminal as a developer tool.** Rejected by the owner:
+  it keeps two products and the ownership confusion.
+- **Strict identity of the two front ends.** Rejected: some presentation (rich panes, interactive
+  output) cannot exist in a terminal. INV-PAR-4 bounds that category instead.
+- **Do nothing.** The gap grows with every App feature.
+
+## Consequences
+
+- New user capabilities are Harness work first, with their terminal surface.
+- Hosts may still add tools through `ToolProvider`, but a tool a person relies on is either a
+  Harness capability or a declared host-backed capability (INV-PAR-3).
+- The server protocol gains method groups only through the proposals that add each capability.
+
+## Migration
+
+No stored data changes. Existing gaps are recorded in `docs/parity.md` with IDs (`PAR-NNN`) and
+closed one at a time.
+
+## Checks
+
+Documentation change. Link check of the edited pages; each later capability brings its own tests
+on both surfaces.

package/docs/architecture/proposals/PROP-0016-managed-worktrees.md

@@ -0,0 +1,156 @@
+---
+id: PROP-0016
+title: Managed git worktrees as a Harness capability, in the terminal and every host
+status: Implemented
+created: 2026-10-23
+updated: 2026-10-23
+affects: [INV-BND-2, D-5, INV-STO-3, INV-SRV-1, 00-overview.md, 02-sessions-and-runs.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0016: Managed git worktrees
+
+Accepted by the user's approval of the parity plan on 2026-10-23 (PROP-0015, ADR-0017).
+Implemented in the working tree on 2026-10-23: `src/worktrees/`, `Sessions.run`, `Terminals`,
+`xharness --worktree`, `xharness worktree`, `/worktree`; spec pages 00, 02, 10, 11, 12 updated.
+The App source has create integration; remaining App actions are tracked as PAR-012. Harness and
+terminal implementation is included in the 4.0.0 candidate. The owner chose the Codex model:
+managed, disposable worktrees with automatic pruning and a handoff back to the main checkout.
+
+## Problem
+
+Worktrees exist only in the App (`App/src-tauri/src/projects.rs`: `create_worktree`,
+`list_worktrees`), with no removal, so thread, task and Solo worktrees accumulate. The terminal
+runs in its launch folder only (`terminal/standalone.ts`), with no way to isolate a session's
+edits. `RunRecord.worktreeId` is an opaque App field (drift D-5). Under INV-PAR-1 a capability a
+person uses must be a Harness capability with a terminal surface.
+
+## Affected rules
+
+- 00-overview "Stays in the application: … projects and worktrees …".
+- `INV-BND-2` lists "worktree" as an application concept.
+- Drift D-5: `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts.
+- `INV-STO-3`: a new top-level folder is an architecture change.
+- `INV-SRV-1`: a new method group.
+
+## Proposal
+
+### Model
+
+A **worktree** is a linked git worktree of a repository (the *source checkout*) that the Harness
+created or adopted. It has an id, a repository root, a path, a name, a branch or a detached HEAD,
+the ref and commit it started from, a kind and an origin.
+
+- **Managed** worktrees (the default) are disposable, usually one per session, on a detached HEAD.
+  They are pruned automatically.
+- **Permanent** worktrees are named, may host several sessions, and are never pruned.
+- **Create branch** gives a worktree a branch under a configurable prefix (default `wt/`).
+
+### Creation
+
+`create({ repo, name?, baseRef?, kind?, carryChanges? })`:
+
+1. Resolve the source checkout's top level; refuse a folder that is not a git repository with at
+   least one commit.
+2. `git worktree add --detach <path> <baseRef>` (default `HEAD`), with repository filter drivers
+   switched off (`GIT_LFS_SKIP_SMUDGE=1`, `-c filter.lfs.*` cleared), never through a shell.
+3. When `carryChanges` (default true for `baseRef: HEAD`), apply the source checkout's
+   uncommitted tracked changes (`git diff HEAD --binary` piped to `git apply`) and copy its
+   untracked, non-ignored files, as Codex does.
+4. Copy ignored files matched by `.worktreeinclude` (gitignore syntax, matched by git itself). A
+   file is copied only when it does not exist in the worktree; symlinks are skipped; a per-file
+   (5 MB) and total (100 MB) cap applies; the result lists what was copied and skipped.
+5. Run the repository's setup script `.xharness/worktree-setup` when it exists and its exact text
+   is trusted by hash (`worktrees.setup.trust`). It runs with `HARNESS_WORKTREE_PATH`,
+   `HARNESS_WORKTREE_SOURCE`, `HARNESS_WORKTREE_NAME`, a 10-minute timeout, and its output in a log
+   file. An untrusted script is reported, never run.
+
+### Lifecycle
+
+- **Lease and lock.** A session that runs in a worktree holds a lease (session id, process id) and
+  `git worktree lock --reason`. The lease is released on dispose; a lease whose process is gone is
+  released on `open` (recovery).
+- **Prune.** `prune({ keep })` keeps the `keep` (default 15) most recently used managed worktrees
+  per repository and removes older ones that hold no lease. Permanent, leased and locked-by-others
+  worktrees are never pruned.
+- **Snapshot before removal.** Every removal of a worktree with uncommitted changes or commits not
+  on any other branch first records them: `git stash create` (with untracked files committed into a
+  temporary index) and `git update-ref refs/xharness/snapshots/<id> <commit>`. `restore({ id })`
+  recreates the worktree from its snapshot.
+- **Remove.** `remove({ id, force? })` refuses a leased worktree, and refuses dirty work unless
+  `force`, in which case it snapshots first.
+- **Handoff.** `handoff({ id, direction: 'toSource' | 'toWorktree' })` moves uncommitted changes
+  between the worktree and the source checkout through git (`diff --binary` and `apply --3way`,
+  plus untracked files). It refuses when the target has uncommitted changes, when a branch would be
+  checked out twice, or when the patch does not apply cleanly; nothing is changed on refusal.
+- **Adopt.** `adopt({ path })` registers an existing linked worktree (for example ones a host
+  created earlier) with origin `adopted`. It moves nothing.
+
+### Sessions and runs
+
+`SessionRunInput` and `TerminalPrepareInput` accept `worktreeId`. The Harness resolves the working
+folder from the registry, takes the lease, and records `RunRecord.worktreeId`, which now has
+Harness meaning. A caller that passes a folder without `worktreeId` behaves as before. D-5 narrows
+to `handoffId`.
+
+### Storage
+
+```text
+<state dir>/worktrees.json                         registry, owner: worktrees/registry.ts
+<state dir>/worktrees/<repoKey>/<name>/            checkouts (device-local)
+<state dir>/worktrees/logs/<id>.setup.log          setup output
+<state dir>/worktree-setup-trust.json              trusted setup-script hashes, owner-only
+```
+
+`repoKey` is a slug of the source folder's name and a short hash of its real path. Checkouts are
+device-local and may be large, so they live in the state directory (`INV-STO-1`). A host may set
+`HarnessOptions.worktrees = { root?, branchPrefix?, keep? }`.
+
+### Server methods
+
+New group `worktrees`: `list { repo? }`, `status { id }`, `create`, `branch { id, name }`,
+`handoff { id, direction }`, `remove { id, force? }`, `restore { id }`, `prune { repo?, keep? }`,
+`adopt { path }`, `setup.trust { repo, hash }`. Terminal equivalents use the control key
+(INV-TUI-4).
+
+### Terminal
+
+- `xharness --worktree [name]` (`-w`) starts the terminal in a new managed worktree of the current
+  repository (or reuses the named one).
+- `xharness worktree list|new|rm|prune|adopt|restore`.
+- `/worktree` opens a page: list with branch, changes and last use; actions new, switch, create
+  branch, hand off, remove, restore, prune, trust setup script. Switching uses the terminal
+  relaunch loop with the new folder.
+
+### INV-BND-2
+
+"worktree" leaves the list of application concepts; a worktree is now a Harness object.
+
+## Alternatives
+
+- **Keep worktrees in the App.** Breaks INV-PAR-1; the terminal could not isolate a session.
+- **Claude Code's opt-in named worktrees only.** The owner chose Codex's managed model; named
+  permanent worktrees are kept as the second kind.
+- **Inside the repository** (`.claude/worktrees`, `.agents/worktrees`). Puts large device-local
+  folders where editors and tools index them; the state directory avoids that.
+- **Copy-on-write clones** (omp). Faster for large ignored folders but platform-specific; left for
+  a later option.
+
+## Consequences
+
+- Hosts call `worktrees.*` instead of running git themselves. The App's `projects.rs` worktree
+  code is replaced; its existing worktrees can be adopted on the person's command.
+- New folders in the state directory; no data-root change.
+- The terminal gains a command-line flag, a command and a page.
+
+## Migration
+
+Nothing moves automatically. `adopt` registers existing worktrees when a person asks. The change
+can be undone by removing the registry; checkouts stay valid git worktrees.
+
+## Checks
+
+Unit tests on temporary repositories: create (detached, branch, carry changes), include copy (no
+overwrite, symlink skip, caps), setup trust gate, lease and lock, recovery of a stale lease, prune
+order and protection, snapshot and restore, remove refusal, handoff both ways and its refusals,
+adopt. Terminal page model tests. `npm run typecheck`, `npm test`, `npm run prove`, and the App's
+checks.

package/docs/architecture/proposals/PROP-0017-page-annotations.md

@@ -0,0 +1,127 @@
+---
+id: PROP-0017
+title: Page annotations as a Harness capability, captured in the headed browser or a host's web view
+status: Implemented
+created: 2026-10-23
+updated: 2026-10-23
+affects: [INV-STO-3, INV-SRV-1, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0017: Page annotations
+
+Accepted by the user's approval of the parity plan on 2026-10-23 (PROP-0015, ADR-0017). The owner
+chose capture through a visible (headed) Harness browser window when only the terminal runs.
+Implemented in the working tree on 2026-10-23: `src/annotations/`, the `annotations` world part,
+`annotations.*` methods, `/notes` and `/annotate`; spec pages 07, 10, 11, 12, 13 updated. The App
+source changes migrate the prior store into Harness and provide the Annotate panel; acceptance of
+native WKWebView gestures remains outstanding. The Harness implementation is included in the 4.0.0
+candidate.
+
+## Problem
+
+Web annotations exist only in the App (`App/src-tauri/src/browser_annotations/`, FEAT-0016): a
+person marks a page, a text range or an element in an App WebKit tab, writes a note, and shares it
+with an agent, which reads it with `browser_annotations_list` / `browser_annotations_read`. The
+store, the page script and the tools are App code, so the terminal has no annotations (INV-PAR-1).
+
+## Affected rules
+
+- 13-world-tools: "The App owns its shared WebKit browser UI, private/shared tab policy, …" — the
+  WebKit capture surface stays with the host; the store, tools and page script move here.
+- `INV-STO-3`: new data-root folder `annotations/`.
+- `INV-SRV-1`: new method group `annotations`.
+
+## Proposal
+
+### Records
+
+A **note** is `{ id, version, source, target, body, tags, status, author, createdAt, updatedAt,
+grants, history }`, the format of the App store, so existing notes import unchanged:
+
+- `source`: `{ url, title, capturedAt }` plus an optional opaque `surface` string from the capturing
+  front end.
+- `target`: `page`, `text { exact, prefix, suffix, start, end }` (Unicode code points over
+  normalised page text), or `element { tag, role, name, text, context, selector }`.
+- `status`: `open` or `resolved`. `version` increases on every change; update and delete name the
+  version they expect (compare-and-swap). The last 100 change receipts are kept, without earlier
+  bodies. At most 10,000 notes.
+- `grants`: `{ principal: { sessionId? , agentId? }, binding?: string, grantedAt }[]`. `binding` is
+  an opaque host string (the App uses its tab and sharing epoch); the Harness compares it, never
+  interprets it. Sharing and revoking are a person's action through the methods below, never a
+  model's.
+
+Notes are one JSON file each under `<data root>/annotations/`, written atomically, owned by
+`annotations/store.ts`. The store is synchronous, like the Wiki.
+
+### Page script
+
+`annotations/pageScript.js` is the App's page script, moved: plain DOM code with a pull model
+(`identity`, `begin`, `capture`, `cancel`, `resolve`, `reveal`). The page never calls out; the
+front end polls it. It runs in the page's own script world, as in the App, so a page can tamper
+with it: every result is untrusted and validated by the store before it is saved. A host reads the
+same source with `annotations.pageScript`.
+
+### Tools
+
+A world part `annotations` (plugin id `annotations`, switchable, on by default) offers two
+read-only tools to SDK and terminal sessions:
+
+- `page_notes_list { url?, status?, offset? }` — up to 20 summaries, 12,000 characters total.
+- `page_notes_read { id }` — the full note, marked untrusted.
+
+A tool returns only notes granted to the calling session or agent. A binding is the host's handle
+for revocation: when what it stands for ends (a tab closes or is shared again), the host calls
+`annotations.revokeBinding` and every grant made with it ends. The Harness never interprets a
+binding. The part is separate from the browser part, so a host that replaces the browser
+(`browser: false`) still has annotations.
+
+### Server methods
+
+Group `annotations`: `list { url?, query?, status?, offset? }`, `read { id }`,
+`create { source, target, body, tags }`, `update { id, expectedVersion, patch }`,
+`delete { id, expectedVersion }`, `share { id, principal, binding? }`,
+`unshare { id, principal }`, `revokeBinding { binding }`, `import { notes }` (keeps ids; used once
+by a host migrating its own store), `pageScript` (the page helper's source for a host's web view).
+
+### Terminal capture
+
+- `/annotate [url]` opens a visible capture browser for the terminal session (its own window and
+  its own profile, `<state dir>/browser/profiles/person`, separate from the agent's browser),
+  navigates when a URL is given, and runs the page script there. The person selects
+  text or an element in the Chromium window and presses Capture in the terminal; the terminal pulls
+  the selection, asks for a body and tags, and saves the note. `/annotate --page <url>` saves a
+  page note without opening a window.
+- `/notes` lists notes for the current page or all notes, with search and status filter, and offers
+  edit, resolve or reopen, share with this session, unshare, delete and reveal (highlight in the
+  headed window; result `matched`, `ambiguous` or `unresolved`).
+
+### Host capture
+
+A host with its own web view (the App's WebKit tabs) runs the same page script there and calls the
+same methods. The host keeps its tab and sharing policy and passes it as the grant's binding.
+
+## Alternatives
+
+- **Keep annotations in the App.** Breaks INV-PAR-1.
+- **Terminal-only capture from page text and the accessibility snapshot.** The owner chose the
+  headed window, which captures exactly what the person selects. Snapshot picking can be added
+  later as a fallback.
+- **Put the tools in the browser part.** A host that replaces the browser would lose them.
+
+## Consequences
+
+- New data-root folder `annotations/`, new method group, two new model tools.
+- The App's store and tools are replaced by Harness calls; its WebKit capture stays.
+
+## Migration
+
+The App imports its existing `<data root>/browser-annotations/*.json` once with
+`annotations.import`, keeping ids, then renames the old folder `browser-annotations.migrated`. If
+the import fails, nothing is renamed and the App reports it.
+
+## Checks
+
+Store tests ported from the App's `store.rs` tests (compare-and-swap, cap, history, target
+validation, code-point offsets); grant tests (an unshared note is invisible, a binding mismatch is
+refused); page-script tests; capture and reveal with a fake browser launcher; terminal page model
+tests. `npm run typecheck`, `npm test`, `npm run prove`, and the App's checks.

package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md

@@ -0,0 +1,179 @@
+---
+id: PROP-0018
+title: Inspector-style page notes, a fix queue to the agent, and app windows as capture targets
+status: Implemented
+created: 2026-10-23
+updated: 2026-10-23
+affects: [INV-STO-3, INV-SRV-1, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0018: Inspector, fix queue and app targets for page notes
+
+Requested by the owner on 2026-10-23. They chose these four things:
+- the popover's three choices: Save, Queue, Send now
+- the popover drawn inside the page
+- Electron over its DevTools port, and real Tauri windows on macOS, as targets
+- the Harness and terminal first, then the App pane
+
+Implemented for the Harness and terminal on 2026-10-23 and in the App source on 2026-10-24 (store migration, `page_notes_*` tools, Annotate panel). The Harness implementation is included in the 4.0.0 candidate. Native WKWebView gestures still need acceptance in the running App.
+
+## Problem
+
+Page notes (PROP-0017) take several prompts each. The person picks a kind, confirms in the terminal, types the note in the terminal, then shares it. A note never reaches the agent unless the person asks the agent to read it. Capture works only on http(s) pages, in a new browser context. So a person cannot point at a component of the app they are building, say what to change, and have the agent do it, and they cannot do it at all in a desktop app's own window.
+
+## Affected rules
+
+- `INV-SRV-1`: new methods `annotations.queue`, `dequeue`, `confirm`, `queued`, `createAndAct`, `compose`, `delivered`, `send`, `annotations.capture.*` and `annotations.bridge.start`. All are additive.
+- `INV-STO-3`: one new state-directory file, `<state dir>/notes-bridge.json`, which holds the page bridge's port and token. It is owned by `annotations/bridge.ts`.
+- 07: a new model tool, `page_notes_mark_fixed`. It is the first page-note tool that writes.
+- 13: "Capture happens in the terminal's visible browser or in a host web view" now also covers app windows, either over a loopback DevTools port or through the page bridge.
+
+## Proposal
+
+### Records
+
+A note gains an optional `delivery`:
+`{ state: 'queued' | 'sent' | 'fixed', sessionId, queuedAt, autoSend?, confirm?, sentAt?, runId?, fixedAt?, summary? }`.
+
+- `status` (`open` | `resolved`) is unchanged, and only a person resolves a note.
+- Queueing a note shares it with that session, because the agent must be able to read what it is asked to fix.
+- New history operations: `queue`, `dequeue`, `deliver`, `mark_fixed`.
+- A note captured in an app window carries `source.app: { kind: 'cdp' | 'bridge', name }`. Its URL may then also use `file:`, `app:`, `tauri:`, `electron:` or `asset:`, still without credentials. Web notes keep the http(s) rule.
+
+### Inspector and popover
+
+`begin` takes a third kind, `inspect`.
+- Hovering draws an outline and a `tag.class W×H` chip.
+- A click, or a drag over text, opens a popover beside the target. It has a comment box and three buttons:
+  - **Create annotation**: `save`
+  - **Ask agent to fix**: `queue`
+  - **Proceed now**: `send`
+- ⌘/Ctrl+Enter is Proceed now; with Shift it is queue.
+- Everything is drawn in a closed shadow root.
+- The page never receives the press or click on what is inspected, nor anything typed in the popover.
+- Inputs, secrets, `[data-sensitive]` elements, frames, shadow roots and custom elements are never picked, as in PROP-0017.
+- The inspector stays on after each comment.
+- A new operation, `next`, returns `{ active, documentId, url, title, result }`, one comment at a time.
+- `toast` shows a short status in the page.
+- The helper's global key moves to `…page.v2`.
+
+### Trust
+
+What the page helper returns is page data. Whether a "Proceed now" goes straight to the agent depends on **where the helper ran**, decided by the Harness:
+- **Chromium (the capture browser and DevTools-attached apps):** the helper runs in an isolated script world (`Page.createIsolatedWorld`). The DOM is shared, but the JavaScript globals are not, so the page cannot read or forge results. These results are trusted and sent directly.
+- **Page bridge and host web views without isolation:** results are untrusted. A send becomes a queued note with `confirm: true`, which the person confirms in the panel before it goes out.
+
+A host's `annotations.createAndAct` passes `trusted: true` only for comments from its own UI or an isolated world.
+
+### Delivery
+
+`compose(notes)` builds one instruction for a batch:
+- It contains each note's id, where it is, the element (tag, role, name, selector, text) or the quoted text, and the person's comment.
+- Page-derived text is labelled untrusted and fenced; the comment is in a `comment` fence.
+- It asks the agent to call `page_notes_mark_fixed`.
+- A batch holds at most 20 notes.
+
+The `NoteDeliveries` service (`annotations/delivery.ts`) handles sending:
+- **Terminal session:** the batch goes out as a new run through `TerminalSessions.send`, and the notes become `sent` with that run id. If the session is busy, the notes stay queued with `autoSend`.
+- **Host session:** the reply is `{ state: 'host', text, ids }`. The host starts the run (`sessions.run`) and reports it with `annotations.delivered`.
+- **When a run ends** (`runs.listen`, after 250 ms), the session's `autoSend` notes go out. Notes still waiting for a person's confirmation are skipped. For a host session, the service emits the notice `annotations.ready`.
+- Every change emits `annotations.changed`.
+
+### Model tool
+
+`page_notes_mark_fixed { id, summary }` works only on a note shared with the caller. It sets `delivery.state = 'fixed'` with the summary. It never resolves a note and never changes grants. It is not read-only, so it is unavailable in plan mode.
+
+### Capture targets
+
+`AnnotationCapture` captures in one target per key:
+- **`web`:** the visible browser window from PROP-0017. Its helper calls now run in an isolated world.
+- **`cdp`:** an app started with a DevTools port, attached with `connectOverCDP` to a loopback address only. It uses the app's own windows, and nothing is routed or opened. Releasing the target disconnects; the app keeps running. The default name is `App at <host:port>`.
+- **`bridge`:** a loopback HTTP server (`annotations/bridge.ts`) serves `/page-notes.js?token=…`. That script is the page helper plus a long-poll loop that pulls operations and posts replies.
+  - The port and token are kept in `notes-bridge.json`, so the script tag in an app stays valid across restarts.
+  - Requests need the token and the host name `127.0.0.1:<port>` or `localhost:<port>`, which blocks DNS rebinding.
+  - At most 32 windows; a window is dropped after 45 s without a poll.
+
+Methods (`key`, `windows`, `selectWindow`, `inspect`, `stopInspect`, `next`, `toast`) behave the same for all three.
+
+`inspectStep` (`annotations/inspect.ts`) is the one loop step the terminal and hosts share. It:
+1. reads the next comment;
+2. creates the note with `source.surface` and `source.app`;
+3. applies the action with the target's trust;
+4. shows a toast in the page.
+
+### Server methods
+
+| Method | Input | Reply |
+|---|---|---|
+| `annotations.queue` | `{ id, sessionId, expectedVersion?, autoSend? }` | `Note` |
+| `annotations.dequeue` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.queued` | `{ sessionId }` | `{ notes }`, oldest first |
+| `annotations.createAndAct` | `{ note, action, sessionId?, trusted? }` | `{ note, send }` |
+| `annotations.compose` | `{ sessionId, ids? }` | `{ text, ids }` |
+| `annotations.delivered` | `{ ids, sessionId, runId }` | `{ notes }` |
+| `annotations.send` | `{ sessionId, ids? }` | `{ state: sent \| busy \| host \| empty, … }` |
+| `annotations.capture.attach` | `{ key, kind, endpoint?, name? }` | `{ kind, app, windows, bridge? }` |
+| `annotations.capture.target` | `{ key }` | `{ kind, app, inspecting, windows }` |
+| `annotations.capture.selectWindow` | `{ key, window }` | `{}` |
+| `annotations.capture.open` | `{ key, url? }` | `{ url, title }` |
+| `annotations.capture.inspect` / `stopInspect` | `{ key }` | `{ captureId }` / `{}` |
+| `annotations.capture.next` | `{ key, sessionId?, surface? }` | `{ active, trusted, app, note, send, message, … }` |
+| `annotations.capture.release` | `{ key }` | `{}` |
+| `annotations.bridge.start` | `{}` | `{ port, token, scriptUrl, snippet }` |
+
+### Terminal
+
+`/annotate` is now a full-screen pane. The browser window or the app's window is the canvas, and the pane is the panel beside it.
+
+Ways to start it:
+- `/annotate [url]`: a web page or dev server
+- `/annotate --app <DevTools address | port> [name]`: an app over its DevTools port
+- `/annotate --bridge [name]`: shows the script tag to load in the app
+
+The pane:
+- The header shows the target, the window, and whether the inspector is on.
+- Sections: **Queue (N)**, **Sent and fixed**, and **Saved**.
+- Keys:
+
+  | Key | Action |
+  |---|---|
+  | `i` | inspector on/off |
+  | `s` | send the queue, confirming page-origin notes first |
+  | `x` | take the selected note out of the queue |
+  | `t` | choose a window |
+  | `Enter` | note menu: reveal, send, confirm, queue, unqueue, edit, resolve, delete |
+
+- It polls `terminal.annotations.next` every 400 ms while the inspector is on.
+
+New terminal routes: `target`, `attach`, `windows`, `selectWindow`, `inspect`, `stopInspect`, `next`, `queue`, `dequeue`, `confirm`, `send`. They queue and send only to the terminal's own session and need the control key. `/notes` stays the plain list.
+
+## Alternatives
+
+- **The host draws the popover.** The App's native web view covers React content, and each host would build its own. The owner chose in-page drawing.
+- **A WebSocket bridge.** It would need a new dependency. Long-polling over plain HTTP is enough for one person's clicks, and `text/plain` posts avoid CORS preflights.
+- **Trust whatever the page reports.** A hostile page could start a run with its own text. The isolated world, plus confirmation where isolation is impossible, prevents that.
+- **Do nothing.** The owner's request goes unmet.
+
+## Consequences
+
+- **Notes:** the record has a new optional field; older notes read unchanged.
+- **Protocol:** additive methods and notices.
+- **Hosts:** the App replaces its bottom-strip panel with a pane, and calls `annotations.*`, `annotations.capture.*` for app targets, and `compose`/`delivered` around its own `sessions.run`.
+- **Agent tools:** sessions get a third page-note tool.
+
+## Migration
+
+No data migration: `delivery` is optional. The App's PAR-011 migration (`annotations.import`) is unchanged. The bridge settings file is created on first use and can be deleted to get a new port and token.
+
+## Checks
+
+| What | Where |
+|---|---|
+| Queue, delivery, busy and auto-send, confirmation, host hand-off, mark fixed, app URLs | `annotations/delivery.test.ts` |
+| Inspector in a real page: element, text drag, sensitive field refused, Escape, toast, cancel | `annotations/pageScript.test.ts` |
+| Isolated world (the page cannot see the helper), reload re-arm, DevTools attach leaves the app running, bridge round-trip as untrusted, stable port and token | `annotations/capture.test.ts` |
+| Bridge token, host-name check and relay | `annotations/bridge.test.ts` |
+| Pane | `terminal/tui/pages/annotatePage.test.ts` |
+| Terminal send and auto-send on run end | `terminal/terminal.test.ts` |
+| Host compose and delivered | `npm run prove` |