@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/06-plugins-and-capabilities.md

@@ -17,7 +17,8 @@ callable result for one run.
 | `Plugins` (`loading`, `loaded`) | `plugins/plugins.ts` | Chooses the paths a session or terminal loads; records what each extension registered. |
 | discovery | `plugins/discover.ts` | Finds items with Pi's own resolver, which runs no extension code. |
 | attachments (`load`, `save`, `attached`, `decided`, `set`) | `plugins/attachments.ts` | The one store of what is switched on, per scope. |
-| `HARNESS_PLUGINS` | `plugins/builtin.ts` | Descriptors of the harness's own parts: `pi`, `harness`, `subagents`, `wiki`, `history`, `ask-user`, `checklist`, `connected-apps`. |
+| `BuiltinPluginRegistry`, `BuiltinPluginModule` | `plugins/builtinRegistry.ts`, `plugins/builtin.ts` | Registers built-in modules and their descriptors, world parts, server handlers and plugin-owned terminal commands. Harness core commands live in `commands/registry.ts`, shared by both surfaces. |
+| `HARNESS_PLUGINS` | `plugins/builtin.ts` | Descriptor view of the registered Harness parts and feature plugins. |
 | `FIRST_PARTY_PLUGINS` | `plugins/firstParty.ts` | `output-trim`, `budget-guard`: inline extensions shipped switched off. `lessons`: switched off; its contribution turns on reflection after a run (page 08, PROP-0008) and loads no Pi code. |
 | `Hooks` | `plugins/hooks.ts` | Runs a package's hooks file after a write. |
 | install / trust | `plugins/install.ts`, `plugins/trust.ts` | Install through Pi's package manager with scripts off; trust code by hash. |
@@ -28,21 +29,41 @@ callable result for one run.
 ## Contracts
 
 - **Loading.** `Plugins.loading({ cwd, agentDir, caller, contributions, install? })` returns
-  `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `builtins` (terminal only), `hooks`,
+  `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `builtins` (legacy shape; no Pi CLI built-ins selected), `hooks`,
   `found`, `detached`, `projectCode`, `packageCode`. A session opens Pi with its own discovery off
   and only these paths; a terminal receives them as `--extension`, `--skill`,
   `--prompt-template` and `--theme` after `--no-extensions --no-skills --no-prompt-templates
   --no-themes`. Pi still reads `AGENTS.md` and `SYSTEM.md` itself.
+- **Surface metadata (PROP-0040).** `PluginDescriptor.surfaces` and `Plugin.surfaces` optionally
+  carry `{ preferred: 'host', terminal: 'fallback' | 'unavailable', note: string }`.
+  `plugins/surfaces.ts` formats the note and badge. Inspection explains what the host adds and
+  what the terminal does instead; this is not a category, attachment switch or permission.
+- **Shared resources (PROP-0040).** Both surfaces load Harness-selected resources and enabled
+  first-party hooks, including output trim and budget guard. Terminal preparation exposes these
+  through its protected bridge. Pi CLI-only llama.cpp, codemode, tool-search and MCP built-ins are
+  not selected or advertised as extra terminal capabilities. This does not remove Harness MCP.
 - **Attachments.** `config/plugin-attachments.json` holds `global`, `agents`, `projects` (each
   `{ on, off }`) and `settings` per plugin. The narrowest scope that says something wins: agent,
   then project, then everywhere. With no entry an item keeps its default.
+- **Package metadata.** A Pi package may declare `"harness": { "extends": [...], "hooks": "./hooks.mjs", "commandPrefix": "my-tools" }`.
+  `commandPrefix` is optional; in the terminal, commands otherwise use a normalized package name as
+  their owner prefix. Prefixes use lowercase letters, digits and hyphens, starting with a letter;
+  `plugin` and `skill` are reserved. See page 11 for the command route and collision rules.
 - **Hooks.** A package declares `"harness": { "extends": [...], "hooks": "./hooks.mjs" }`. Events:
   `wiki.page.saved`, `history.run.ended`. A hook has 30 seconds; its errors are kept in
   `plugin-hooks.json`. `ctx.call(connection, tool, args)` reaches only a connected app that is on
   for everyone, and only a tool marked to run without asking.
 - **Capability set** (`CapabilitySet`): `{ version: 1, tools, connectors, contributions }`.
   `capabilities.resolve` returns the set available to a caller; `capabilities.intersect` /
-  `toolIntersection` narrows it for a child.
+  `toolIntersection` narrows it for a child. The required `ask-user` plugin remains attached, but its
+  `ask_user` tool is included only for an attended plan run or a continuation pinned with that
+  capability. Automatic or refinement-triggered continuations with it are rejected rather than
+  weakening the frozen set. The `side-questions` descriptor owns the fixed instruction for the
+  restricted side-question run; it has no tools, providers, connectors, subagents or variant code
+  (PROP-0019). In plan mode, delegation is limited to research children: the resolved profile must
+  have explicit tool and plugin allowlists confined to the research set, and the child's frozen
+  capabilities are intersected with the parent and profile. A profile name or its instructions alone
+  never grants eligibility (INV-RUN-8).
 
 ## Invariants
 
@@ -70,8 +91,19 @@ callable result for one run.
   each delivery. A working folder's package cannot bring a hook.
 - **INV-PLG-9** Unattended runs load no extension found on disk (`INV-RUN-5`). The harness's own
   parts are required and refuse to be switched off; switching something on grants no permission.
+  A side-question run also has no variant plugin code or tool guidance (PROP-0019).
+- **INV-PLG-10** Every Harness-managed built-in feature is registered by `BuiltinPluginRegistry`.
+  Its descriptor, world tools, server handlers and any plugin-owned terminal commands share one
+  owner. First-class Harness terminal commands are registered by the terminal command registry and
+  do not depend on a feature plugin's command metadata or attachment state. A module's world part
+  releases resources through the existing session and Harness lifecycle. This registry does not
+  load third-party Pi code or bypass its trust checks.
+- **INV-PLG-11** Built-in plugin categories are a documentation ownership taxonomy. They are not a
+  `PluginDescriptor` field, a public response field or a second attachment scope.
 - **INV-CAP-1** A capability set only narrows. `intersect` never adds access; a run's set is
-  frozen when it starts (`INV-RUN-2`).
+  frozen when it starts (`INV-RUN-2`). An agent profile's `plugins` list keeps only the parent's
+  contributions of those plugins (required plugins always stay) and drops the tools they own; it
+  never adds one (PROP-0029).
 - **INV-CAP-2** The capability contract is generic. It names no application task, role or UI
   concept.
 - **INV-CAP-3** A capability set says what may be called, not whether a call may run. The gate
@@ -91,3 +123,24 @@ callable result for one run.
 ## Source map
 
 `src/plugins/*.ts`, `src/capabilities/*.ts`, `src/core/changes.ts`.
+
+## Built-in ownership taxonomy (PROP-0020)
+
+These categories make ownership visible in docs and source layout. They do not change plugin
+metadata or availability:
+
+| Category | Features | Foundation boundary |
+|---|---|---|
+| Foundation | Accounts, sessions and run recording, prompt and variant validation, gate, plugin loading/trust/attachments, resource browser, server and terminal frameworks | Release-owned infrastructure and security contracts |
+| World | Web search/read tools, browser tools, page annotations | The isolated browser engine and network policy remain Foundation services |
+| Memory | Wiki, history and trajectory | Storage and run records remain Foundation-owned services |
+| Automation | Subagents, ask-user, checklist, lessons and refinement | Run lifecycle, capability narrowing and approval gate remain Foundation-owned |
+| Integrations | Connected apps/MCP and Hub | Connector credentials and plugin installation remain behind Foundation services |
+| Operations | Doctor, worktrees and usage | Diagnostics, repository operations and usage analytics remain Harness-managed services |
+
+## Terminal resource inspection
+
+The unified browser joins saved plugin/contribution metadata with actual session skills and tool
+registration. A saved on/off state does not prove a resource loaded; origins and owners distinguish
+same-name resources. Protected install/remove, settings, attachment and trust actions call the
+existing services. No second discovery or enablement mechanism is introduced (PROP-0013).

package/docs/architecture/07-tools-and-gate.md

@@ -4,7 +4,9 @@
 
 A run's tools come from four places: the harness's own tools, the connected-apps broker,
 subagent tools, and the application's tool providers. Every call, whatever its source, passes one
-per-call gate that asks the application's policy, then standing approvals, then the person.
+per-call gate. Native writes also obey the run's pinned workspace boundary, with shell writes
+contained by an OS sandbox; the gate then applies application policy, standing approvals and the
+person without letting remembered per-tool grants widen that boundary.
 
 ## Components
 
@@ -13,30 +15,90 @@ per-call gate that asks the application's policy, then standing approvals, then
 | `HarnessToolDefinition`, `RECALL_TOOLS`, `TRAJECTORY_TOOLS`, `WIKI_READ_TOOLS`, `WIKI_WRITE_TOOLS`, `SKILL_TOOLS`, `DEFAULT_TOOL_NAMES` | `tools/definitions.ts` | The harness's own tools, defined once. |
 | `dispatch` | `tools/dispatch.ts` | One entry point for every History, Wiki and skill call, from a Pi tool, the server or a terminal. |
 | `harnessTools` | `tools/harnessTools.ts` | The definitions as `ToolSpec`s for one session. |
-| `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops the run and asks a question with choices. |
-| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. |
-| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent`, `wait_subagents`. |
+| `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
+| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `checklist` telemetry call. The prompt's Progress group asks the model to keep it current and write one final update before replying; unfinished work is not automatically marked complete. |
+| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
+| `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
 | `Approvals`, `decide`, `grant`, `approvalKey` | `sessions/approvals.ts` | Standing approvals. |
 
-Harness tools: `history_search`, `history_read`, `trajectory_search`, `trajectory_read`,
-`wiki_search`, `wiki_read`, `wiki_list`, `wiki_write` (not in the default set), `skill_load`,
-`ask_user`, `checklist_write`. Broker: `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
+Harness tools: `get_capabilities` (read-only current-run discovery), `history_search`, `history_read`,
+`trajectory_search`, `trajectory_read`, `wiki_search`, `wiki_read`, `wiki_list`, `wiki_write`
+(not in the default set), `skill_load`, `ask_user` (attended plan runs and pinned continuations only),
+`checklist_write`. Broker:
+`mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
+## Cross-surface registration (PROP-0040)
+
+The terminal registers Harness History/trajectory, Wiki-read and skill tools through
+`Terminals.ownTools` and dispatches them over the session socket; they are model tools, not merely
+shell commands. Enabled first-party hooks load through the protected `firstParty.list` bridge and
+`terminal/piExtension.ts`. Attended planning uses the shared `ask_user`; the terminal-only question
+alias is removed.
+
+`get_capabilities` is implemented as a read-only Harness tool. Structured sessions register it from
+the current run's frozen capability snapshot and live Pi tool/schema inventory. The terminal
+extension (`terminal/piExtension.ts`) registers the same schema from Pi's active and registered tools;
+when plan mode is active it reports the plan's allowed tool set. `sessions/planMode.ts` includes it in
+the shared read-only allowlist. Host sessions use this Harness tool rather than defining a duplicate.
+It reports availability, never permission, and every call remains subject to the gate.
+
+## Native file paths
+
+The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
+absolute paths, and `~` paths. The working folder is a default location, not a read boundary; the
+operating system's access for the Harness process decides what can be read. The compiled file
+guidance names the configured data root. Each run pins `workspaceRoot`: the nearest Git root or
+worktree above its effective working directory, or the canonical working directory when there is no
+repository. The filesystem root itself is rejected because it would collapse the write boundary.
+`edit` and `write` resolve targets canonically, revalidate the pinned target at mutation,
+and atomically replace the directory entry in a helper process constrained by the OS sandbox. This
+prevents hard-link writes from changing another alias; normal file mode is retained where possible,
+but ACLs and extended attributes are not guaranteed to survive replacement. An outside target
+requires a human-only one-call approval (or an eligible Full Permission answer) and is not covered by
+remembered tool grants.
+
+Bash, including an initial `!` command, runs in an OS-enforced sandbox that permits broad reads but
+writes only inside the root. Before default-scope Bash, Harness scans the workspace for regular-file
+inodes with links outside it; an incomplete scan or possible external alias blocks the command, which
+must be repaired or copied. The sandbox also prevents its own processes from creating cross-boundary
+hard links; macOS denies hard-link creation entirely, including within the workspace. A local process
+outside Harness running as the same user is outside this protection.
+The Bash tool's optional `workspaceWriteScope` defaults to `workspace`; `outside` requests a
+human-only one-call approval before the exact command runs once with broader filesystem access. The
+approval shows the full escaped command in scrollable details and fails closed if the terminal
+cannot show both the details and the choices. The terminal uses `!outside <command>` for the same
+explicit request on a direct initial command.
+stdout/stderr never proves a sandbox denial: denial text cannot request approval, and a command is
+never replayed after partial effects. Full Permission is the explicit eligible-run bypass.
+Unsupported or unavailable sandbox enforcement fails closed. A side-question run has an empty
+capability set and no tools (PROP-0019).
+
 ## The gate, per call
 
+For native `edit` and `write`, the canonical target check is added to policy scope before approval;
+the registered tool can mutate only through the policy-bound atomic helper. Bash workspace scope
+scans for external hard links and then runs under the OS sandbox. An explicit outside scope is
+approved before execution and runs once; stdout/stderr never triggers approval or retry. The
+eligible Full Permission switch may answer the explicit request under its existing restrictions, but
+a remembered tool grant cannot.
+
 ```text
 child run and tool outside its snapshot ─► refuse
-plan mode and tool not research-safe    ─► refuse (before approvals)
+plan mode and tool/call not research-safe ─► refuse (including ineligible spawn profiles, outside-scope or denied Bash; before approvals)
+plan-mode Bash                          ─► read-only OS sandbox, never widened, run once
+canonicalize native write target / verify pinned root
 policy.scope(call)
   not allowed and (automatic or no approval possible) ─► refuse with reason
 policy.authorize(call) throws           ─► refuse
-allowed, not humanOnly, (automatic or not gated) ─► run
-trigger probe or improver               ─► refuse (nobody to ask)
-run.requestApproval(...)                ─► standing approvals may answer, else the person
-  denied                                ─► refuse
+outside native file target              ─► human-only one-call approval; eligible Full Permission may answer
+Bash workspace scope                    ─► hard-link scan, OS sandbox, run once
+Bash outside scope                      ─► pre-execution human-only approval, then run once unconfined
+trigger probe, improver, reflection or unattended ─► refuse anything requiring a person
+run.requestApproval(...)                ─► standing approvals may answer where eligible, else the person
+  denied                                ─► refuse; never replay a command
 policy.authorize(call) again            ─► run or refuse
 ```
 
@@ -50,18 +112,49 @@ the switch and global tools.
 
 - **INV-GATE-1** Every tool call of every run passes the gate. No tool source bypasses it,
   including extension-registered tools (which ask before every call) and the initial Bash command.
+- **INV-TOOL-9** `checkpoint_write` records one bounded handoff for the active run and is read-only
+  and plan-safe: no field changes files, and the record is the `checkpoint` run event (PROP-0041).
+- **INV-TOOL-10** Bash keeps one command budget on every surface: 120 seconds when the call says
+  nothing, 300 seconds as the ceiling without a `reason`, 900 seconds as the maximum, and a timeout
+  returns the partial output with a narrowing instruction instead of blocking the reply.
 - **INV-GATE-2** The gate is the last extension loaded, after disk, variant and inline extensions, so
   it sees the final input of every call.
-- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, then the policy's scope and
-  authorize, then standing approvals, then the person, then authorize again.
+- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, canonicalize native file-write
+  targets, consult the policy's scope and authorize, combine mandatory outside-write approval with
+  that scope, then eligible standing approvals or the person, then authorize again. Native mutations
+  revalidate the authorized target and use atomic replacement inside an OS-enforced write scope.
+  Default Bash scans for external hard links, then runs only inside the OS sandbox. `workspaceWriteScope:
+  'outside'` requests human-only approval before running that exact command once with broader access.
+  Command output never proves a sandbox denial and never triggers approval or replay; earlier
+  side-effects are not repeated. The policy may tighten or deny a call, but cannot waive the boundary.
+  Outside file writes and broad Bash calls cannot use remembered per-tool approval; only the eligible
+  Full Permission switch can answer automatically under its existing restrictions. In plan mode, Bash
+  runs only in the read-only scope (PROP-0043): no writes but a discarded temp folder, no network,
+  no signals outside the sandbox, no macOS mach services; Full Permission and `outside` never apply.
 - **INV-GATE-4** Refinement runs (`probe`, `improver`) never ask a person; what would need one is
   refused, never queued (`INV-REF-4`).
-- **INV-GATE-5** A tool is registered only if its name is in the run's frozen capability set, in
-  that order (`INV-CAP-1`).
+- **INV-GATE-5** SDK tools are registered only if their names are in the run's frozen capability
+  set (`INV-CAP-1`). `get_capabilities` is a read-only Harness tool on structured and terminal
+  surfaces; it reports the frozen callable set and does not grant access. The terminal may retain
+  question-tool definitions in its private Pi inventory, but normal mode deactivates them; a plan
+  request activates only registered questions under its plan-mode gate.
 - **INV-GATE-6** Tool attachment bytes never enter the run-event stream; only references are
   recorded.
 - **INV-GATE-7** Tool descriptions name the product with `{product}` (filled by `describeTool`),
   never an application's name (`INV-BND-2`).
+- **INV-GATE-8** Native reads are bounded by process and operating-system permissions, not by the
+  workspace root; absolute and `~` paths are valid. Every run pins its canonical `workspaceRoot`.
+  Native `edit` and `write` mutations revalidate the authorized canonical target and atomically
+  replace it under an OS-enforced scope; outside targets require human-only one-call approval and
+  cannot use remembered tool grants. Default Bash scans the workspace for possible outside hard-link
+  aliases and is OS-sandboxed to write only inside the root while retaining broad reads; the sandbox
+  prevents its own processes from creating cross-boundary hard links, and macOS denies all hard-link
+  creation in the sandbox. An incomplete scan or missing
+  enforcement fails closed. An explicit `workspaceWriteScope: 'outside'` request is approved before
+  execution and runs once; command output never triggers approval or retry. The terminal exposes the
+  same choice as `!outside <command>`. Full Permission is the only standing boundary bypass and
+  remains subject to host policy, authorization, read-only, plan, unattended, probe, improver and
+  reflection restrictions. The rule does not protect against a peer process running as the same user.
 
 ## Data
 
@@ -70,7 +163,9 @@ the switch and global tools.
 ## Source map
 
 `src/tools/*.ts`, `src/web/*.ts`, `src/sessions/sessions.ts`, `src/sessions/runner.ts`,
-`src/sessions/approvals.ts`, `src/sessions/policy.ts`.
+`src/sessions/workspaceBoundary.ts`, `src/sessions/initialBash.ts`, `src/core/workspaceBashTool.ts`,
+`src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`, `src/sessions/approvals.ts`,
+`src/sessions/policy.ts`. Decision: [ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md).
 
 ## Session naming (PROP-0010)
 

package/docs/architecture/08-memory-and-history.md

@@ -55,7 +55,9 @@ rebuildable SQLite index.
     lessons; nothing is evicted.
   - The `wiki` pointer section says how many lessons there are when there are any.
 - **Index.** Every finished run is indexed when it ends; `open` and `rebuildIndex()` sync from
-  `runs/`.
+  `runs/`. The same pass writes the **usage ledger**: one `usage_requests` row per model request
+  from the run's `usage.updated` events, and one `usage_indexed` marker per run (PROP-0042).
+  `/usage:analysis` queries only that ledger; it is derived and rebuilt from run events.
 
 ## Invariants
 
@@ -84,7 +86,7 @@ rebuildable SQLite index.
 <data root>/wiki/            home.md, library/, projects/<slug>/
 <data root>/wiki-history/    earlier versions of notes
 <data root>/legacy/          an earlier Wiki's memory blocks, facts, revisions, Inbox (moved once)
-<data root>/index.sqlite     derived: pages, links, runs, recall passages (FTS5)
+<data root>/index.sqlite     derived: pages, links, runs, recall passages (FTS5), usage rows
 <data root>/projects.json    read only: the application owns it
 ```
 

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

@@ -67,7 +67,7 @@ skills, prompts, rules and Pi packages.
 ## Data
 
 ```text
-<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log
+<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log, per-account state (health, plan, limits)
 <state dir>/secrets.json      default SecretStore (owner-only)
 <state dir>/connections.json  connected apps, no secrets
 <state dir>/hub/catalog.json  catalog cache
@@ -88,3 +88,41 @@ labels this local readiness. A selected live model probe sends one synthetic req
 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.
+
+## Provider limits (PROP-0042)
+
+A limit reading says what a provider itself reported: a plan window, a credit balance, a rate
+limit, or a configured organization limit. Three sources are used, in order:
+
+1. **Response headers** on the account's own model requests. Each account runtime's providers are
+   wrapped so `onResponse` sees status and headers; a terminal session's own runtime forwards only
+   the limit-bearing headers to the parent over the control-key-protected session socket.
+   `usage/limits/normalize.ts` understands `anthropic-ratelimit-*`, Anthropic unified plan windows,
+   `x-codex-*` and `x-ratelimit-*`, plus `Retry-After` on a 429. Raw headers are never stored.
+2. **The provider's own usage endpoint**, read with `Models.getAuth(provider)` so OAuth refresh
+   stays in Pi's serialized credential path: OpenRouter `GET /api/v1/key`, DeepSeek
+   `GET /user/balance`, Anthropic's organization `rate_limits` for an admin API key (configured
+   limits, not usage), ChatGPT/Codex `GET https://chatgpt.com/backend-api/wham/usage`, and
+   OpenCode Go `GET https://opencode.ai/zen/go/v1/usage`. A Codex request carries the account id
+   from the access token's JWT claim; an OpenCode Go request carries the account's API key.
+   The request is a bounded HTTPS GET that refuses redirects, caps its body, and never puts a
+   credential in an error. An endpoint reading replaces every limit for that provider; a header
+   reading only merges the windows it saw.
+3. **Unavailable**, with a reason. No percentage is invented; local usage is shown instead.
+
+Undocumented endpoints require the usage plugin's `experimentalProbes` setting. Readings are
+cached for `refreshMinutes` (default 10) and refreshed on a page open or an explicit refresh, never
+by a background timer. They are stored in the account's existing state (`limits`,
+`providerLimits`), never in a new file, and no credential is written. A reading carries both `usedPercent` and the additive
+`remainingPercent`. The Limits page is a centered dialog: each window is a label and reset line
+above a quota-left bar, green at 50% or more left, amber from 20–49%, and red below 20%. It adds
+the local seven-day ledger without a label, so a provider's zero reading and this app's own use
+are not confused.
+
+## 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

@@ -12,7 +12,7 @@ to the host for the extension points the host supplies.
 | Type / function | Module | Role |
 |---|---|---|
 | `RpcPeer`, `Transport`, `stdioTransport`, `PROTOCOL_VERSION` | `server/rpc.ts` | Framing, requests, replies, host calls. |
-| `methods(harness)` | `server/methods.ts` | The method table. |
+| `methods(harness)` | `server/methods.ts` | Merges Foundation handlers with built-in plugin handlers from `BuiltinPluginRegistry` and rejects overlapping ownership. |
 | `serve`, `attach` | `server/serve.ts` | Registers the table, forwards events and notices. |
 | `remoteSecrets`, remote policy, directory, tools | `server/remote.ts` | Extension points supplied by the host over the protocol. |
 | CLI `serve` | `src/cli.ts` | `serve --state <dir> --data <dir> --name <product> [--builtins <dir>] [--host-secrets] [--host-policy] [--host-tools] [--host-directory]`. |
@@ -27,9 +27,13 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 ```
 
 - stdout carries only protocol lines; diagnostics go to stderr.
+- Run events use the validated, persisted payload schemas in page 02. `question.requested` may carry
+  the optional bounded ASCII sketch metadata described there; the server relays it without changing
+  answer payloads or the protocol framing (PROP-0024).
 - `harness.methods` lists every method. Groups in the table: `accounts`, `harnesses`, `runs`,
   `connections`, `plugins`, `wiki`, `refine`, `capabilities`, `hub`, `terminal`, `approvals`,
-  `harness`, `subagents`, `sessions`, `library`, `recall`, `context`.
+  `harness`, `subagents`, `agents`, `sessions`, `sideQuestions`, `library`, `recall`, `context`,
+  `worktrees`, `annotations`, `commands`, `usage`.
 - Host calls (only with the matching `--host-*` flag): `secrets.get|set|delete`,
   `policy.scope|authorize|approval|connections`, `tools.call`. The host registers tools with
   `tools.register` and names with `directory.set`, and describes its parts with
@@ -37,10 +41,69 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 - `refine.start` takes `{ task, k?, mode?, improver?, executor?, baseVersion?, retainWorkspaces?, id? }`;
   `refine.candidates` returns each execution with `workspace: string | null` (page 05, PROP-0002, PROP-0003).
 - `runs.checklist { runId }` returns the run's latest checklist, `[]` when it wrote none (PROP-0006).
-- `runs.continuation { runId, sessionDir? }` returns a `Continuation`, and `sessions.run` accepts
-  `continueFrom` (page 02, PROP-0007). `harness.status` reports `recovery.interruptedRunIds`.
+- Run records include optional nullable `workspaceRoot`, the canonical root whose files a run may
+  modify by default (page 02). New Harness runs set it; older records may omit it. Hosts must
+  tolerate the additive field and must not nominate or widen the root.
+- `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` (its `checkpoint` is the last
+  work-slice handoff), and `sessions.run` accepts `continueFrom` (page 02, PROP-0007) and `workSlice`
+  (PROP-0041). `harness.status` reports `recovery.interruptedRunIds`.
+- `workSlice { enabled?, maxToolCalls?, maxMinutes?, maxNewTokens?, maxSlices?, continue? }` on
+  `sessions.run` bounds that reply; absent uses 160 calls, 40 minutes, 320 000 new tokens, 8 slices and
+  automatic continuation. A token cap counts new input, cache writes and output, never the cached
+  prefix. `enabled: false` turns the guard off for that run; `XINGULAR_WORK_SLICE=off` in the
+  launching process turns it off for every run in it, and nothing is persisted. The policy is
+  carried into the continuation. A value outside its range is refused with `invalid_request` before
+  the run record is written.
+- The run-event stream adds `checkpoint` (the bounded handoff) and `heartbeat` (steps, elapsed time,
+  last tool, compactions, slice, call budget). Hosts must accept both; an unknown event type is still
+  relayed in order (INV-RUN-3).
 - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
 
+## Usage (PROP-0042)
+
+| Method | Input | Reply |
+|---|---|---|
+| `usage.summary` | `{ scope?: "session" \| "account" \| "project" \| "all", sessionId?, accountId?, projectId?, period?: "today" \| "7d" \| "30d" \| "all", timezoneOffsetMinutes? }` | `UsageSummary`: totals, cache hit rate, latency, day/model/provider/account/session breakdowns, unpriced count, ledger time |
+| `usage.limits` | `{ accountId?, refresh?: boolean }` | `UsageLimitsReport`: per account and provider, the reading source, reason, observed time and limits |
+| `usage.sync` | `{}` | `{ runs, indexed, lastIndexedAt }` |
+
+The methods are contributed by the built-in `usage` plugin module and read only derived or stored
+data; `refresh: true` is the only form that may contact a provider, once per due provider. The
+terminal reaches the same service through protected `terminal.usage.summary|limits`, whose scope
+comes from the terminal session, never from the request.
+
+## Commands and session controls (PROP-0040)
+
+`commands.list { cwd?, accountId?, agentId?, projectId? }` returns `ListedCommand[]`: `name`,
+optional `aliases`, `args`, `description`, `owner`, plus `group`, `source`
+(`core | plugin | extension | prompt | skill`) and optional core `kind` (`session | page | local`).
+Core metadata comes from `commands/registry.ts`; effective plugin contributions supply other routes.
+Namespace/collision rules are shared; discovery neither runs a command nor proves surface acceptance.
+
+For the methods below, `ref` means `{ sessionDir, sessionFile?, cwd? }`.
+
+| Method | Input | Reply |
+|---|---|---|
+| `sessions.tree` | `ref` | `SessionTree`: file, leaf, entries and user-message fork points |
+| `sessions.navigate` | `ref + { entryId }` | `{ leafId, editorText? }`; no summary/model request |
+| `sessions.fork` | `ref + { entryId, targetDir }` | `{ sessionFile, editorText }` |
+| `sessions.clone` | `ref + { targetDir }` | `{ sessionFile }` |
+| `sessions.rename` | `ref + { name }` | `{ name }` |
+| `sessions.lastReply` | `ref` | `{ text: string | null }` |
+| `sessions.export` | `ref + { path }` | `{ path }`; absolute `.jsonl` branch export |
+| `sessions.reload` | `{}` | `{ reloaded: true }`; reloads persistent hooks; structured turns load resources fresh |
+
+`sessions.run` also accepts `command` for compact, navigation with optional summary, or HTML
+export instead of prompt submission (page 02). These retain tracked run lifecycle and pins.
+Saved-history helpers currently validate file scope but do not themselves fence active work;
+host adapters must not infer concurrency safety from method availability.
+
 ## Invariants
 
 - **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. Adding a method
@@ -56,6 +119,10 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   variants, the Wiki, the prompt, connected apps, a recorded session, a plugin hook and the
   refinement demo. The App's sidecar tests parse every reply with its schemas and must pass too.
 
+Built-in feature modules may contribute handlers through `BuiltinPluginRegistry`, but the
+`methods(harness)` result remains the public contract. Plugin module ownership does not rename
+methods or change their params, result shapes or authorization paths (PROP-0020).
+
 ## Source map
 
 `src/server/*.ts`, `src/cli.ts`, `src/core/errors.ts`, `scripts/prove-standalone.mjs`.
@@ -78,7 +145,104 @@ account/model, findings, and available live-check notices. Findings distinguish
 `live` and statuses `pass`, `warning`, `fail`, `disabled`, `blocked`, `unverified`. Schemas and
 Node types are exported. Jobs are in-memory until shutdown; real live-run records remain.
 
+## Side questions (PROP-0019)
+
+| Method | Input | Reply |
+|---|---|---|
+| `sideQuestions.start` | `{ question, cwd, caller, context?: { instructions?, transcript?, references? }, parentRunId?, parentSessionId?, accountId?, model?, effort?, runId?, sessionId? }` | `{ runId, sessionId, nativeSessionId }` |
+| `sideQuestions.read` | `{ runId, sessionId, afterSequence? }` | `{ run: RunRecord, events: RunEvent[] }` |
+| `sideQuestions.interrupt` | `{ runId, sessionId }` | `{ runId }` |
+
+The Harness builds bounded context from the parent's persisted effective prompt and public events
+plus the surface's visible transcript. Read and interrupt require the side run's session id. The
+standalone terminal exposes the same operations through control-key-protected
+`terminal.sideQuestions.*` calls; its caller identity, account and working folder come from terminal
+preparation, not client-supplied values.
+
 Remote `tools.register` may include `diagnostics: [{ id, category, title, tools, probe?: { notice,
 tool, input, contains } }]`. The host answers `tools.diagnose({ id, context })` with `{ status,
 evidence, remedy? }` for local inspection. A probe is a declared registered tool call through
 the gate, with an expected response marker; it cannot supply arbitrary executable code.
+
+## Private terminal resource controls (PROP-0013)
+
+These methods are session-socket controls, not additions to the public host RPC table. All
+require the claimed terminal control key; account, working directory and variant pin come
+from preparation, never from the request.
+
+| Method | Input | Reply |
+|---|---|---|
+| `terminal.browser.config` | `{}` | `{ allowPrivate }`, the device-local private-address setting |
+| `terminal.browser.configure` | `{ allowPrivate: boolean }` | `{ allowPrivate }`, updated setting |
+| `terminal.browser.snapshot` | `{ refresh?: boolean }` | `BrowserSnapshot`: resources, plugins, safe connection records, pinned/latest variant identity and Hub overview |
+| `terminal.browser.read` | `{ id, latest?: boolean }` | `{ content }`, bounded enumerated resource content |
+| `terminal.browser.importSkill` | `{ path }` | `{}`, validated bounded local bundle imported into the existing library |
+| `terminal.browser.hubPreview` | `{ id, version, offset? }` | Existing `HubPreviewPage` |
+| `terminal.browser.hubDocument` | `{ id, version }` | Existing verified installed document |
+| `terminal.browser.connections.appClients` | `{}` | Existing available application OAuth catalog IDs |
+| `terminal.browser.connections.save` | `{ input: ConnectionInput }` | Existing safe `Connection` record |
+| `terminal.browser.connections.test\|signIn\|signOut\|remove` | `{ id }` | Existing connection service result |
+| `terminal.usage.summary\|limits` | `{ scope, period, timezoneOffsetMinutes }` / `{ refresh? }` | Existing usage service result, scoped to this terminal's account and project |
+| `terminal.usage.headers` | `{ provider, status, headers }` | `{}`; only limit-bearing headers, throttled, stored as an account limit reading |
+
+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`).