@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/12-storage.md

@@ -0,0 +1,118 @@
+# 12 Storage
+
+## Purpose
+
+The harness keeps two folders. The **data root** holds knowledge and history that may be shared
+or synced: variants, refinements, the library, the Wiki, runs. The **state directory** holds
+device-local state that must never travel with the data: accounts, secrets, approvals, trust,
+connections, sockets. Files are the source of truth everywhere; the only database is a derived
+index.
+
+## Layout
+
+```text
+<data root>/
+  variants/<scope>/   versions/<fingerprint>/{variant/, version.json}, head.json, lineage.jsonl, restores.jsonl, tags.json   (03)
+  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)
+  legacy/              an earlier Wiki's data, moved once   (08)
+  registry/            skills/, prompts/, rules/: the component library   (03)
+  plugins/<name>/      packages kept with the data   (06)
+  plugin-proposals/<id>.json   pending and decided proposal text, hash and status; owned by plugins/proposals.ts   (06)
+  trash/plugins/       removed packages   (06)
+  hub/                 installed documents and provenance   (09)
+  runs/<id>/           run.json (including optional legacy-compatible workspaceRoot and workspaceSnapshot), 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; every live reply emits one
+  # heartbeat per 30 seconds (about 60 KB an hour) and no side file (PROP-0041, ADR-0054).
+  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, recall, usage ledger)   (08, PROP-0042)
+  projects.json        read only: the application owns it
+
+<state dir>/
+  accounts/            registry, per-account Pi agent folders, _shared/pi/, audit log   (09)
+  secrets.json         default SecretStore, owner-only   (09)
+  approvals.json       standing approvals   (07)
+  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/                 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.json        device-local BrowserConfig: backend, CDP, private-address policy and domains   (13)
+  browser/             isolated profiles, downloads, and owner-only extension-bridge.json pairing state   (13, ADR-0082)
+  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 and long-lived harness diagnostics
+  harness.sock         the long-lived harness's protocol socket, owner-only, while it runs   (10, ADR-0083)
+  harness.lock         { pid, startedAt, socket } of the one long-lived harness for this folder   (10, ADR-0083)
+```
+
+`/remote-control` (page 15) stores nothing here: its pairing and device keys live in memory and end
+with the session (INV-RC-2).
+
+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 state directory (or the `--account-state` one), even if that profile names a host
+backend; it does not use or alter host credentials.
+
+A standalone launch can take its account identity from another state directory:
+`--account-state <dir>` uses that directory's `accounts/` folder (`HarnessOptions.accountsDir`) and
+its `secrets.json`, so an account signed in by one launch is the account and credential of the
+other. `scripts/dev.mjs` passes the installed command's state directory, so development and
+installed launches share accounts and sign-in while keeping separate data roots, approvals, plugin
+trust and connections. A launch that shares an account folder must use the `SecretStore` that
+folder's account ids belong to; the registry, account folders and shared settings travel together.
+
+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
+  written to the data root, and knowledge or history is never written to the state directory.
+- **INV-STO-2** Files are the source of truth. `index.sqlite` can be deleted and rebuilt
+  (`INV-MEM-5`); its migrations are append-only (`INV-MEM-6`).
+- **INV-STO-3** Each folder has one owning module, named on its page. Another module reads it
+  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
+
+`src/harness.ts` (`open`), `src/core/fs.ts`, `src/core/index.ts`, and the store module of each
+part, listed on its page.

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

@@ -0,0 +1,114 @@
+# 13 World tools
+
+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. The same
+backend-neutral browser tools can also target an explicitly paired Brave extension, which controls
+normal tabs on origins separately permitted by the person; Incognito is excluded, and the
+extension never requests history or cookie permissions or exports cookies (page content can still
+reflect the person's active sign-in). Every tool passes the same capability and policy gate. Web requests use the
+public-address guard; isolated-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. A disconnected or
+paused Brave bridge refuses calls and never switches to another backend.
+
+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.
+Other hosts may add backend capabilities and diagnostics through ToolProvider or WorldPart.
+
+Browser configuration is device-local. The selected backend is either the isolated engine or
+Brave. The extension bridge listens only on loopback, pairs with a short-lived code, and persists
+its bearer token and extension origin in owner-only state. Pairing validates the extension origin; subsequent calls require the bearer token and reject a mismatched Origin when present because service-worker fetches may omit that header. The extension uses the browser debugger
+API. Chrome host grants can cover every port on a host, so the extension separately records each exact allowed origin (scheme, host and port) and checks it before exposing a tab; the loopback bridge permission alone never enables site access. It does not request history or cookie access or export cookies.
+User-configured CDP attachment is explicit; diagnostics never attach to it. Doctor browser probes
+instead use disposable headless profiles and an offline synthetic page. Their input runs only after
+live-check confirmation, and their resources are released on completion, timeout or cancellation.
+Computer interaction needs a host-provided isolated surface; without one it is blocked.
+
+## Approved-window screenshot contract
+
+`computer/screenshot.ts` defines an opt-in host provider adapter for `computer_screenshot`.
+The backend must capture exactly one currently approved window, excluding the desktop, other windows
+and overlays even when they overlap, and refuse if it cannot guarantee that scope. It must not
+fall back to a display capture. Coordinates supplied to a host's related interaction tools, if any,
+are relative to the returned image pixels. The tool goes through the ordinary provider and gate,
+returns an image to the model, and is not plan-mode safe by default. Image content is untrusted.
+The contract itself does not prove that a host implements these requirements. In particular, the
+existing macOS host capture has not yet adopted this contract and captures a display; it must not
+be represented as approved-window-only capture. The standalone terminal has no capture backend.
+
+`computer/contracts.ts` and `computer/control.ts` define an unregistered, session-bound adapter for
+future approved-window interaction. Its opaque target and screenshot IDs, bounded inputs, stale
+capture checks and concurrency guard do not authorize a call. A provider must enforce the gate and
+human approval independently, and its backend must enforce target identity, window isolation,
+sensitive-field refusal and run liveness at the point of effect. No terminal computer tools are
+registered through this adapter. `computer/boundary.ts` adds an unregistered, run-bound transaction
+that asks for a fresh human decision for each action and revalidates after approval; it is not a
+replacement for the normal gate or for point-of-effect enforcement in the backend. The terminal
+socket has a one-shot client operation that does not replay a request after a lost reply. Neither is
+wired to computer tools. `computer/terminalCapture.ts` adds an unregistered read-only bridge with
+person-controlled selection, per-capture approval and revocation; its host must still enforce
+window isolation at capture time. `computer/volatileImages.ts` is an unregistered experiment that
+sanitizes computer screenshot results before Pi session persistence and restores their images to an
+in-memory request projection; it is not connected to a runtime and cannot protect host logs or
+provider retention. `native/computer/` contains disabled capture and picker prototypes: isolation
+and continuous approval are not established. Terminal integration and native input delivery need a
+verified authorization boundary before they can be exposed; an implementation that cannot enforce
+window confinement must refuse rather than post global input.
+
+
+## Shared browser contract and host backend limits (PROP-0040, ADR-0082)
+
+`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 and the connected Brave adapter support accessibility snapshots and snapshot-scoped refs.
+The Brave adapter relays calls through the paired extension, enforces the extension's exact-origin allow list and
+network policy, and invalidates refs when the page or debugger attachment changes. A native WebKit
+host backend supports navigation, tab management, visible-text reads, page screenshots and
+page-level scrolling without a ref. It does not support accessibility snapshots, snapshot refs or
+ref-based click/type/select/scroll/screenshot, browser waits or keyboard presses. Native page
+screenshot implementation and authorization checks are present, but live host capture acceptance
+remains open.
+
+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
+another backend. The isolated Harness browser and Brave extension are separate device-selected
+backends, not fallbacks for a host's native provider. The App's `browser_upload` remains its own
+WebKit-only operation and is absent from the shared Brave tool set. A host plugin's `surfaces`
+description labels its fallback and 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 browser provider and its plugin
+descriptor, then supply its own provider. `HarnessOptions.browserExtension` keeps the Harness-owned
+Brave bridge available alongside that host provider. The App uses both options: its WebKit provider
+remains separate, and Brave mode supplies `browserToolsForSession` from the Harness. Provider calls
+are pinned to the selected backend and never fall through to another browser.
+
+## 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, sending and app targets (PROP-0018, PROP-0048).**
+
+- **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 two choices: Annotate and Annotate & send.
+  - With a session, every note is shared with it at once and is pending (unsent) until sent.
+  - `annotations/delivery.ts` sends all of a session's pending notes as one message, with the
+    person's request last when given, and sends notes held back while the session was busy when its
+    run ends, trying again while the session still answers busy.
+  - The page-note tools are read-only. Only the person resolves a note.
+- **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. `discover` probes loopback ports 9222–9230 and ports used before (a Node inspector is skipped); `launchApp` starts a program (the one inside a macOS `.app`) with `--remote-debugging-port` on a free loopback port and attaches. A started app keeps running.
+  - **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,151 @@
+# 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, todo |
+| 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.
+  The direct `/plugins` page manages local plugin state and package lifecycle; `/hub` presents the
+  Community catalog and all installed Hub receipts. These are distinct presentations of existing
+  Harness services, not host-only capabilities. The broad `/harness` browser remains available.
+- 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. Package-owned prompt templates use the same owner namespace;
+  standalone prompt templates and `/skill:<name>` keep their existing forms. Bare plugin and generic
+  `/plugin:<command>` aliases are not routes. 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, and neither changes the answer payload (PROP-0025,
+  ADR-0026; originally PROP-0024). Shared `ask_user` guidance asks the model to use a fixed
+  80-column canvas, but validation remains permissive for shorter sketches. The terminal pads its
+  display projection to 80 content columns, bounds the outer frame to the available dock width and
+  provides horizontal panning. It 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 fixed 80-column canvas and join the outer frame with `├` and `┤` (PROP-0026, ADR-0027,
+  amended by ADR-0080). Prose, content operators and ordinary pipes are not globally substituted.
+  Hosts may retain literal ASCII previews with accessible overflow; 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. The isolated Harness engine
+  and paired Brave extension implement the snapshot-ref contract. A native WebKit host backend lacks
+  accessibility snapshots and snapshot-ref interactions, waits and keyboard input; it supports page
+  screenshots without refs in source, with live acceptance pending. The App chooses WebKit or Brave
+  at the device level; unsupported calls return an explicit refusal before effects and never trigger
+  an automatic backend switch (page 13, PAR-015, ADR-0082).
+- 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.
+- Remote control (page 15) is a third Harness-owned surface of a terminal session: a phone page the
+  harness serves. It is not a host and owns no capability. A paired device acts through the same
+  `Terminals` and controller paths as the terminal, and reaches no command, shell, link, plugin or
+  account control.
+- The terminal is a client of the harness by default (page 11, ADR-0083): it presents the same
+  capabilities over harness live sessions, and its plugin presentation is the host subset
+  (INV-TUI-8). Its runs, approvals and questions are the structured path's, so the terminal and a
+  host share one lifecycle. `XINGULAR_TERMINAL_RUNTIME=inprocess` keeps the in-process runtime.
+- 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).

package/docs/architecture/15-remote-control.md

@@ -0,0 +1,120 @@
+# 15 Remote control
+
+## Purpose
+
+Remote control lets a person continue a live terminal session from a phone or iPad. The session
+keeps running in `xagent` on the computer. A paired device sends messages, watches the reply as it
+streams, stops it, and answers approvals and questions. It works without a cloud relay: the
+harness serves a small web page on the computer's Tailscale address, or its private Wi-Fi or LAN
+address, and the device opens it from a QR code. Remote control ends when the terminal session
+ends ([ADR-0056](../decisions/ADR-0056-remote-control.md)).
+
+A paired device is a second person at the terminal. It reaches the same controller and `Terminals`
+methods the terminal uses and nothing else, so remote control adds a surface, not a capability
+path.
+
+## Components
+
+| Type / module | Role |
+|---|---|
+| `remote/addresses.ts` | Bind candidates from `networkInterfaces()`: Tailscale (100.64.0.0/10, fd7a:115c:a1e0::/48) first, then RFC 1918 IPv4. `pickRemoteAddress(auto\|tailscale\|lan)`. |
+| `remote/seal.ts` | Sealed frames: NaCl `secretbox` (XSalsa20-Poly1305, `tweetnacl`) with a random 24-byte nonce; a counter inside each frame, checked by `ReplayGuard` (a 256-counter window). |
+| `remote/pairing.ts` | `Pairing`: the pairing link (id and key), one waiting pair request, paired devices (`RemoteDevice`), limits, rotation. |
+| `remote/server.ts` | `listenRemote`: `node:http` on one address; the page assets, `POST /rc/hello`, `POST /rc/call`, `GET /rc/events` (server-sent events). Host and Origin checks, body caps, no-store and CSP headers. |
+| `remote/service.ts` | `RemoteControl` for one terminal session over a `RemoteSessionPort`: start, stop, rotate, confirm, status and `waitStatus`; projects run events and decisions for the phone. |
+| `remote/webClient.ts` | The phone page: HTML, CSS and script, served as is. |
+| `terminal/tui/pages/remoteControlPage.ts`, `terminal/tui/qr.ts` | The `/remote-control` page and its half-block QR code (`uqr`). |
+
+```text
+Phone browser ── http://<tailscale or LAN address>:<port> ──> RemoteControl (xagent parent)
+   sealed hello / calls / events                                  │ RemoteSessionPort
+                                                                   ├─ Terminals.send
+                                                                   ├─ TerminalController.control (interrupt, approve, answer, pending.wait)
+                                                                   └─ RunRegistry.listen (this session's own runs)
+```
+
+## Contracts
+
+- **Terminal surface.** `/remote-control` (alias `/rc`) starts remote control for the current
+  session and opens its page: the link, the QR code (space hides it), the address kind, paired
+  devices, and a waiting pair request. Keys: `c` copy the link, `n` a new link (every device is
+  unpaired), `t` switch between Tailscale and Wi-Fi when both exist, `x` stop, `a`/`d` allow or
+  deny a request. Esc closes the page; remote control keeps running. `/rc off` stops it;
+  `/rc tailscale` and `/rc lan` choose the address kind. `xagent --remote-control` (`--rc`) runs
+  `/remote-control` as the terminal opens. The status bar shows `rc` while it is on and `rc ●`
+  while a device is connected. When the page is closed, the terminal asks about a pair request
+  in a confirmation dialog.
+- **Methods.** `terminal.remoteControl.start { interface? }`, `.stop`, `.rotate`,
+  `.confirm { requestId, allow }`, `.status`, `.status.wait { revision }` (returns at once for a
+  changed revision, otherwise within 20 seconds). Each returns a `RemoteStatus`
+  `{ running, revision, url, kind, kinds, devices, request, warning }`. All of them go through the
+  session socket's control key (INV-TUI-4).
+- **Pairing.** The link is `http://<address>:<port>/#<pairingId>.<key>`. A browser never sends the
+  fragment. The phone says hello with a frame sealed by the link key. The request waits up to 50
+  seconds for the person at the terminal to allow it; the reply, sealed by the link key, carries
+  the device's id and its own key. A link pairs one device and is then replaced, so the QR code on
+  screen pairs the next one. At most 3 devices; at most 10 hello attempts a minute; 20 failed
+  attempts replace the link and show a warning.
+- **Calls.** `POST /rc/call { d: deviceId, f: frame }`. The frame holds `{ id, method, params }`;
+  the reply frame holds `{ id, result }` or `{ id, error }`. Methods: `snapshot` (title, the
+  session's own runs as phone events, pending decisions, state), `send { text }`, `interrupt`,
+  `approve { requestId, decision, alwaysAllow? }`, `answer { requestId, answer }`,
+  `answers { batchId, answers }`, `unpair`. Anything else is refused.
+- **Events.** `GET /rc/events?d=&f=` opens a stream of sealed frames:
+  `{ type: 'event', event }`, `{ type: 'pending', requests }`, `{ type: 'ended' }`,
+  `{ type: 'unpaired' }`. A phone event is one of `delta`, `message`, `tool`, `run`, `todo`, with
+  only the fields the page shows: no tool input or output, no context snapshot, no native evidence.
+  An approval's `action` text is sent whole.
+- **Streaming.** The terminal extension batches assistant text deltas (150 ms) into a `delta`
+  telemetry event; the controller records it as `message.delta` under the id the completed
+  `message` then carries. It is not host telemetry.
+
+## Invariants
+
+- **INV-RC-1** Remote control listens on exactly one Tailscale or private LAN address, never on a
+  public address or on all interfaces. With no such address it refuses with the reason. (Tests
+  inject a loopback address through `RemoteControlOptions.bindHost`.)
+- **INV-RC-2** Every remote-control key lives in memory only. Nothing about pairing is written to
+  the data root or the state directory; a phone keeps its own device key in its browser storage.
+- **INV-RC-3** A paired device acts only through the terminal's existing paths: `Terminals.send`,
+  and `TerminalController.control` for `terminal.interrupt`, `terminal.approve`,
+  `terminal.answer`, `terminal.answers` and `terminal.pending.wait`. For a client terminal
+  (ADR-0083) the same calls reach its `LiveTerminal`, and a message goes as a new reply or a
+  follow-up of the live session. The validation those paths
+  apply (a busy session, a terminal draft, the rememberable check on "always allow", the policy
+  recheck of a direct approval) applies unchanged.
+- **INV-RC-4** A decision is shown on the phone with its complete action text, never shortened,
+  beside its choices. The first answer from either surface wins; the other surface's card goes
+  away on the next pending revision.
+- **INV-RC-5** Remote control ends with its terminal session (`Terminals.dispose`): the server
+  closes, connected phones are told, and every device key is forgotten. `stop` does the same
+  without ending the session.
+- **INV-RC-6** A paired device runs no slash command, no `!` shell command and no link, and reaches
+  no plugin, account, Hub, worktree or browser control. A message starting with `/` or `!` is
+  refused.
+- **INV-RC-7** Starting remote control and allowing a device are decisions of the person at the
+  terminal: both are control-key calls, and no phone can pair without that confirmation.
+- **INV-RC-8** Every body between the phone and the harness, except the static page, is sealed.
+  A frame that does not open, or whose counter was seen, is refused the same way.
+
+## Threat notes
+
+Sealing defeats a passive listener on the network and replays. It does not defeat an attacker who
+can change traffic on the LAN (for example by ARP spoofing): the page itself is served over plain
+HTTP, so such an attacker could serve a changed page to the phone. The terminal confirmation is the
+remaining check. The `/rc` page tells the person to use Tailscale, whose traffic is end-to-end
+encrypted, on a network they do not trust.
+
+## Data
+
+None stored. The phone's browser keeps `{ deviceId, deviceKey, label }` under
+`remote-control:<host:port>` in its own storage; it is useless once the session ends.
+
+## Source map
+
+`src/remote/`, `src/terminal/terminals.ts` (`remote`, `remotePort`, `remoteCall`, dispose),
+`src/terminal/controller.ts` (`delta`), `src/terminal/piExtension.ts` (`message_update`),
+`src/terminal/tui/pages/remoteControlPage.ts`, `src/terminal/tui/qr.ts`,
+`src/terminal/opentui/app.ts` (`watchRemoteControl`), `src/terminal/opentui/statusBar.ts`,
+`src/terminal/standalone.ts` (`--remote-control`). Decision:
+[ADR-0056](../decisions/ADR-0056-remote-control.md).