@xingular/harness 0.1.7 → 1.1.1

package/docs/architecture/09-accounts-and-connectors.md

@@ -0,0 +1,98 @@
+# 09 Accounts and connectors
+
+## Purpose
+
+**Accounts** are isolated Pi identities: each has its own agent folder, credentials, sessions and
+history, so one person can use several providers and subscriptions without them mixing.
+**Connectors** (connected apps) are MCP servers a session reaches through a broker, with scoped
+access, approval of non-read calls, and redaction. The **Hub** installs exact catalog versions of
+skills, prompts, rules and Pi packages.
+
+## Components
+
+| Type / function | Module | Role |
+|---|---|---|
+| `Accounts` | `accounts/accounts.ts` | Accounts and pools: `resolve`, `context`, `runtime`, `models`, `status`, sign-in (`loginStart`, `loginStatus`, `loginRespond`, `loginCancel`), `setApiKey`, `signOut`, terminal accounting. |
+| `isolateProcess`, `ensureSharedDir`, `sharedDir` | `accounts/env.ts` | Isolated launch environments. |
+| account store, audit | `accounts/store.ts` | The registry and audit log. |
+| `SecretStore`, `secretKey`, `fileSecretStore`, `memorySecretStore` | `accounts/secrets.ts` | Where credentials live (page 01). |
+| `ConnectedApps` | `mcp/service.ts` | The broker: `grant`, `session`, `expose`, `tools`, `revokeRun`, `callUnattended`, traces. |
+| `Connections` | `mcp/connections.ts` | Saved connections, scopes, secrets, `redactEvent`, `scrub`. |
+| `McpManager` | `mcp/manager.ts` | MCP clients. |
+| OAuth | `mcp/oauth.ts` | Sign-in; an application's own registered clients (`AppOAuthClients`). |
+| `Hub` | `hub/hub.ts`, `hub/schema.ts` | Catalog, preview, install, uninstall, receipts. |
+
+## Contracts
+
+- **Account folder.** Every Pi session gets its account's own agent folder
+  (`PI_CODING_AGENT_DIR`) under `<state dir>/accounts/`. Settings, skills, prompts and
+  instructions are shared through links to `_shared/pi/`; credentials, sessions and history stay
+  in the account's own folder.
+- **Resolution.** A new session may name an account, a pool, or neither (the default). Once
+  started, it stays on that account.
+- **Sign-in progress** lives in the running process only. `accounts.loginStatus` recovers the
+  current code or prompt with a revision; it is never written to account files.
+- **Broker tools.** `mcp_list_tools` and `mcp_call_tool`. A connection reaches a session only if
+  its scope allows the caller and the policy's `connections` keeps it. Calls that are not reads
+  are approved through the gate. Each call's redacted result is traced in `mcp-context.json`.
+- **`apps.expose(tools)`** offers the application's own tools through the broker, which is how a
+  terminal session reaches them.
+- **Hub.** `hub.list`, `get`, `preview`, `install`, `uninstall`, `readDocument`. Pi packages need
+  an exact npm version or a full Git commit. Documents are saved as inert JSON.
+
+## Invariants
+
+- **INV-ACC-1** Accounts are isolated. A session runs in its account's own Pi folder, never in
+  `~/.pi`. The process drops inherited credential variables (`*_API_KEY`, `*_AUTH_TOKEN`,
+  `*_OAUTH_TOKEN`, `*_ACCESS_TOKEN`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `PI_CODING_AGENT_DIR`)
+  before any session starts.
+- **INV-ACC-2** An account is never exchanged for another. A pinned session that cannot use its
+  account fails. Changing account for a terminal is an explicit person's action that restarts
+  the child.
+- **INV-ACC-3** The harness never writes a secret to its own files; it asks the `SecretStore`.
+  The default file store is owner-only (`0600`).
+- **INV-ACC-4** A terminal's `/accounts` goes through the session socket's `accounts.*` calls, and
+  every one needs the session's control key. A command the model runs in the shell cannot make
+  an account change.
+- **INV-MCP-1** Connector secrets live in the `SecretStore`; `connections.json` holds no secret.
+  Run events and traces are redacted before they are stored or shown.
+- **INV-MCP-2** A session reaches only the connections its scope and the policy allow, and loses
+  them when its run ends (`revokeRun`).
+- **INV-MCP-3** An application's OAuth client is usable only by a catalog entry it lists, and
+  nothing of it is stored.
+- **INV-MCP-4** Hub installation grants no attachment, trust, credential or permission. Writes
+  are serialized; existing registry files are never overwritten; uninstall removes only the exact
+  receipt's resources and revokes its attachment choices.
+
+## Data
+
+```text
+<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log
+<state dir>/secrets.json      default SecretStore (owner-only)
+<state dir>/connections.json  connected apps, no secrets
+<state dir>/hub/catalog.json  catalog cache
+<data root>/hub/              installed documents and provenance
+<data root>/runs/<id>/mcp-context.json
+```
+
+## Source map
+
+`src/accounts/*.ts`, `src/mcp/*.ts`, `src/hub/*.ts`. Decision:
+[ADR-0005](../decisions/ADR-0005-app-provided-oauth-clients.md).
+
+## Account and connector diagnostics
+
+`Accounts.inspect` reads credentials and a non-refreshing Pi model catalogue through a read-only
+credential store. It never refreshes OAuth tokens or verifies a key over the network. `/doctor`
+labels this local readiness. A selected live model probe sends one synthetic request, caps output
+at 64 tokens, and records usage through the normal run writer. It never substitutes an account.
+MCP live diagnostics connect and list tools on the selected scoped connector, without calling
+connector tools or starting sign-in. Disposable grants and clients are closed afterwards.
+
+## Terminal connection setup
+
+The unified browser exposes existing connection save/test/sign-in/sign-out/remove services through
+private terminal controls (PROP-0013). New definitions are saved disabled. Saving does not connect,
+sign in or approve tools. Secrets use masked fields and the existing secret store; snapshots omit
+saved credential values and scrub connection errors/tool metadata. Hub documents remain inert until
+a person explicitly chooses setup and completes the normal validated connection form.

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

@@ -0,0 +1,193 @@
+# 10 Server protocol
+
+## Purpose
+
+A host that is not a Node program embeds the harness as a child process and talks to it over
+newline-delimited JSON on stdin and stdout. The protocol exposes the same in-process API a Node
+application uses, run events as they are saved, state-change notices, and calls from the harness
+to the host for the extension points the host supplies.
+
+## Components
+
+| Type / function | Module | Role |
+|---|---|---|
+| `RpcPeer`, `Transport`, `stdioTransport`, `PROTOCOL_VERSION` | `server/rpc.ts` | Framing, requests, replies, host calls. |
+| `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]`. |
+
+## Contracts
+
+```text
+host → harness   { v: 1, id, method, params }        harness → host   { v: 1, id, result | error }
+harness → host   { v: 1, event }                     a run event, validated, after it is saved
+harness → host   { v: 1, notice }                    state changed: read it again
+harness → host   { v: 1, id, call, params }          host → harness   { v: 1, id, result | error }
+```
+
+- 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`, `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
+  `plugins.describe`.
+- `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`).
+
+## Invariants
+
+- **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. Adding a method
+  to an existing group is an additive change (update this page). Renaming, removing, or changing
+  the params or result shape of a method is an architecture change.
+- **INV-SRV-2** A method handler calls the same in-process API a Node application uses. The server
+  holds no logic of its own beyond parameter checking.
+- **INV-SRV-3** Events reach the host only after they are persisted and redacted (`INV-RUN-3`).
+- **INV-SRV-4** Changing the framing or `PROTOCOL_VERSION` is an architecture change.
+- **INV-SRV-5** The harness works with none of the host calls supplied (`INV-EXT-2`).
+- **INV-SRV-6** After a change to the server, the CLI or startup, `npm run prove` must pass: it
+  starts the server on a throwaway data root with no application present and exercises accounts,
+  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`.
+
+## Doctor jobs (PROP-0011)
+
+| Method | Input | Reply |
+|---|---|---|
+| `doctor.start` | `{ context: { caller, cwd, accountId, model, tools, variant?, capabilities? }, mode?: "local" \| "live", checks?: string[], confirmed?: boolean }` | `DoctorReport` |
+| `doctor.read` | `{ id }` | `DoctorReport` |
+| `doctor.cancel` | `{ id }` | `DoctorReport` |
+
+A trusted host attests confirmation for the exact selected live checks. Live mode requires both
+`confirmed: true` and non-empty `checks`. Terminal equivalents are `terminal.doctor.*`; every call
+requires the control key and each job belongs to its originating terminal. The terminal supplies
+its account and pinned variant; the controlled frontend supplies its current model and tool list.
+
+Reports carry job state (`running`, `completed`, `cancelled`), progress, timestamps, selected
+account/model, findings, and available live-check notices. Findings distinguish `local` from
+`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

@@ -0,0 +1,261 @@
+# 11 Terminal
+
+## Purpose
+
+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.
+
+## Components
+
+| Type / module | Role |
+|---|---|
+| `Terminals` (`terminal/terminals.ts`) | Parent side: `prepare` (account, compiled context, trusted resources, run writer) returns a launch specification; `send`, `state`, `input`, `dispose`. |
+| `src/terminal/opentui/` (`app.ts`, `root.tsx`) | The OpenTUI/Solid frontend: lifecycle, submission, commands, decisions, composition, transcript, composer, dialogs. |
+| `src/terminal/opentui/attachments.ts`, `composerMarks.ts` | Composer attachments: pasted images and collapsed large pastes, their atomic labels, and expansion into the prompt text and Pi image content on send. |
+| `src/terminal/tui/runtime.ts` | `AgentSessionRuntime` over `createAgentSession`, `ModelRuntime`, `SessionManager`, `DefaultResourceLoader`. |
+| `src/terminal/socket.ts`, `client.ts`, `control.ts`, `controller.ts` | The session socket, the private control key, and the run controller. |
+| `src/terminal/piExtension.ts` | The bridge extension, loaded last as the trusted inline gate. |
+| `src/terminal/cli.ts` | Wiki and connected-apps commands for the session's shell. |
+
+```text
+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 dialogs, full-screen resource browser
+```
+
+## Contracts
+
+- 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
+
+- **INV-TUI-1** OpenTUI is the only terminal frontend. Pi's `InteractiveMode` is never constructed
+  ([ADR-0006](../decisions/ADR-0006-opentui-only-terminal.md)).
+- **INV-TUI-2** The harness owns screen composition, input, scrolling, command routing and plugin
+  UI. Pi owns the execution runtime, native history and rich content components. A host owns the
+  PTY and process supervision ([ADR-0001](../decisions/ADR-0001-owned-terminal.md)).
+- **INV-TUI-3** Execution, account isolation, trust, authorization and run recording stay behind
+  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, `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, [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)
+
+The bridge registers `session_name` against Pi's `getSessionName` / `setSessionName` APIs.
+The native `session_info_changed` event invalidates the frontend's cached snapshot and
+refreshes the working line. Both the active and retained completion line append
+` – <name>` after duration and token rate, for example
+`Working (2m, 50 tok/s) – Add web browser integrations`. Unnamed sessions omit the suffix.
+Names use the existing terminal text sanitization, remain outside the verb shimmer, and
+truncate at the right edge. Manual `/name` and existing long names remain supported.
+
+## Doctor command
+
+`/doctor` opens a command page and runs local readiness checks. Refresh and retry are local;
+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

@@ -0,0 +1,75 @@
+# 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   (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)
+  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)
+  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
+
+<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/             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
+  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`).
+
+## 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.