@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,245 @@
+# 07 Tools and the gate
+
+## Purpose
+
+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. 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
+
+| Type / function | Module | Role |
+|---|---|---|
+| `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 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. |
+| `todoTool` (`todo_write`) | `tools/todo.ts` | Writes the run's whole todo list as a `todo.updated` event (PROP-0006, renamed by PROP-0045). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `todo` telemetry call. The prompt's Progress group asks the model to call it before the first other tool call when work has several steps, keep it current, and write one final update before replying; unfinished work is not automatically marked complete. The pre-rename `checklist.updated` event is still read, never written. |
+| `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. The description states the run's budget, and `Subagents.spawn` refuses a child past its per-profile or total limit (ADR-0052). |
+| `annotationsPart` (`page_notes_list`, `page_notes_read`) | `annotations/part.ts` | Read-only world tools over the page notes a person shared with the session or agent (PROP-0017, PROP-0048). |
+| `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: `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),
+`todo_write`, `plugin_propose`. 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.
+
+## Plugin proposal security
+
+`plugin_propose { name, description, files }` is a write-classified Harness tool, subject to the
+normal capability and per-call gate, and creates only a pending proposal in the Harness data root.
+It does not accept, install, enable or trust a plugin. Proposal text is untrusted, including skill
+instructions; preview and human review are needed before acceptance. Acceptance is a separate
+trusted-caller API, bound to the reviewed content hash; it does not execute package code, grant
+trust or bypass the loader, attachment controls, capability restrictions or gate. Text contributions
+can load once enabled without code trust, so review their instructions as well as executable files.
+See page 06 and [ADR-0046](../decisions/ADR-0046-hash-bound-plugin-proposals.md).
+
+## 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).
+
+**Windows** has no write-boundary sandbox the harness can use, so the Bash tool treats every
+command there as an outside request: a human-only one-call approval (or an eligible Full
+Permission answer), then the command runs once without a sandbox. Plan-mode Bash is refused,
+because a read-only scope cannot be enforced. Commands run in Git Bash when it is installed
+(`%ProgramFiles%\Git\bin\bash.exe`, then `bash.exe` on `PATH`, never the WSL launcher in
+`System32`), otherwise in PowerShell (`pwsh.exe`, then Windows PowerShell). The tool keeps the name
+`bash`; its description names the shell. Native `edit` and `write` run their atomic helper with
+Node directly, without an OS guard: the target is still canonicalized, authorized, revalidated and
+replaced by rename, and outside targets still need their approval, but a junction or symlink swap
+between the check and the rename is not prevented
+([ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md)).
+
+## 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/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
+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
+Bash on Windows (no sandbox)            ─► as outside scope; plan-mode Bash refused
+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
+```
+
+An approval is a control a person clicks, never a permission asked for or granted in a message. The
+gate pauses that exact call and the run reports `waiting_for_approval`; allowing it resumes the same
+call in the same turn, and denying it resolves back to the running turn as a tool result. The
+compiled prompt says so, so a model calls the tool instead of ending its turn to ask. Every surface
+that can ask presents a control: a decision dock, a keypress, or a paired phone's choices. A surface
+that cannot ask a person refuses the call instead of waiting.
+
+Structured sessions and the terminal record gate and work-slice refusals as `tool.refused`, with the call id, name, bounded reason and a code (`plan_mode`, `workspace`, `scope`, `policy`, `capability`, `approval_denied`, `unattended`, `work_slice` or `controller_unavailable`). The terminal relay is best effort if its controller is unreachable. The existing tool-result text is unchanged. Refusals inside a tool after it starts are not gate refusals.
+
+Standing approvals (`approvals.json`): an always-approve switch per key (`chat`, or the run's
+`harness`), tools allowed across the state directory per key, and targets remembered per
+session. `humanOnly` calls are never answered by remembered tools, and by the switch only when
+`allowGlobalApproval`. `ApprovalFacts.unattended` disables standing answers; `readOnly` disables
+the switch and global tools. A person answering through a phone paired by `/remote-control` answers
+the same terminal request through the same controller call, with its complete action text shown
+beside the choices (INV-RC-3, INV-RC-4).
+
+## Invariants
+
+- **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** The model has no tool that ends or hands off its own work (ADR-0071, ADR-0072):
+  neither `checkpoint_write` (PROP-0041, removed by ADR-0069) nor `finish` (ADR-0069, removed by
+  ADR-0071) exists. The one exception is `update_goal` in a goal the person started: it is offered
+  only while a goal exists, its `complete` is only a claim that the harness checks (INV-RUN-16), and
+  its `paused` needs the person's word. The model cannot create, resume or limit a goal. When a
+  reply stops, it settles as it ends unless a person interrupted it, the slice guard ended it, or a
+  goal stopped it (INV-RUN-15); a slice or goal stop writes the checkpoint from the run's evidence.
+- **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, 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.
+  On Windows, which has no sandbox, every Bash call takes the `outside` path and plan-mode Bash is
+  refused (ADR-0042).
+- **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** 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.
+  On Windows the atomic replacement runs without an OS-enforced scope (ADR-0042).
+- **INV-GATE-9** An approval is a control, never a message. The gate pauses the exact call and the
+  run reports `waiting_for_approval`; Allow resumes that same call in the same turn, and Deny returns a
+  tool result on the still-running turn. The compiled prompt tells the model to call the tool rather
+  than ask for permission in a message or end its turn to wait, and no surface accepts a typed
+  approval instead of a control.
+
+## Data
+
+`<state dir>/approvals.json`.
+
+## Source map
+
+`src/tools/*.ts`, `src/web/*.ts`, `src/sessions/sessions.ts`, `src/sessions/runner.ts`,
+`src/sessions/workspaceBoundary.ts`, `src/sessions/initialBash.ts`, `src/core/workspaceBashTool.ts`,
+`src/core/shell.ts`, `src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`,
+`src/sessions/approvals.ts`, `src/sessions/policy.ts`. Decisions:
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md),
+[ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md).
+
+## Session naming (PROP-0010)
+
+`session_name` (`tools/sessionName.ts`) binds to the current native session. It maintains
+only Pi session metadata and is explicitly plan-safe, while still subject to capability
+selection and the host policy. The prompt asks for it once before the first other tool call when
+a request needs tools or changes state. When a top-level attended session starts unnamed, the
+harness also derives a provisional name from its first substantive request and sets it through
+Pi before the first model request; a host gate refusal or a failed write leaves the session
+unnamed and never fails the run. The model may revise the provisional name. The terminal
+registers the same definition through its Pi bridge; standalone policy permits naming without
+approval. See page 02 for validation and persistence. It is a foundation tool, not mutable
+variant data.
+
+## Diagnostic probes
+
+`/doctor` is a user command, never a model tool. Live diagnostics create separate real runs,
+intersect current capabilities, and execute tool calls through the existing gate. Calls that
+require an additional per-call approval report blocked; batch diagnostic consent does not grant
+standing permission. No raw tool inputs, results, or screenshots enter diagnostic findings.
+
+A live check may also run one command the harness wrote itself, when the capability it diagnoses is
+a native Pi tool rather than a harness tool: the shell check runs `printf` through the same
+workspace root, hard-link scan and write-boundary sandbox as a Bash call, and reports only the exit
+status. It passes the gate first, and a diagnostic never widens the boundary — Full Permission,
+an outside-workspace request and a host bypass are all refused for it — so a boundary that stops
+the command before the shell starts is reported as blocked with the boundary's own reason.

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

@@ -0,0 +1,100 @@
+# 08 Memory and history
+
+## Purpose
+
+Two kinds of memory sit outside the variant. The **Wiki** holds project notes: linked
+Markdown that people and agents read and write as reference material, never as instructions.
+**History** is the record of earlier runs: recall over what was said, and bounded reads of the
+recorded trajectory. Both are served through harness tools (page 07) and kept searchable in a
+rebuildable SQLite index.
+
+## Components
+
+| Type / function | Module | Role |
+|---|---|---|
+| `paths`, `list`, `read`, `write`, `remove`, `versions`, `version`, `search`, `graph`, `ensureLayout`, `moveLegacy` | `wiki/notes.ts` | The Wiki. Logical module (functions), not a class. |
+| `noteChange` | `core/changes.ts` | Announces a completed write to listeners (hooks). |
+| `indexRun`, `sync`, `search`, `read` | `history/recall.ts` | Recall passages from runs, scoped to the caller. |
+| trajectory search and read | `history/trajectory.ts` | Paged, redacted reads of canonical run events. |
+| `Lessons`, `keptLessons`, `lessonMission` | `history/lessons.ts`, `history/lessonPrompt.ts` | Reflection on finished runs when the `lessons` plugin is on; keeps general lessons as Wiki notes (PROP-0008). |
+| `withIndex`, `migrate`, `MIGRATIONS` | `core/index.ts` | The shared `index.sqlite` connection and its migrations. |
+
+## Contracts
+
+- **Note paths.** A note's path is its file path under `wiki/` without `.md`. Links are
+  `[[path]]`, `[[path|label]]` or a relative Markdown link. Notes live in `home.md`, `library/`
+  (no project) and `projects/<slug>/` (a project the application named in `projects.json`).
+- **Writes.** `write(root, path, body, { expectedUpdatedAt?, actor?, reason? })` refuses text over
+  400,000 characters, text that looks like a credential (`secret_refused`), an unknown project
+  slug, and a stale `expectedUpdatedAt` (`conflict`). The previous text is kept in `wiki-history/`.
+- **Recall scope.** A `Code` caller (a session in a project) reads only session runs of its project,
+  or its own session. A `Chat` caller reads its agent's conversations. `recallExcludeAgents` hides
+  named agents' conversations. A caller never reads a run outside its scope.
+- **Trajectory search** returns run summaries including `terminalReason` and `terminalCode`, each
+  null when unavailable (including older records without a code). Trajectory reads include the same
+  summary.
+- **Trajectory reads** return pages of canonical execution events, including active runs,
+  bounded and marked when truncated. `run: 'current'` resolves to the caller's active run on
+  structured and terminal model-tool paths; without an active run it fails rather than using a
+  previous run. They omit account identifiers, credential fields, attachment bytes, native adapter
+  payloads and provider reasoning text. They report evidence, never a score.
+- **Lessons** (PROP-0008, [ADR-0010](../decisions/ADR-0010-lessons-in-the-wiki.md)). When the
+  first-party `lessons` plugin is on for a run's caller (its contribution is in the run's
+  `capabilities.json`), a **completed, top-level** run that made at least `minToolCalls` tool calls
+  is queued after it ends. Subagent runs and runs with trigger `probe`, `improver` or `reflection`
+  are never queued. One reflection runs at a time, in the background, and the queue is not kept
+  across a restart.
+  - The reflection is a session with trigger `reflection` on the run's own account and model, file
+    tools `read`, `grep`, `find`, `ls` only, no providers, connections, harness tools or subagents,
+    `automatic: true`; anything needing a person is refused at the gate. Its evidence is a temporary
+    `context/` with `run.md` (the request and the rendered trajectory, observations kept to at least
+    10,000 characters) and `lessons.md` (the kept lessons' paths and cues), checked with the grader
+    tripwire.
+  - It replies `NO_ENTRY`, `SAME <path>`, or one `<experience>` block (`cue`, `lesson`, `evidence`,
+    `confidence`): refinement's lesson shape, which never carries the run's own facts.
+  - A new lesson is written with `notes.write` to `library/lessons/<slug of cue>` with actor
+    `reflection`, frontmatter `title`, `cue`, `confidence`, `sources: [runId]`. `SAME` adds the run
+    id to that note's `sources`. Nothing is written when the lesson is longer than `maxChars`,
+    looks like a credential, carries a grader marker, or the Wiki already keeps `maxLessons`
+    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/`. 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
+
+- **INV-MEM-1** The Wiki is reference material, not instructions. Only the variant shapes an agent
+  (`INV-VAR-1`); the Wiki reaches a prompt only as the dynamic `wiki` pointer and selected
+  `references` (`INV-PRM-3`).
+- **INV-MEM-2** The harness is the only writer of the Wiki and of run records. An application
+  reads them and writes notes only through harness methods (`wiki.*`). Inside the harness, the
+  Wiki is written by `wiki_write`, by `wiki.*` methods, and by `Lessons` (actor `reflection`, only
+  under `library/lessons/`, only while the `lessons` plugin is on for the run's caller).
+- **INV-MEM-3** Every write point calls `noteChange` after the file is in place, and never waits
+  for listeners (`INV-PLG-7`). (Removal does not yet: drift D-7.)
+- **INV-MEM-4** A note write keeps the previous text as a version. Nothing deletes history except
+  an explicit person's action.
+- **INV-MEM-5** Files are the source of truth. `index.sqlite` is derived and can be deleted and
+  rebuilt (`harness.rebuildIndex()`).
+- **INV-MEM-6** Index migrations are append-only once released. Each runs in one transaction
+  after the file is backed up; a failure restores the previous index.
+- **INV-MEM-7** Recall and trajectory reads respect the caller's scope and redact secrets. They
+  never return another scope's runs.
+- **INV-MEM-8** Wiki code is synchronous (`INV-BND-4`).
+
+## Data
+
+```text
+<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), usage rows
+<data root>/projects.json    read only: the application owns it
+```
+
+## Source map
+
+`src/wiki/notes.ts`, `src/history/recall.ts`, `src/history/trajectory.ts`, `src/history/lessons.ts`, `src/core/index.ts`,
+`src/core/changes.ts`, `src/core/projects.ts`, `src/core/secrets.ts`.

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

@@ -0,0 +1,153 @@
+# 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 the account state folder (`HarnessOptions.accountsDir`, by default
+  `<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. The registry,
+  the account folders and their shared settings are one identity: a launch that points
+  `accountsDir` at another state's folder (`--account-state`) also uses that state's `SecretStore`,
+  so both launches sign in as the same accounts.
+- **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. The `/hub` Catalog
+  view filters Community entries for display; the service and other callers retain the full catalog.
+  Installed shows receipts from every channel. On page entry, cached/bundled content is shown before
+  a remote refresh, and origin, refresh time and failure status remain visible (PROP-0047).
+
+## 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-ACC-5** A credential has one copy. A terminal's Pi keeps no `auth.json`: it reads its own
+  account's credentials with `accounts.credentials.read`/`list`, and a refresh or sign-in holds the
+  store's cross-process lock from `accounts.credentials.lease` to `accounts.credentials.commit`
+  (`terminal/credentialStore.ts`, at most 20 seconds, then the lease lapses unchanged). Like every
+  `accounts.*` call they need the control key, so the model's shell never sees a token. Two copies of
+  a rotating refresh token, each under its own lock, let the second refresh send a spent token and
+  fail with `invalid_grant`. An `auth.json` a terminal of an older version left is folded in under the
+  lock, a newer stored token never replaced, and removed once no other process has a terminal on the
+  account.
+- **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. Every removal route for a Hub-owned Pi
+  package, including `plugins.remove`, goes through Hub's receipt-owning uninstall operation. A
+  floating plugin-package update must not change a Hub-owned package; replacement uses an explicit
+  exact catalog version (PROP-0047).
+
+## Data
+
+```text
+<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log, per-account state (health, plan, limits)
+<state dir>/accounts/<id>/choices.json  the model and effort each mode last used on that account
+<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
+```
+
+`choices.json` is the account's own model memory: it holds no credentials and is removed with the
+account. A conversation that reaches a new account cannot use is started on this account's newest
+selection — the mode's, then normal's, then the newest in any mode — with that selection's effort,
+skipping a model the account cannot authenticate; the terminal records the start in the
+conversation, never in `choices.json`. See [ADR-0064](../decisions/ADR-0064-account-model-fallback-on-resume.md).
+
+## 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.
+
+## 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.