@xingular/harness 1.0.0 → 1.2.0

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,66 @@ 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.
+- Each terminal `begin` returns the run's pinned `workspaceRoot` to that extension. Native file
+  writes use the same revalidated atomic helper and OS write scope as SDK sessions. Terminal Bash,
+  including initial `!` commands, defaults to the workspace sandbox and external-hard-link scan;
+  `!outside <command>` requests human-only approval before that exact command runs once; its full
+  escaped command is available in scrollable approval details, and an undersized terminal denies
+  the request. The eligible Full Permission switch is the only standing boundary bypass; remembered
+  per-tool grants do not widen it, and command output never triggers approval or replay.
 - The terminal compiles its prompt once (`compile` + `render`) and keeps that pack; each run
-  records a copy (page 04).
-- Standalone defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
-  `~/.xingular-harness-dev/{data,state}`.
+  records a copy (page 04). The shared compaction checkpoint extension reintroduces the active
+  request and latest checklist into post-compaction model context until the run settles.
+- Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
+  shared tool alongside its read-only set and restores the normal set on success, failure or
+  interruption. There is no terminal-only question alias (PROP-0040).
+- A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
+  (PROP-0043). A user `!` command is refused while a plan request runs.
+- Current standalone source defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
+  `~/.xingular-harness-dev/{data,state}`. The standalone development launch uses a file SecretStore
+  under its resolved development state directory, even when its profile names a host backend; it
+  does not use or alter host credentials. `--variant <scope>` explicitly selects a variant head.
+  PROP-0040 approves a shared Harness-owned interactive profile, neutral default scope and
+  credential backend; adoption and runtime verification remain in progress. Until that lands,
+  matching roots/scopes is explicit and matching roots alone does not share host Keychain secrets.
+- `Launch.standard` supplies the shared role and folder text. History, Wiki and skill model tools
+  use the session socket; enabled output-trim/budget-guard hooks load through `firstParty.list`.
+  Pi CLI built-ins (llama.cpp, codemode, tool-search and MCP) are not loaded as a terminal-only
+  resource path. Harness MCP remains available.
+- 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` opens the worktree page; selecting
+  one 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)` opens the full-screen, searchable
+  saved-session page with unnumbered title and metadata rows; `/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. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
+  opens its Limits tab (PROP-0042); both are plugin-owned namespaced routes. The usage page is a
+  centered dialog: each window is a label and reset line above a quota-left bar coloured green at
+  50% or more left, amber from 20–49%, and red below 20%. `commands.list`
+  publishes the effective routes; the browser-safe core catalogue is `commands/registry.ts`. First-class Harness commands are unprefixed and live in that registry,
+  independently of plugin command metadata. Every plugin-owned command uses
+  `/<owner-prefix>:<command>`; the namespace root is offered only by plugins that declare a default
+  command. Prompt templates and `/skill:<name>` keep their existing forms.
 
 ## Invariants
 
@@ -50,18 +96,46 @@ 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** Harness core commands use unprefixed names and are registered independently of
+  feature-plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents`
+  and `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections
+  shortcut. Every plugin-owned terminal command uses `/<owner-prefix>:<command>`, for required and
+  optional built-ins and Pi extensions alike. Completions, help and dispatch use the same stable
+  owner prefix. Prefixes are unique to an owner; a prefix collision or duplicate command within an
+  owner is rejected with owner diagnostics. `/skill:<name>` remains reserved for skill invocation.
+  For one release, the former owner-qualified and `/plugin:<command>` forms of promoted Harness
+  commands remain hidden compatibility aliases; aliases are not listed in help or completion.
+- **INV-TUI-8** Terminal sessions use the Harness-pinned workspace root and the same write
+  boundary as SDK sessions. Native file mutations use revalidated atomic replacement under an OS
+  scope; default Bash scans for external hard-link aliases and runs inside the sandbox. The terminal
+  cannot widen the boundary through its socket or native extension. `!outside <command>` requests
+  human-only approval before one execution; the terminal shows the complete escaped command and
+  denies the request if it cannot display details and choices together. stdout/stderr cannot trigger
+  approval or replay. Missing enforcement fails closed. Full Permission bypasses the boundary only
+  for eligible interactive
+  user runs and does not override hard policy denials, read-only or plan mode, unattended work, or
+  refinement restrictions.
 
 ## 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)
+(superseded by [ADR-0031](../decisions/ADR-0031-plugin-command-owner-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),
+[ADR-0031](../decisions/ADR-0031-plugin-command-owner-namespaces.md),
+[ADR-0034](../decisions/ADR-0034-first-class-harness-terminal-commands.md),
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md). Experiments:
+EXP-0001, EXP-0002 in `../experiments/`.
 
 ## Session name in the working line (PROP-0010)
 
@@ -79,3 +153,172 @@ 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. Multi-select choices use `✓`
+when selected and `○` when unselected, matching checklist glyphs; single-choice options remain
+numbered.
+
+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.
+
+## Web annotations commands (PROP-0017)
+
+`/annotate:notes` lists the Web annotations kept in the data root, with search, and offers reveal, edit, resolve or
+reopen, share with this session or stop sharing, and delete. `/annotate:` opens the default capture pane;
+`/annotate:annotate [url]` is its explicit command form. It opens a visible capture browser (its own window and profile, separate from the agent's browser), where the person can annotate the whole page,
+select text, or click an element there. An annotation is private until shared; this session's agent then reads it with `page_notes_list`
+and `page_notes_read`.
+
+The annotate pane (PROP-0018) is a full-screen page beside the window being inspected.
+
+- **Ways to start it:**
+  - `/annotate:` or `/annotate:annotate [url]`: the capture browser
+  - `/annotate:annotate --app <DevTools address | port> [name]`: an app's own windows over its DevTools port
+  - `/annotate: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.
+
+## Work-slice checkpoint (PROP-0041)
+
+Terminal replies carry the same work-slice guard as structured runs: 160 tool calls, 40 minutes or
+320 000 new tokens, then a refusal that asks for `checkpoint_write`. The extension registers the shared
+tool and sends it as `checkpoint` telemetry, which the controller records as `checkpoint` on the
+active run, so an App reading the same session sees the handoff. Terminal replies are not
+auto-continued: at the boundary the person decides, which is what the terminal's own turn model
+already does. The run record says `interrupted` with terminal reason `slice_complete` (or `stalled`
+when the guard ended it), so a host can continue it; a checkpoint card in the transcript is not built
+yet (PAR-004). Start the terminal with `XINGULAR_WORK_SLICE=off` to launch a reply with no
+boundary at all; it is not persisted, so the next launch without it restores the guard.
+
+## 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), counts from the child's own checklist, the pinned account label, effective model and
+effort, and cumulative usage totals. Model and effort come from the volatile launch selection; the
+latest provider-reported model supersedes the launch model when usage is available. Usage is an
+explicit projection of token, cache, cost, request-count and context-window totals. Per-request
+payloads and reasoning summaries do not enter the monitor. 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 a colored
+profile and normal-color title on its first line, then muted account, model, effort and usage
+metadata on its second line. One blank row separates each two-line entry. Narrow rows truncate this
+lower-priority summary without hiding the title.
+At parent settlement, the terminal makes a final monitor read and keeps the latest parent's rows
+visible until the next parent run starts. The projection remains volatile and read-only, is scoped to
+the latest parent run in the terminal session, and is cleared on session replacement or terminal
+disposal. 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)
@@ -24,9 +25,12 @@ index.
   plugins/<name>/      packages kept with the data   (06)
   trash/plugins/       removed packages   (06)
   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)
+  runs/<id>/           run.json (including optional legacy-compatible workspaceRoot), events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json   (02)
+  # `checkpoint` and `heartbeat` are run events in the same events.jsonl; a bounded reply emits one
+  # heartbeat per 30 seconds (about 60 KB an hour) and no side file (PROP-0041).
   config/              plugin-attachments.json and settings the harness reads   (06)
-  index.sqlite         derived index (FTS5)   (08)
+  agents/<name>.md     a person's global agent profiles; agents/profiles.ts owns it   (02, PROP-0029)
+  index.sqlite         derived index (FTS5, recall, usage ledger)   (08, PROP-0042)
   projects.json        read only: the application owns it
 
 <state dir>/
@@ -36,10 +40,39 @@ 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
 ```
 
+The interactive profile is a credential-free, versioned selection file at
+`~/.xingular-harness/profile.json`, owned by `src/core/interactiveProfile.ts`. It selects the
+interactive defaults: data root, state directory, default variant scope, and a credential-backend
+descriptor. With no selected profile, the defaults are `~/.xingular-harness/data`,
+`~/.xingular-harness/state`, scope `default`, and the state directory's owner-only file secret
+store. A host may provide a stable host-backed secret adapter instead; the profile stores only its
+identifier, never credentials. If that adapter is unavailable, startup fails rather than falling
+back to a different store.
+
+Explicit roots or variant scopes take precedence over the selected profile; the selected profile
+precedes caller-supplied legacy defaults. Explicit adoption creates the profile file without
+replacing an existing selection and does not create, copy, merge, or migrate data roots or
+credentials. Existing account, variant, and session pins remain authoritative for their saved
+runs; the profile selects defaults for new interactive work. `scripts/dev.mjs` and a development
+interactive profile use `~/.xingular-harness-dev/{data,state}` and a separate profile file, not the
+production defaults. The standalone development launch always selects a file SecretStore under its
+resolved development state directory, even if that profile names a host backend; it does not use or
+alter host credentials.
+
+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,10 +83,19 @@ 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`).
 - **INV-STO-7** Files holding trust or secrets are owner-only (`0600`).
+- **INV-STO-8** `core/interactiveProfile.ts` owns the credential-free selection of interactive
+  roots, default variant scope, and credential-backend descriptor. Explicit roots/scopes win; a
+  selected profile wins over legacy defaults. Adoption never replaces a selection or merges roots,
+  and a missing host credential adapter never silently downgrades to a file store. The standalone
+  development launch explicitly selects its isolated file store; this is not a fallback for normal
+  interactive profiles. Profile defaults do not replace the account, variant, or other pins on saved
+  runs.
 
 ## Source map
 

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,49 @@ 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.
+## Shared browser contract and native WebKit limits (PROP-0040)
+
+`browser/contracts.ts` owns the backend-neutral names and input schemas for `browser_*` tools;
+providers adapt those definitions rather than inventing host-specific selectors. The isolated Harness
+backend supports accessibility snapshots and snapshot-scoped refs. A native WebKit host backend
+currently supports navigation, tab management, visible-text reads and page-level scrolling without a
+ref. It does not support accessibility snapshots, snapshot refs or ref-based click/type/select/scroll,
+browser screenshots, browser waits or keyboard presses.
+
+For an unsupported operation the native provider returns an explicit `browser_unsupported` refusal
+with “Nothing was done”; it never treats a snapshot ref as a selector and never silently switches to
+the isolated browser. The isolated Harness browser is an independent backend, not an automatic
+fallback for the native provider. A host plugin's `surfaces` description labels that fallback and its
+limits; it does not assert full browser parity.
+
+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.** Element targets prefer semantic role/name/text. A visually empty element may still be
+  annotated when it has a specific CSS selector (ID, test ID, classes, and a structural path when
+  needed); bare tag selectors are not enough. Reveal checks for one live match and preserves any
+  captured semantic/context evidence, otherwise reporting ambiguous or unresolved. Text annotations
+  continue to use quote plus context, not screen coordinates.
+- 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.
+- **Web components (PROP-0038).** The helper walks the composed tree: open shadow roots and slotted content can be picked, selected and revealed, and such targets carry `tree: 'composed'`. Targets without it resolve by the document-only rules as before. Closed shadow roots and frames stay out of reach, and the inspector says why it refuses something.
+- **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,136 @@
+# 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. Foundation context behavior, including bounded checkpoint restoration after
+  compaction (PROP-0033), is shared by terminal and embedded sessions; a host does not reimplement it.
+- Workspace write scope is Harness-owned on both surfaces. Each run pins a canonical root after
+  worktree selection; reads retain OS-permission scope, while native file writes and shell
+  filesystem effects default to that root; the filesystem root itself is not a valid workspace.
+  Native mutations revalidate their canonical target and atomically replace the file under an OS
+  write scope. Default Bash scans for external hard-link
+  aliases and runs under an OS sandbox that prevents its own processes from creating cross-boundary
+  hard links; on macOS the sandbox denies hard-link creation entirely, including within the
+  workspace. `workspaceWriteScope: 'outside'` (terminal `!outside <command>`) requests a human-only
+  approval before one execution, showing the complete escaped command in scrollable terminal details
+  and denying if the terminal is too small. Output never triggers approval or retry. Hosts may
+  tighten or deny policy but cannot silently waive the boundary. Only the eligible Full Permission
+  switch may answer automatically under its existing restrictions. A same-user peer process outside
+  Harness is not controlled by this rule. `workspaceRoot` is additive and legacy run records may
+  omit it.
+- Harness core terminal commands use unprefixed names and are registered independently of feature
+  plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents` and
+  `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections shortcut.
+  Every plugin-owned terminal command uses `/<owner-prefix>:<command>`, for required and optional
+  built-ins and Pi extensions alike. Built-in prefixes are stable registry metadata; Pi package
+  extensions use a normalized package name or the package's `harness.commandPrefix`, and loose
+  extensions use their normalized extension name. Prefix collisions and duplicate commands within
+  one owner are rejected with owner diagnostics. Built-in plugin modules may declare a default
+  command for their namespace root. The former owner-qualified and `/plugin:<command>` forms of
+  promoted Harness commands remain hidden compatibility aliases for one release. Prompt templates
+  and `/skill:<name>` keep their existing forms. Built-in plugin categories remain documented in
+  page 06, not public 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,
+  with no terminal-only question alias (PROP-0040). Plan-mode delegation
+  is limited to named profiles whose effective tool and plugin allowlists qualify for read-only
+  research; both terminal and host use the same gate and child-capability narrowing.
+- 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.
+- PROP-0040 defines one shared launch/command contract: `Launch.standard`, `commands.list`,
+  saved-history controls and tracked `SessionRunInput.command` runs. Hosts present these rather
+  than approximating navigation with a fork. A listed command or handler is not proof of acceptance.
+  The current host `/session` picker reads a host-owned session catalog rather than a shared Harness
+  catalog (PAR-008), and read-only command pages do not stand in for unsupported management methods.
+  The register records command routes individually; parity remains open until each route passes
+  acceptance.
+- Read-only `get_capabilities` is implemented in structured sessions and the terminal. Structured
+  sessions report tools filtered by the run's frozen capability set and actual registered schemas;
+  the terminal reports Pi's active tools and schemas, applying its plan-mode allowed set when active.
+  It is in the shared plan-mode allowlist and grants no permission. Hosts use this Harness tool rather
+  than defining a duplicate.
+- `browser/contracts.ts` owns shared backend-neutral browser schemas. A native WebKit host backend
+  still lacks accessibility snapshots and snapshot-ref interactions, browser screenshots, waits and
+  keyboard input; unsupported calls return an explicit refusal before effects and do not trigger an
+  automatic backend switch (page 13, PAR-015).
+- Shared interactive defaults, profile adoption, credentials and a cross-surface session catalog
+  remain in progress under PROP-0040. Existing pins and explicit profile choices win; adoption must
+  not merge stores, copy credentials or silently downgrade the secret backend.
+- `PluginDescriptor.surfaces` / `Plugin.surfaces` optionally describe a host preference, terminal
+  fallback/unavailability and reason. This labels add-ons, not plugin categories or permissions.
+- 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),
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md).