@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/README.md

@@ -1,6 +1,6 @@
 # Harness architecture specification
 
-**Status:** binding. **As of:** 2026-10-21, checked against `src/` on branch `harness2`.
+**Status:** binding. **As of:** 2026-10-26, checked against `src/` on branch `release/1.0.0`.
 
 This folder is the core specification of `@xingular/harness`. Code must conform to it. A change
 that would alter what it says needs a proposal the user approves first (see
@@ -41,6 +41,7 @@ not one class (a set of functions in one module, say), it says so.
 | [11 Terminal](11-terminal.md) | The Harness-owned terminal frontend and its process boundary | `INV-TUI` |
 | [12 Storage](12-storage.md) | The data root and state directory, and who writes what | `INV-STO` |
 | [13 World tools](13-world-tools.md) | Generic web and isolated browser backends, host boundary and diagnostics | — |
+| [14 Surfaces and parity](14-surfaces-and-parity.md) | Every capability is a Harness capability with a terminal surface; host-backed capabilities; host-only surfaces | `INV-PAR` |
 | [Proposals](proposals/README.md) | Architecture change proposals and their status | — |
 
 Related records, not binding by themselves:
@@ -57,11 +58,14 @@ Related records, not binding by themselves:
 
 ## Glossary
 
-These words are used the same way on every page, in code and in the data layout.
+These words are used the same way across architecture pages and, for implemented concepts, in code
+and the data layout. Terms marked as planned are future vocabulary only; they do not describe
+current behavior.
 
 | Word | Meaning |
 |---|---|
 | **Foundation** | The fixed half of the harness: code and invariants that no edit, improver or adoption can change. Changes by release, and by proposal when a contract moves. |
+| **Agent Mode** | A planned foundation-level work style, with at most one mode active at a time. Plugins remain independently stackable contributions. This is distinct from plan mode and existing `mode` fields; it is not a runtime contract ([FW-0001](../future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode)). |
 | **Variant** | The mutating half: one tree of eight components (c1–c8) for one scope. Formerly "harness tree". |
 | **Component** | One of c1–c8 inside a variant (system prompt, guardrails, memory, tool guidance, subagents, skills, scripts, plugins). |
 | **Surface** | The foundation's definition of what a variant may contain (`PI_SURFACE`): paths, patterns, the always-on cap. |
@@ -106,9 +110,18 @@ proposal, or a correction to the other document).
 | D-1 | `AGENTS.md` (before this spec), `INV-RUN-6` | The old rule said only `sessions/runStore.ts` writes `runs/<id>/`. In code, four other harness modules also write side files there: `prompt/compile.ts` (`context.json`), `sessions/sessions.ts` (`caller.json`), `capabilities/runSnapshot.ts` (`capabilities.json`), `mcp/service.ts` (`mcp-context.json`). The spec states the rule the code keeps (see `INV-RUN-6`); whether to route all of them through `runStore.ts` is open. |
 | D-2 | `README.md` "Plugins" | Describes a `plugin_propose` tool and an Inbox for proposed plugins. No such tool exists in `src/`. |
 | D-3 | `README.md` "External curation" | Describes `externalMaintenance`, `vaultAccess`, `MAINTENANCE_PLUGIN`, `maintenance.*` methods and tools. None exist in `src/`. |
-| D-4 | `INV-BND-2` | Several names carry an application's name: the context message type `xingular-context`, the approval extension `xagent-approvals`, the MCP client name `xagent`, and the terminal commands `xagent-wiki` / `xagent-mcp`. The default product name `Xingular Harness` is allowed; these are not. |
-| D-5 | `INV-BND-2` | `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts. They are stored and returned, never read, and are documented as the application's fields. |
+| D-4 | `INV-BND-2` | Several names carry an application's name: the context message type `xingular-context`, the approval extension `xagent-approvals`, the MCP client name `xagent`, and the terminal commands `xagent-wiki` / `xagent-mcp`. The default product name `Xingular Agent` is allowed; these are not. |
+| D-5 | `INV-BND-2` | `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts. They are stored and returned, never read, and are documented as the application's fields. Since PROP-0016 (2026-10-23) `worktreeId` has Harness meaning when it names a registered worktree; only `handoffId` remains an application field. |
 | D-6 | `INV-BND-2` | Plan-mode instructions (`sessions/planMode.ts`) name a managed browser and computer controls, which the harness does not provide. |
 | D-7 | `INV-MEM-3` | `wiki/notes.ts::remove` keeps a version but does not call `noteChange`, so hooks hear saves but not removals. |
 | D-8 | old `AGENTS.md` | Listed `work` among the sections delivered as updates. The compiler's built-in dynamic sections are only `references` and `wiki`; `work` is dynamic only when the application marks it so. `INV-PRM-3` states the code's rule. |
 | D-9 | World/browser implementation | Resolved for the 1.0.0 candidate by PROP-0012/ADR-0014 and page 13: the Harness owns a generic isolated browser; App browser UI, tab sharing and computer integration remain with the host. |
+| D-10 | OpenTUI skill completion | At the start of PROP-0013, documentation claimed skill completion, but OpenTUI only rendered slash-command completions. The skill helper had no frontend caller. PROP-0013 explicitly resolves this drift. |
+| D-11 | `INV-RUN-5`, unattended approval and question paths | Source inspection on 2026-10-23 found that `SessionRunInput.automatic` disables resource discovery and extension dialogs (`sessions/runner.ts:574`), but the general gate does not receive that flag. `Sessions.gate` explicitly refuses approvals for `probe`, `improver` and `reflection` triggers, then otherwise calls `requestApproval` (`sessions/sessions.ts:198`). `ask_user` was also constructed independently of `automatic` when harness tools were enabled (`sessions/sessions.ts:397`, `tools/askUser.ts:69`). That question-tool gap is resolved for newly resolved runs by PROP-0022/ADR-0022 (2026-10-24); an unattended continuation of a run pinned with that tool is rejected. Thus the flag alone does not establish the invariant that every unattended run refuses human interaction; host policy and capability selection can narrow these paths. This is a static source finding, not a live reproduction. See [proactive autonomy research](../study/proactive-autonomy.md#current-foundation-and-the-missing-loop). |
+| D-12 | 12-storage layout | The isolated browser keeps device-local profiles and settings under `<state dir>/browser/` (`browser/config.ts`, `browser/session.ts`); page 12's layout did not list it. Resolved 2026-10-23: page 12 lists it. |
+| D-13 | `docs/study/feature-gap-review.md` row 8 | Says browser and computer interaction are not built in. Page 13 (PROP-0012) records a generic isolated browser in the foundation; computer interaction needs a host surface. |
+| D-14 | 12-storage layout | Page 12 lists browser settings under `<state dir>/browser/`, while `browser/config.ts` stores configuration in `<state dir>/browser.json`; browser profiles and downloads use the `browser/` directory. The layout needs an owner decision before either side is changed. |
+| D-15 | Terminal sketch verification status — resolved 2026-10-24 by PROP-0028 | Pages 11 and 14 and `terminal-tui.md` said connected-sketch implementation verification was pending, while retained PTY evidence and PAR-014 recorded it as verified. Updated the docs to distinguish deterministic fixture verification from owner visual acceptance, every-emulator rendering and live-model sketch quality. |
+| D-16 | Terminal slash-command highlighting — resolved 2026-10-24 | `terminal-tui.md` specified accent coloring for recognized leading commands while typing, but the OpenTUI composer only styled attachment labels. User-message bubbles also lacked command-token styling. The renderer now uses the active command registry for both surfaces. |
+| D-17 | `PROP-0039`, `ADR-0036`, `INV-GATE-3/8` | Implementation is in progress in the 1.2.0 worktree: native writes revalidate canonical targets and atomically replace files under an OS write scope; default Bash fails closed on external hard-link aliases and runs in a sandbox that prevents new cross-boundary links; outside-scope Bash requires approval before one execution and command output never triggers approval or replay. The filesystem root is rejected as a workspace, and approval details expose the complete command. Launcher selection uses fixed system paths. Same-user peer processes remain outside this boundary. Focused macOS tests, full Harness CI, App compatibility checks, and PTY verification at 40x20, 80x24, and 100x30 pass. Linux sandbox integration remains unverified locally because this Darwin host has no `bwrap` and Colima is stopped; both CI workflows now install bubblewrap and `scripts/ci.sh` fails if it is absent, but an Ubuntu run is still required. No candidate, tag, or publication exists. |
+| D-18 | `core/index.ts` migration 5 | The `run_stats` table has no writer in the Harness. PROP-0042's `usage_requests` ledger is the analytics source; whether to drop the older table is open. |

package/docs/architecture/proposals/PROP-0006-run-checklist.md

@@ -3,7 +3,7 @@ id: PROP-0006
 title: A run checklist the model writes, recorded as a run event
 status: Implemented
 created: 2026-10-22
-updated: 2026-10-22
+updated: 2026-10-24
 affects: [02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 10-server-protocol.md]
 ---
 
@@ -41,7 +41,9 @@ Gap #2 of `docs/study/feature-gap-review.md`.
   where public instruction lives" (study insight 4).
 - New built-in plugin `checklist` declares the tool.
 - `checklistOf(events)` projects the latest list; the server exposes it as `runs.checklist`.
-- Terminal sessions do not get the tool yet.
+- Terminal sessions do not get the tool yet. (Update 2026-10-24: they do now; the terminal
+  extension registers the same tool, records it through `checklist` telemetry and renders each
+  write as a checklist block. See `docs/parity.md` PAR-001.)
 
 ## Alternatives
 

package/docs/architecture/proposals/PROP-0013-resource-browser.md

@@ -0,0 +1,58 @@
+---
+id: PROP-0013
+title: Unified terminal resource browser
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-TUI-4, 03-variants.md, 06-plugins-and-capabilities.md, 09-accounts-and-connectors.md, 11-terminal.md]
+---
+
+# PROP-0013: Unified terminal resource browser
+
+## Problem
+
+Skills, local resources, variant additions and community discovery are split across commands.
+See [source study](../../study/tui-resource-browser.md). The user approved the proposed UX plan
+and requested implementation in this session.
+
+## Affected rules
+
+INV-TUI-4 requires a private control key for terminal configuration mutations. Extend that
+protected route to browser reads, local imports, package install/remove and connection management.
+INV-FND-2 (validated variant commits), INV-PLG-1 (single loader), INV-PLG-3 (installation grants
+no trust/attachment) and INV-MCP-4 remain enforced. No extension point is added.
+
+## Proposal
+
+One browser exposes Overview, Foundation, Variant, Skills, Plugins, Connections, Tools and Library.
+Resource sections share Installed/Discover. Existing commands become shortcuts. Saved and live
+availability remain separate: session loader/tool registry proves current availability; configuration
+and variant head describe future sessions. Inspecting never loads extensions or connects MCP.
+The private socket adds terminal.browser.* adapters to the existing services. File reads accept
+resource IDs and use enumerated owner paths, regular-file checks and bounded previews.
+
+## Alternatives
+
+Do nothing retains fragmented discovery. Separate improved pages still require users to learn
+where a resource lives. A combined local/remote list obscures the action and availability differences.
+
+## Consequences
+
+No second loader, enablement store or secret store. The public host RPC framing is unchanged.
+Optional install/remove callbacks extend the terminal adapter. Credential inputs are masked.
+Hub documents remain inert until a separate explicit connector-setup action validates their shape.
+
+## Migration
+
+No data migration. Existing commands remain valid shortcuts. Existing sessions keep their resource
+selection and variant pins. New resources require the same trust/attachment and restart as before.
+
+## Checks
+
+Focused model/page/socket tests, OpenTUI completion tests, isolated PTY journeys at 40x20, 80x24,
+120x40, Harness typecheck/tests/build/proof and required sibling App checks. No real model requests.
+
+## Implementation evidence
+
+[Terminal acceptance and limits](../../evidence/terminal-resource-browser/README.md).
+Implementation remains in the working tree; no release or publication is claimed.

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,131 @@
+---
+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-25
+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 }`. Element capture
+  prefers role/name/text; when an otherwise empty visual element has no semantic label, it may use
+  a specific CSS selector (ID, test ID, classes, and a structural path when needed), never a bare
+  tag. Resolution uses that selector only when it identifies one allowed element and the captured
+  semantics/context still agree; stale or duplicate targets remain unresolved or ambiguous.
+- `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.