@xingular/harness 1.0.0 → 1.1.1

package/docs/architecture/10-server-protocol.md

@@ -12,7 +12,7 @@ to the host for the extension points the host supplies.
 | Type / function | Module | Role |
 |---|---|---|
 | `RpcPeer`, `Transport`, `stdioTransport`, `PROTOCOL_VERSION` | `server/rpc.ts` | Framing, requests, replies, host calls. |
-| `methods(harness)` | `server/methods.ts` | The method table. |
+| `methods(harness)` | `server/methods.ts` | Merges Foundation handlers with built-in plugin handlers from `BuiltinPluginRegistry` and rejects overlapping ownership. |
 | `serve`, `attach` | `server/serve.ts` | Registers the table, forwards events and notices. |
 | `remoteSecrets`, remote policy, directory, tools | `server/remote.ts` | Extension points supplied by the host over the protocol. |
 | CLI `serve` | `src/cli.ts` | `serve --state <dir> --data <dir> --name <product> [--builtins <dir>] [--host-secrets] [--host-policy] [--host-tools] [--host-directory]`. |
@@ -27,9 +27,13 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 ```
 
 - stdout carries only protocol lines; diagnostics go to stderr.
+- Run events use the validated, persisted payload schemas in page 02. `question.requested` may carry
+  the optional bounded ASCII sketch metadata described there; the server relays it without changing
+  answer payloads or the protocol framing (PROP-0024).
 - `harness.methods` lists every method. Groups in the table: `accounts`, `harnesses`, `runs`,
   `connections`, `plugins`, `wiki`, `refine`, `capabilities`, `hub`, `terminal`, `approvals`,
-  `harness`, `subagents`, `sessions`, `library`, `recall`, `context`.
+  `harness`, `subagents`, `agents`, `sessions`, `sideQuestions`, `library`, `recall`, `context`,
+  `worktrees`, `annotations`.
 - Host calls (only with the matching `--host-*` flag): `secrets.get|set|delete`,
   `policy.scope|authorize|approval|connections`, `tools.call`. The host registers tools with
   `tools.register` and names with `directory.set`, and describes its parts with
@@ -37,6 +41,12 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 - `refine.start` takes `{ task, k?, mode?, improver?, executor?, baseVersion?, retainWorkspaces?, id? }`;
   `refine.candidates` returns each execution with `workspace: string | null` (page 05, PROP-0002, PROP-0003).
 - `runs.checklist { runId }` returns the run's latest checklist, `[]` when it wrote none (PROP-0006).
+- `agents.list { cwd? }` returns `{ profiles, problems }`; `agents.get { cwd?, name }` one profile;
+  `agents.create { cwd?, name, scope: 'global' | 'project', from? }` writes the template or a copy
+  and refuses an existing file; `agents.remove { cwd?, name, scope }` deletes a person's own file.
+  `subagents.spawn` takes `agent` as a profile name and returns `agent` and `unavailableTools`
+  (PROP-0029). It takes an optional `title` (at most six words); without one the child's title is
+  the first line of its brief (PROP-0030).
 - `runs.continuation { runId, sessionDir? }` returns a `Continuation`, and `sessions.run` accepts
   `continueFrom` (page 02, PROP-0007). `harness.status` reports `recovery.interruptedRunIds`.
 - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
@@ -56,6 +66,10 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   variants, the Wiki, the prompt, connected apps, a recorded session, a plugin hook and the
   refinement demo. The App's sidecar tests parse every reply with its schemas and must pass too.
 
+Built-in feature modules may contribute handlers through `BuiltinPluginRegistry`, but the
+`methods(harness)` result remains the public contract. Plugin module ownership does not rename
+methods or change their params, result shapes or authorization paths (PROP-0020).
+
 ## Source map
 
 `src/server/*.ts`, `src/cli.ts`, `src/core/errors.ts`, `scripts/prove-standalone.mjs`.
@@ -78,7 +92,102 @@ account/model, findings, and available live-check notices. Findings distinguish
 `live` and statuses `pass`, `warning`, `fail`, `disabled`, `blocked`, `unverified`. Schemas and
 Node types are exported. Jobs are in-memory until shutdown; real live-run records remain.
 
+## Side questions (PROP-0019)
+
+| Method | Input | Reply |
+|---|---|---|
+| `sideQuestions.start` | `{ question, cwd, caller, context?: { instructions?, transcript?, references? }, parentRunId?, parentSessionId?, accountId?, model?, effort?, runId?, sessionId? }` | `{ runId, sessionId, nativeSessionId }` |
+| `sideQuestions.read` | `{ runId, sessionId, afterSequence? }` | `{ run: RunRecord, events: RunEvent[] }` |
+| `sideQuestions.interrupt` | `{ runId, sessionId }` | `{ runId }` |
+
+The Harness builds bounded context from the parent's persisted effective prompt and public events
+plus the surface's visible transcript. Read and interrupt require the side run's session id. The
+standalone terminal exposes the same operations through control-key-protected
+`terminal.sideQuestions.*` calls; its caller identity, account and working folder come from terminal
+preparation, not client-supplied values.
+
 Remote `tools.register` may include `diagnostics: [{ id, category, title, tools, probe?: { notice,
 tool, input, contains } }]`. The host answers `tools.diagnose({ id, context })` with `{ status,
 evidence, remedy? }` for local inspection. A probe is a declared registered tool call through
 the gate, with an expected response marker; it cannot supply arbitrary executable code.
+
+## Private terminal resource controls (PROP-0013)
+
+These methods are session-socket controls, not additions to the public host RPC table. All
+require the claimed terminal control key; account, working directory and variant pin come
+from preparation, never from the request.
+
+| Method | Input | Reply |
+|---|---|---|
+| `terminal.browser.config` | `{}` | `{ allowPrivate }`, the device-local private-address setting |
+| `terminal.browser.configure` | `{ allowPrivate: boolean }` | `{ allowPrivate }`, updated setting |
+| `terminal.browser.snapshot` | `{ refresh?: boolean }` | `BrowserSnapshot`: resources, plugins, safe connection records, pinned/latest variant identity and Hub overview |
+| `terminal.browser.read` | `{ id, latest?: boolean }` | `{ content }`, bounded enumerated resource content |
+| `terminal.browser.importSkill` | `{ path }` | `{}`, validated bounded local bundle imported into the existing library |
+| `terminal.browser.hubPreview` | `{ id, version, offset? }` | Existing `HubPreviewPage` |
+| `terminal.browser.hubDocument` | `{ id, version }` | Existing verified installed document |
+| `terminal.browser.connections.appClients` | `{}` | Existing available application OAuth catalog IDs |
+| `terminal.browser.connections.save` | `{ input: ConnectionInput }` | Existing safe `Connection` record |
+| `terminal.browser.connections.test\|signIn\|signOut\|remove` | `{ id }` | Existing connection service result |
+
+Protected `plugins.install { source }` and `plugins.remove { pluginId }` delegate to the package
+service. Optional matching callbacks extend `PluginControl`; hosts without them receive a clear
+unsupported-operation error. No protocol version or persisted schema changes.
+
+## Worktrees (PROP-0016)
+
+| Method | Input | Reply |
+|---|---|---|
+| `worktrees.list` | `{ repo? }` | active `WorktreeRecord[]` (of the repository `repo` is in) |
+| `worktrees.removed` | `{ repo? }` | removed records that `restore` can bring back |
+| `worktrees.status` | `{ id }` | `WorktreeStatus`: exists, head, changed paths, commits since it started |
+| `worktrees.create` | `{ repo, name?, baseRef?, branch?, kind?, carryChanges?, setup? }` | `{ worktree, carried, included, setup }` |
+| `worktrees.branch` | `{ id, name }` | the record, on branch `<prefix><name>` |
+| `worktrees.handoff` | `{ id, direction: "toSource" \| "toWorktree", move? }` | `{ direction, patched, copied, stash }` |
+| `worktrees.remove` | `{ id, force? }` | `{ worktree, snapshot }` |
+| `worktrees.restore` | `{ id }` | the record |
+| `worktrees.prune` | `{ repo?, keep? }` | `{ removed, failed }` |
+| `worktrees.adopt` | `{ path }` | the record (kind `permanent`, origin `adopted`) |
+| `worktrees.setup.trust` | `{ repo, hash }` | `{}` |
+
+Errors: `not_a_repository`, `repository_empty`, `worktree_exists`, `branch_exists`,
+`worktree_in_use`, `worktree_has_work`, `worktree_removed`, `worktree_missing`, `not_a_worktree`,
+`handoff_target_dirty`, `handoff_conflict`, `git_failed`, `git_unavailable`. The terminal reaches the
+same service through `terminal.worktrees.*` routes, which need the control key (`INV-TUI-4`).
+
+## Page notes (PROP-0017)
+
+| Method | Input | Reply |
+|---|---|---|
+| `annotations.list` | `{ url?, query?, status?, offset?, limit? }` | `{ notes, total }`, newest first |
+| `annotations.read` | `{ id }` | `Note` |
+| `annotations.create` | `{ source, target, body, tags? }` | `Note` (private) |
+| `annotations.update` | `{ id, expectedVersion, patch: { body?, tags?, status?, target? } }` | `Note` |
+| `annotations.delete` | `{ id, expectedVersion }` | `{}` |
+| `annotations.share` | `{ id, principal: { sessionId } \| { agentId }, binding? }` | `Note` |
+| `annotations.unshare` | `{ id, principal }` | `Note` |
+| `annotations.revokeBinding` | `{ binding }` | `{ revoked }` |
+| `annotations.import` | `{ notes }` | `{ imported, skipped }` (ids kept) |
+| `annotations.pageScript` | `{}` | `{ script }`: the page helper, with `__ARGS__` for one operation |
+| `annotations.queue` | `{ id, sessionId, expectedVersion?, autoSend? }` | `Note`, shared with the session and queued (PROP-0018) |
+| `annotations.dequeue` / `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.queued` | `{ sessionId }` | `{ notes }`, oldest first |
+| `annotations.createAndAct` | `{ note, action: save \| queue \| send, sessionId?, trusted? }` | `{ note, send }`; an untrusted send waits for `confirm` |
+| `annotations.compose` | `{ sessionId, ids? }` | `{ text, ids }`: one instruction for a host's own `sessions.run` |
+| `annotations.delivered` | `{ ids, sessionId, runId }` | `{ notes }`, marked sent |
+| `annotations.send` | `{ sessionId, ids? }` | `{ state: sent \| busy \| host \| empty, … }` |
+| `annotations.capture.attach` | `{ key, kind: web \| cdp \| bridge, 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 }` |
+
+Notices: `annotations.changed { sessionId, ids }` after any queue, send or fix;
+`annotations.ready { sessionId, ids }` when a host session's waiting notes should be sent now.
+
+Errors: `version_conflict`, `not_found`, `annotation_limit`, `invalid_request`, `invalid_data`. The
+terminal reaches the same store through `terminal.annotations.*`, which shares only with its own
+session and needs the control key (`INV-TUI-4`).

package/docs/architecture/11-terminal.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The harness owns a generic interactive terminal application (`xharness`) over a
+The harness owns a generic interactive terminal application (`xagent`) over a
 persistent Pi session on a variant. It is the standalone way to use the harness, and an
 embedding application can host it in its own PTY. Detail, screen layout and verification evidence
 are in [`../terminal-tui.md`](../terminal-tui.md); this page states the binding parts.
@@ -24,20 +24,42 @@ Harness parent: account + compiled context + trusted resources + run writer
        | launch specification / session socket
 Harness terminal child (Bun): OpenTUI application + persistent Pi AgentSessionRuntime
        | typed native events / plugin UI callbacks
-Screen: transcript above the composer, centred page dialogs
+Screen: transcript above the composer, centred dialogs, full-screen resource browser
 ```
 
 ## Contracts
 
-- The published executable is `xharness`; with no command it starts the interactive terminal. `terminal` remains an explicit alias, and `serve` remains the host-facing RPC path.
+- The published executable is `xagent`; `xharness` is not retained as a compatibility alias. With no command, `xagent` starts the interactive terminal. `terminal` remains an explicit alias, and `serve` remains the host-facing RPC path.
 - `TerminalAssets` is `{ node, cli, piExtension, openTui }`. The command is Bun with
   `--conditions=browser` and `dist/terminal-opentui.js`; no global `pi` is needed.
 - The `piExtension` path is the final prepared extension argument; the runtime loads it as the
   final trusted inline factory.
 - The terminal compiles its prompt once (`compile` + `render`) and keeps that pack; each run
   records a copy (page 04).
+- Normal mode keeps `ask_user` and `ask_user_question` out of the active tool set. A plan request
+  enables the registered question tools alongside its read-only set and restores the normal set on
+  success, failure or interruption. See page 02 and the [terminal guide](../terminal-tui.md).
 - Standalone defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
   `~/.xingular-harness-dev/{data,state}`.
+- An empty conversation shows a centered welcome using `env.productName` (default `Xingular Agent`):
+  the first letter of a multiword name is the orange block mark and its remaining words are letter-spaced
+  in blue. The welcome adds a greeting, tagline and `/help` hint without replacing the composer or
+  status bar. Explicit host product names use the same generic formatting.
+- `xagent --worktree [name]` (`-w`) starts in a new managed worktree of the current repository,
+  or in the named one, and prunes older managed worktrees (PROP-0016). A session that names a
+  worktree holds it for its whole life. `/worktree` switches folders by asking the host to restart
+  the frontend there (`TerminalRelaunch.cwd`), as a new conversation: Pi keeps one history per
+  working folder.
+- Slash-command aliases share one registry entry: `/session (resume)` switches saved sessions,
+  `/history (tree)` navigates branches in the current session, and `/btw (side)` asks a side
+  question through the Harness `SideQuestions` service. It uses the same account/model/effort,
+  mirrors the main run's redacted prompt and public evidence, starts a separate tool-free run, and
+  leaves the main conversation untouched. The dock streams, scrolls and copies the complete answer.
+  Aliases remain callable and searchable, but help and palette show only the canonical
+  entry. Commands owned by required built-in plugins and core terminal commands are unprefixed.
+  Optional built-in plugin and Pi extension commands use `/plugin:<command>`. A bare command or
+  prompt owns its name; a colliding `/plugin:<command>` is omitted and rejected with a hint to use
+  the bare command. Prompt templates and `/skill:<name>` otherwise keep their existing forms.
 
 ## Invariants
 
@@ -50,18 +72,29 @@ Screen: transcript above the composer, centred page dialogs
   their existing layers. The terminal adds no second path for any of them; its runs are written
   through the controller and the run store.
 - **INV-TUI-4** Changes made through the session socket (`plugins.attach|detach|trust|untrust|configure`,
-  `accounts.*`, Hub installs) require the control key the trusted terminal process claimed once
+  `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
+  `terminal.annotations.*`, `terminal.sideQuestions.*`) require the control key the trusted terminal process claimed once
   (`control.claim`). The session's shell can read the session token, so the token alone is never
   enough.
 - **INV-TUI-5** Every resource reload revalidates the original trusted selection; changed or
   revoked code needs review and a fresh terminal.
 - **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The terminal keeps a
   persistent child instead of opening a session per turn.
+- **INV-TUI-7** Required built-in plugin commands use their unprefixed names; optional built-in
+  plugin commands and Pi extension commands use `/plugin:<command>`. Completions and help show each
+  command in its canonical namespace. Bare core commands, aliases, required built-in commands and
+  loaded prompts reserve their names; a colliding prefixed command is hidden and rejected with a hint
+  to use the bare command. Duplicate extension names are rejected with owner diagnostics. Old
+  prefixed forms of required built-in commands are not aliases.
 
 ## Source map
 
 `src/terminal/**`. Decisions: ADR-0001, [ADR-0004](../decisions/ADR-0004-fullscreen-terminal-layout.md)
-(superseded), ADR-0006. Experiments: EXP-0001, EXP-0002 in `../experiments/`.
+(superseded), ADR-0006, [ADR-0021](../decisions/ADR-0021-required-command-namespaces.md),
+[ADR-0024](../decisions/ADR-0024-xagent-command.md),
+[ADR-0027](../decisions/ADR-0027-connected-sketch-display.md),
+[ADR-0028](../decisions/ADR-0028-xingular-agent-product-identity.md). Experiments:
+EXP-0001, EXP-0002 in `../experiments/`.
 
 ## Session name in the working line (PROP-0010)
 
@@ -79,3 +112,150 @@ truncate at the right edge. Manual `/name` and existing long names remain suppor
 Live checks opens an explicit selection followed by account/model, destination, cost and isolation
 confirmation. The page polls structured reports, retains findings after cancellation, and cancels
 on close. No command text is sent to the conversation model. See [Doctor](../doctor.md).
+
+## Resource browser (PROP-0013)
+
+`/harness` owns shared navigation for Foundation, Variant, Skills, Plugins, Connections, Tools
+and Library. `/skills`, `/plugins`, `/connections` (`/mcp`), `/tools`, `/hub` and `/components`
+are shortcuts into that browser. Current availability comes from the live resource loader and
+active tool registry, independently of saved configuration and the latest variant head.
+
+Every `terminal.browser.*` call requires the private control key, including bounded resource
+inspection, local imports, connection management and browser settings. Package install/remove use protected
+`plugins.install|remove`. These are adapters to the existing services, not another loader,
+attachment store, gate or secret store. Browsing neither executes plugin code nor connects MCP.
+The browser uses the full terminal with persistent section tabs (PROP-0014); wide screens keep
+inventory beside details, actions and content, while compact screens keep inline details under
+the same tabs. Other command pages remain centered except `/settings` and `/accounts`, which use
+full-screen page layouts. Accounts keeps Accounts/Pools tabs, search and account-service operations.
+Wide terminals show selected-account details beside the list; Enter or a primary click opens grouped
+actions in that inspector. Compact terminals replace the list with a full-page account detail view
+and its grouped actions. Enter opens the selected account; Escape returns to the list while
+preserving its section, query and selection across navigation and resizing. Tab/Shift+Tab moves focus
+between tabs, the list and (when open) actions; Left/Right changes a focused tab and Up/Down moves
+the focused list or action list. Account actions retain their Session, Account, Sign-in and Remove
+groups; pool actions remain grouped under Manage and Remove. See the
+[terminal guide](../terminal-tui.md#blocks-and-pages) for layout and interaction.
+
+`/settings` is a full-screen page with category tabs, search, settings list and the device-local
+Browser tab for `allowPrivate`. Enabling private address access requires confirmation and allows both
+agent browsing and annotation capture to reach localhost and private networks. It is off by default.
+
+## Worktrees command (PROP-0016)
+
+`/worktree` opens a page of the managed worktrees of the repository the session works in: make a
+managed or permanent worktree, switch the terminal to one (or back to the main checkout), create a
+branch on a detached one, hand changes off in either direction, remove one (with a snapshot when it
+holds work, never the one this terminal uses), restore a removed one, prune older ones, and trust
+the repository's setup script. The page calls `terminal.worktrees.*` routes, which use the same
+`Worktrees` service as the `worktrees.*` server methods. `xagent worktree <command>` offers the
+same actions from a shell.
+
+## Question dock
+
+Pending questions appear in a flat block above the composer, with a tab for each 1–2 word question
+label above its title. Tabs can be clicked; Left/Right also switch questions and preserve staged
+answers. The header has no pager or collapse control, and the dock stays expanded until the answer
+is submitted or Escape cancels the pending question. While it is active, the chat composer and its
+lower status bar are hidden. `n` opens a note for the focused selected choice; Tab and Shift+Tab
+navigate existing note fields, the free-text answer and the action without creating notes. Notes
+and the “Something else” answer wrap across lines. Choice recommendations remain visual only and
+never preselect an answer.
+
+Every choice uses one shared measured layout: a marker gutter, a one-third label cell, a two-cell
+gap, and the remaining description cell. Column boundaries align across all rows at every terminal
+width, including compact widths. Text wraps within its cell; a missing description keeps its cell
+and columns never stack. Recommendation text uses `(Rec.)` when the label column is fewer than 14
+cells. Below 60 terminal columns, the dock uses a compact hint.
+
+The dock body has bounded height and vertical scrolling; question tabs and answer/action controls
+stay outside that scrolling region. PageUp/PageDown scroll the body and Ctrl+Home/End jump to its
+beginning/end while the dock is active, rather than scrolling the transcript. Focused choices and
+note fields are brought into view. Ordinary arrows retain question/choice navigation; Shift+arrows
+pan the sketch horizontally or vertically.
+
+When a question sets `uiSketch: true`, one shared border-only monospace preview below the choices
+shows the hovered or focused choice's ASCII wireframe, with no visible caption or extra left rule.
+Sketch source supports up to 80 columns by 24 lines (page 02) and remains literal ASCII in
+persistence. The terminal uses a bounded structural display projection: recognized ASCII table-border
+rows—including a title between horizontal runs—and enclosed vertical table edges become connected
+box-drawing glyphs, while internal framed tables retain their original widths and positions. For a
+high-confidence frame with matched `+` corners, missing or slightly displaced side edges may be
+filled or moved only through whitespace to the established boundary columns; interior text is never
+moved or overwritten, and conflicting or ambiguous rows remain literal. Bare standalone hyphen
+divider rows expand to `max(panel viewport width, original sketch widest line)` and join the outer
+single-line preview frame with `├` and `┤`. This is not a global `+|-` substitution: prose, content
+operators, ordinary pipes and unrecognized rows remain literal. Source sketches and all persisted
+whitespace remain unchanged; only the display projection adjusts recognized boundary cells.
+
+There is no wrapping, reflow, truncation or markup interpretation. A bounded two-axis viewport makes
+all overflow reachable by panning. Moving focus changes the preview without changing the staged
+answer. Projected glyphs and expanded dividers never enter persisted events or answers; the wire
+contract is unchanged. See [PROP-0025](proposals/PROP-0025-contextual-question-wireframes.md),
+[ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md) and the approved display amendment
+[PROP-0026](proposals/PROP-0026-connected-sketch-display.md) /
+[ADR-0027](../decisions/ADR-0027-connected-sketch-display.md), and
+[PROP-0028](proposals/PROP-0028-normalize-question-wireframes.md) /
+[ADR-0029](../decisions/ADR-0029-normalized-question-wireframe-borders.md). Isolated production
+PTY verification is retained in `docs/evidence/terminal-wireframe-normalization/`; it establishes
+cell topology for bounded fixtures, not every emulator/font or live-model sketch quality.
+
+## Page notes commands (PROP-0017)
+
+`/plugin:notes` lists the page notes kept in the data root, with search, and offers reveal, edit, resolve or
+reopen, share with this session or stop sharing, and delete. `/plugin:annotate [url]` starts a new note: it
+opens a visible capture browser (its own window and profile, separate from the agent's browser), and
+the person notes the whole page, selects text, or clicks an element there, then confirms in the
+terminal. A note is private until shared; this session's agent then reads it with `page_notes_list`
+and `page_notes_read`.
+
+`/plugin:annotate` is the annotate pane (PROP-0018): a full-screen page beside the window being inspected.
+
+- **Ways to start it:**
+  - `/plugin:annotate [url]`: the browser window
+  - `/plugin:annotate --app <DevTools address | port> [name]`: an app's own windows over its DevTools port
+  - `/plugin:annotate --bridge [name]`: app windows that load the page bridge script, which the pane shows
+- **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in the page with Create annotation, Ask agent to fix, and Proceed now.
+- **Sections:** Queue, Sent and fixed (with the agent's summary), and Saved.
+- **Other keys:** `s` sends the queue as one run of this session, confirming notes that came from a page-world script first; `x` takes a note out of the queue; `t` picks a window.
+- **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|queue|dequeue|confirm|send` act only on this terminal's session and need the control key.
+
+## Checklist (PROP-0006, PAR-001)
+
+Terminal sessions register the shared `checklist_write` tool. The extension validates each list
+with the same tool code and sends it as `checklist` telemetry; the controller emits it as
+`checklist.updated` on the active run, so `runs.checklist` and continuation read terminal runs too.
+The gate treats it as read-only, plan mode allows it, and terminal children inherit it. The
+transcript shows each write as a checklist block (`✓` done, `●` in progress (warning yellow), `○` pending) under a
+`Checklist · n of m done` header instead of a tool row; a failed or malformed call stays a tool row.
+
+## Subagent activity monitor
+
+During an active parent run, the terminal polls a private read-only monitor once per second. It
+projects the flat set of child and nested-child runs with task, status, elapsed time, the latest
+tool name, the child's agent profile (name and colour, PROP-0029), the title the parent gave it
+(PROP-0030), and counts from the child's own checklist. The child's own `session_name` is not
+projected; it names the child's session, not its row. Tool summaries, other
+arguments, output and checklist item text never enter the monitor. The latest completed tool name
+remains visible across one-second snapshots until new tool or response activity replaces it. The
+monitor exposes no controls to steer or stop children.
+
+The live rows sit under the status line, after one blank row, with no heading. Each row reads, in
+order: the status mark (`○` queued, a running row that shows the working spinner's frame in the profile's colour (warning for a copy of the parent), `●` waiting in the accent,
+`✓` done, `✕` failed, `!` stopped), the profile name in its colour (`subagent`, muted, for a copy
+of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` when the child
+keeps a checklist. Active rows come first, at most three, then `+N more · /subagents`; a narrow
+terminal cuts the title first. `/subagents` opens the searchable full roster with the same fields.
+Finished rows remain until the parent run settles. The projection is volatile and scoped to that
+parent run; it is not a persisted event or public server method.
+
+## Agent profiles (PROP-0029)
+
+`/agents` opens the Agents page over `terminal.agents.list|create|remove`, which call the same
+`agents/profiles.ts` functions as `agents.*`. It lists built-in, global, project and variant
+profiles, and files that cannot be read. The detail pane shows the colour, description, tools,
+plugins, variant, model, effort, file and instructions. Enter on a row offers: for a person's own
+profile, edit (opens the file in `$VISUAL`/`$EDITOR` with the renderer suspended), copy and delete
+(confirmed); for a built-in or variant profile, copy. New profile asks for a name and a place
+(project or global), writes the template and opens it. The terminal passes its pinned variant to
+`Subagents.register`, so the variant's c5 names are profiles there too.

package/docs/architecture/12-storage.md

@@ -16,6 +16,7 @@ index.
   refine/<id>/         summary.json, task.json, variants/, rollouts/, sessions/, context/, selection/, reflection/, improver/, or matrix.json + suite.json for evaluation matrices   (05)
                        rollouts/<label>/workspace/ only when started with retainWorkspaces
   library/<scope>/<area>/   INDEX.md, variants/<task>/{variant/, EXPERIENCE.md}   (05)
+  annotations/<id>.json   page notes   (13, PROP-0017)
   wiki/                home.md, library/ (library/lessons/ from the lessons plugin), projects/<slug>/   (08)
   reflection/improver/lesson-<run id>/   a reflection's native history and reply   (08)
   wiki-history/        earlier versions of notes   (08)
@@ -26,6 +27,7 @@ index.
   hub/                 installed documents and provenance   (09)
   runs/<id>/           run.json, events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json   (02)
   config/              plugin-attachments.json and settings the harness reads   (06)
+  agents/<name>.md     a person's global agent profiles; agents/profiles.ts owns it   (02, PROP-0029)
   index.sqlite         derived index (FTS5)   (08)
   projects.json        read only: the application owns it
 
@@ -36,10 +38,20 @@ index.
   plugin-trust.json, variant-plugin-trust.json, plugin-registered.json, plugin-hooks.json   (03, 06)
   connections.json     connected apps, no secrets   (09)
   hub/catalog.json     catalog cache   (09)
-  run/                 the session socket and terminal commands   (11)
+  run/                 terminal commands, and one session socket per Harness process,
+                       harness-<pid>-<random>.sock; files of ended processes are pruned   (11)
+  worktrees.json       managed worktree registry   (02, PROP-0016)
+  worktrees/<repo>/<name>/   managed worktree checkouts; worktrees/logs/ setup output   (PROP-0016)
+  worktree-setup-trust.json  trusted setup-script hashes, owner-only   (PROP-0016)
+  browser/             isolated browser settings and profiles   (13)
+  notes-bridge.json    the page bridge's port and token, kept so an app's script tag stays valid   (13, PROP-0018)
   harness.log          standalone terminal diagnostics
 ```
 
+Side-question runs use the ordinary `runs/<id>/` records. Their temporary Pi native history is
+created under the operating system temporary directory and removed when the run ends; it is not
+retained in the data root or state directory.
+
 ## Invariants
 
 - **INV-STO-1** Device-local state (credentials, approvals, trust, connections, sockets) is never
@@ -50,6 +62,8 @@ index.
   through that module's functions. A new top-level folder or a new file in `runs/<id>/` is an
   architecture change.
 - **INV-STO-4** `projects.json` belongs to the application; the harness only reads it.
+  Project agent profiles live in the repository at `<project>/.xingular/agents/<name>.md`; the
+  harness writes them only through `agents.create` and `agents.remove` (PROP-0029).
 - **INV-STO-5** Migrations of stored data are one-way and safe: the old data is backed up or left
   as it was when a migration fails, and the failure is reported in `Recovery.migrationError`.
 - **INV-STO-6** Writes of shared JSON files are atomic (`core/fs.ts::atomicWrite`, `writeJson`).

package/docs/architecture/13-world-tools.md

@@ -1,10 +1,12 @@
 # 13 World tools
 
-The foundation supplies generic web and isolated browser tools through the existing tool-provider
-surface. Web requests use the public-address guard. Each browser session owns its context and
-profile; its tools pass the same capability and policy gate as other tools. Read page content is
-untrusted. Sending, purchasing, deleting, changing accounts and granting access require explicit
-human approval. Sensitive fields are not filled by the agent.
+The Foundation owns the generic isolated browser engine, per-session contexts and profiles,
+network policy, and lifecycle. Built-in World plugins contribute the user-facing web search/page
+tools, browser tools and annotations through the existing tool-provider surface. Every tool passes
+the same capability and policy gate. Web requests use the public-address guard; browser requests
+use the device-local private-address setting. Read page content is untrusted. Sending, purchasing,
+deleting, changing accounts and granting access require explicit human approval. Sensitive fields
+are not filled by the agent.
 
 The App owns its shared WebKit browser UI, private/shared tab policy, selected-file uploads,
 windows and the native computer bridge. These application objects do not enter the Harness.
@@ -16,8 +18,28 @@ synthetic page. Their input runs only after live-check confirmation, and their r
 released on completion, timeout or cancellation. Computer interaction needs a host-provided
 isolated surface; without one it is blocked.
 
-Ownership is recorded in PROP-0012 and ADR-0014. No eighth extension point is added.
+Plugin ownership and the Foundation boundary are recorded in PROP-0012, ADR-0014 and PROP-0020.
+World providers are assembled through `BuiltinPluginRegistry`; no eighth extension point is added.
 
 An embedding host may set `browser: false` to disable the generic backend and its plugin
 descriptor before supplying its own browser tool provider. The App uses this option for its
 shared-tab browser, so matching tool names never silently select the wrong backend.
+
+## Page notes (PROP-0017)
+
+The `annotations` world part offers `page_notes_list` and `page_notes_read`, read-only, to SDK and
+terminal sessions. It is separate from the browser part, so a host that sets `browser: false` keeps
+it. A tool returns only notes a person shared with the calling session or agent; quoted page text
+and element names are marked untrusted. Capture happens in a visible capture browser in the
+terminal, or in a host's own web view running the same page helper (`annotations.pageScript`).
+
+**Inspector, queue and app targets (PROP-0018).**
+
+- **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with three choices: save, queue for the agent, or send now.
+  - A queued note is shared with its session.
+  - `annotations/delivery.ts` sends a batch as one instruction, and sends notes the person asked for while the session was busy when its run ends.
+  - The agent reports a fix with `page_notes_mark_fixed`, the only page-note tool that writes. It never resolves a note or changes grants.
+- **Targets.** Besides the browser window, capture can use an app's own windows:
+  - **DevTools port:** an app started with a DevTools port, on a loopback address only. It uses the app's existing windows, routes nothing, and never closes the app.
+  - **Page bridge:** a loopback server whose script an app loads while it is developed (`annotations/bridge.ts`), for web views without a DevTools port.
+- **Trust.** In Chromium targets the helper runs in an isolated script world, so the page cannot forge a comment. A send from the bridge, or from a host web view without isolation, waits for the person to confirm it.

package/docs/architecture/14-surfaces-and-parity.md

@@ -0,0 +1,89 @@
+# 14 Surfaces and parity
+
+## Purpose
+
+The harness has more than one front end: its own standalone terminal (`xagent`, page 11) and
+every application that embeds it. This page fixes how capabilities relate to those front ends, so
+that a person can do the same work in the terminal and in a host, and so that a reader knows that
+a capability is Harness work even when a request names a host.
+
+A *capability* is something a person or a model can do: start a session, approve a call, work in
+a worktree, annotate a page, inspect a run. A *surface* is how one front end presents it: a
+terminal command or page, a host screen.
+
+## Components
+
+| Kind | What it is | Example |
+|---|---|---|
+| Foundation service | A member of `Harness` with server methods | `sessions`, `accounts`, `apps`, `worktrees` (PROP-0016), agent profiles (`agents.*`, PROP-0029) |
+| Built-in feature plugin | A module in `BuiltinPluginRegistry` (`plugins/builtin.ts`) that may supply a `WorldPart`, server methods and terminal commands | web tools, browser tools, annotations, worktrees |
+| First-party plugin | A descriptor in the registry (`plugins/builtin.ts`) | lessons, checklist |
+| Terminal surface | A command, page or dialog in `terminal/` | `/plan`, `/doctor`, the resource browser |
+| Host surface | A host screen built on the same methods and tools | the App's chat, Capability and Harness screens |
+| Host-backed backend | An operating-system object only a host has, behind a generic Harness contract | the App's WebKit tabs, macOS computer bridge, keychain |
+| Host-only surface | Presentation a terminal cannot show (INV-PAR-4) | reserved: interactive agent output ("OpenUI") |
+
+## Contracts
+
+- A capability is reachable through server methods (page 10) and, where a model uses it, through a
+  tool that passes the gate (page 07). Both front ends use the same methods; neither has a private
+  path to Harness state.
+- Required built-in plugin commands and Foundation commands use unprefixed names. Optional built-in
+  plugin commands and Pi extension commands use `/plugin:<command>`. A bare command, alias or loaded
+  prompt owns its name; a colliding prefixed command is hidden and rejected. Built-in plugin
+  categories are documented in page 06 and are not public plugin metadata.
+- A capability may be limited to a run mode when Harness resolves the callable set; the register
+  records that restriction for both surfaces. `ask_user` is available only in attended plan runs,
+  and the terminal's `ask_user_question` alias follows the same restriction.
+- Question choice sketches use one optional validated event contract: up to 80 printable ASCII
+  columns by 24 LF-separated lines (1,943 bytes maximum; page 02). Both surfaces use the same
+  literal ASCII source, persisted unchanged, in one shared preview with access to overflow; neither
+  changes the answer payload (PROP-0025, ADR-0026; originally PROP-0024). The terminal may project
+  recognized ASCII table-border rows—including title-bearing rules—and enclosed vertical table
+  edges into connected box-drawing glyphs, retaining internal framed table widths. For a
+  high-confidence frame, it may fill a missing boundary cell or realign a displaced edge only
+  through whitespace to matched corner columns; interior text and ambiguous rows remain unchanged
+  (PROP-0028, ADR-0029). Bare standalone hyphen dividers expand to the larger of viewport width and
+  original sketch widest line and join the outer single-line frame with `├` and `┤` (PROP-0026,
+  ADR-0027). Prose, content operators and ordinary pipes are not globally substituted. Hosts may
+  retain literal ASCII previews: equivalent capability does not require identical structural
+  typography. No schema, validation-bound, persistence or answer-payload change follows from these
+  display amendments. Terminal geometry, scrolling and projection boundaries follow page 11; hosts
+  may use native presentation without narrowing accepted metadata. Existing hosts with the old
+  bounds must update before accepting larger sketches. Acceptance of the expanded contract on both
+  surfaces is tracked in the parity register. Isolated production PTY evidence verifies bounded
+  fixture topology, not every emulator/font or live-model sketch quality.
+- Side questions use one Harness service on both surfaces. Each caller supplies its visible
+  transcript projection; Harness adds the parent run's effective prompt and public events, then
+  starts an independent tool-free run.
+- The register of capabilities and their surfaces is [`docs/parity.md`](../parity.md). It is
+  descriptive; the invariants below are binding.
+- A host keeps its own register of host-only surfaces. The Harness names no host surface.
+
+## Invariants
+
+- **INV-PAR-1** Every capability a person can use in a host is a Harness capability: a foundation
+  service, a world part 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; the host
+  surface follows.
+- **INV-PAR-3** A host-backed capability needs an operating-system object only a host has. The
+  Harness defines the generic contract and a terminal fallback (for example the headed isolated
+  browser for page annotations). Without a fallback, the terminal shows the capability as
+  unavailable, with the reason, in `/doctor` and `/tools`.
+- **INV-PAR-4** A host-only surface owns no capability. Its actions are Harness methods or tools,
+  its data lives in Harness records, the terminal renders a text fallback, and each one is listed
+  in the host's register by an owner decision. A generic rich-output event kind for such surfaces
+  needs its own proposal; the name is reserved and nothing is designed.
+
+## Data
+
+None of its own. Each capability stores its data as its own page says.
+
+## Source map
+
+`src/harness.ts` (services), `src/world/world.ts` (world parts), `src/plugins/builtin.ts`
+(first-party descriptors), `src/terminal/` (terminal surfaces), `src/server/methods.ts` (methods).
+Decision: [PROP-0015](proposals/PROP-0015-one-capability-surface.md),
+[ADR-0017](../decisions/ADR-0017-one-capability-surface.md).