@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/README.md

@@ -1,11 +1,55 @@
 # Harness documentation
 
+**Binding specification:** [Architecture](architecture/README.md). Code must follow it; a change
+to it starts as a [proposal](architecture/proposals/README.md) the user reviews.
+
+**Feature guide:** [Harness features](features/README.md) organizes current capabilities by area;
+its pages are descriptive, while the architecture specification remains binding.
+
 Current implementation: [Harness terminal frontend](terminal-tui.md). The package-level
 [README](../README.md) describes the embedding API, accounts, plugins, memory and storage.
 
+**Parity:** [Capability parity register](parity.md) lists every capability, its terminal surface
+and its host surface ([14 Surfaces and parity](architecture/14-surfaces-and-parity.md) is binding).
+
+**Future work:** [Feature backlog](future-work.md) records planned concepts. Backlog entries do not
+change the binding architecture or describe implemented capabilities.
+
 | ID | Record | Type | Status | Related |
 |---|---|---|---|---|
-| ADR-0004 | [Fullscreen terminal layout with a fixed dock](decisions/ADR-0004-fullscreen-terminal-layout.md) | Decision | Accepted; working tree implementation | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |
+| ADR-0080 | [Use a fixed 80-column canvas for question sketches](decisions/ADR-0080-fixed-width-question-sketch-canvas.md) | Decision | Accepted; Harness guidance and terminal projection implemented; input and answer contracts unchanged | [ADR-0027](decisions/ADR-0027-connected-sketch-display.md), [11 Terminal](architecture/11-terminal.md), [14 Surfaces and parity](architecture/14-surfaces-and-parity.md), [parity register](parity.md) |
+| ADR-0048 | [A skill named anywhere in a message is required for that request](decisions/ADR-0048-required-skills-from-a-message.md) | Decision | Harness compiler, terminal and App composer implemented; acceptance not certified | [04 Prompt](architecture/04-prompt.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
+| ADR-0047 | [A link a person clicks opens with the system's handler](decisions/ADR-0047-links-open-with-the-os-handler.md) | Decision | Implemented in the Harness, the terminal and the App; acceptance not certified | [10 Server protocol](architecture/10-server-protocol.md), [parity register](parity.md) |
+| ADR-0046 | [Hash-bound plugin proposal review](decisions/ADR-0046-hash-bound-plugin-proposals.md) | Decision | Harness API and model proposal tool implemented; review surfaces pending | [06 Plugins](architecture/06-plugins-and-capabilities.md), [parity register](parity.md) |
+| ADR-0045 | [Release-owned plugin-authoring skill](decisions/ADR-0045-default-plugin-authoring-skill.md) | Decision | Implemented as an on-demand resource | [06 Plugins](architecture/06-plugins-and-capabilities.md) |
+| PROP-0026 | [Connect structural sketch lines in the terminal display](architecture/proposals/PROP-0026-connected-sketch-display.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0027](decisions/ADR-0027-connected-sketch-display.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
+| ADR-0027 | [Project structural ASCII sketch lines into connected terminal borders](decisions/ADR-0027-connected-sketch-display.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md), [14 Surfaces and parity](architecture/14-surfaces-and-parity.md) |
+| FW-0001 | [Agent Modes, starting with Router Agent Mode](future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode) | Future work | Candidate; requires architecture proposal before implementation | [Architecture glossary](architecture/README.md#glossary), [Feature guide](features/README.md#planned-agent-modes) |
+| PROP-0025 | [Strict question columns and contextual ASCII wireframes](architecture/proposals/PROP-0025-contextual-question-wireframes.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
+| ADR-0026 | [Align question columns and preserve contextual ASCII wireframes](decisions/ADR-0026-contextual-question-wireframes.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0025](architecture/proposals/PROP-0025-contextual-question-wireframes.md), [02 Sessions and runs](architecture/02-sessions-and-runs.md), [11 Terminal](architecture/11-terminal.md) |
+| ADR-0025 | [Store bounded ASCII sketches with question requests](decisions/ADR-0025-question-choice-sketches.md) | Decision | Accepted; working tree implementation verified | [PROP-0024](architecture/proposals/PROP-0024-question-sketch-previews.md) |
+| ADR-0024 | [Publish the Harness CLI as xagent](decisions/ADR-0024-xagent-command.md) | Decision | Accepted; implemented in the 4.0.0 candidate | [PROP-0023](architecture/proposals/PROP-0023-xagent-cli-name.md) |
+| ADR-0020 | [Page annotations and delivery are Harness-owned](decisions/ADR-0020-page-annotations.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0017](architecture/proposals/PROP-0017-page-annotations.md), [PROP-0018](architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md), [parity register](parity.md) |
+| ADR-0019 | [Managed Git worktrees are a Harness capability](decisions/ADR-0019-managed-git-worktrees.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0016](architecture/proposals/PROP-0016-managed-worktrees.md), [parity register](parity.md) |
+| ADR-0018 | [Built-in feature modules and namespaced commands](decisions/ADR-0018-builtin-feature-plugins.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0020](architecture/proposals/PROP-0020-builtin-feature-plugins.md) |
+| ADR-0017 | [One capability surface for the terminal and every host](decisions/ADR-0017-one-capability-surface.md) | Decision | Accepted; implementation in 4.0.0 candidate, App parity gaps tracked | [PROP-0015](architecture/proposals/PROP-0015-one-capability-surface.md), [PROP-0016](architecture/proposals/PROP-0016-managed-worktrees.md), [PROP-0017](architecture/proposals/PROP-0017-page-annotations.md), [parity register](parity.md) |
+| ADR-0016 | [Full-screen browser tabs](decisions/ADR-0016-fullscreen-browser-tabs.md) | Decision | Accepted; working tree verified | [PROP-0014](architecture/proposals/PROP-0014-fullscreen-browser-tabs.md) |
+| ADR-0015 | [Unified resource browser](decisions/ADR-0015-resource-browser.md) | Decision | Accepted; working tree verified | [PROP-0013](architecture/proposals/PROP-0013-resource-browser.md), [source study](study/tui-resource-browser.md) |
+| ADR-0014 | [Public release baseline](decisions/ADR-0014-public-release-baseline.md) | Decision | Accepted; 1.0.0 published; 4.0.0 candidate in preparation | [Release procedure](releases/README.md), [PROP-0012](architecture/proposals/PROP-0012-release-baseline.md) |
+| ADR-0013 | [Evidence-based diagnostics with opt-in live probes](decisions/ADR-0013-doctor.md) | Decision | Accepted; working tree implementation | [PROP-0011](architecture/proposals/PROP-0011-doctor.md), [Doctor guide](doctor.md) |
+| SPEC | [Harness architecture specification](architecture/README.md) | Specification | Binding; as of 2026-10-21 | [Proposals](architecture/proposals/README.md), [Known drift](architecture/README.md#known-drift) |
+| STUDY-0002 | [Proactive autonomy: a harness with its own readable agenda](study/proactive-autonomy.md) | Study | Research and three feature hypotheses; not implemented | [Proactive-system sources](study/autonomy-sources.md), [engineering sources](study/autonomous-engineering-sources.md), [known drift D-11](architecture/README.md#known-drift) |
+| STUDY-0001 | [Agent-harness arm study](study/00-index.md) | Study | Arms 01–10 audited (core sources); matrix + roadmap done; remaining-source fills pending | [insights.md](study/insights.md), [roadmap.md](study/roadmap.md), [`/btw` comparison](study/btw-comparison.md) |
+| DESIGN-0001 | [System-prompt design: fixed foundation + adapting harness](system-prompt-design.md) | Design | Draft — not yet accepted; refs current `compile.ts`/tree contracts | STUDY-0001 (arms 01, 10), [roadmap.md](study/roadmap.md) T1-1/9 |
+| EXP-0001 | [Terminal input latency profile](experiments/EXP-0001-terminal-input-latency/plan.md) | Experiment | Completed on one local machine; slow-machine validation pending | ADR-0001, [Profile instructions](terminal-tui.md#input-performance-profile) |
+| ADR-0012 | [Agents name their own native Pi sessions](decisions/ADR-0012-native-session-names.md) | Decision | Accepted; working tree implementation verified | [PROP-0010](architecture/proposals/PROP-0010-session-names.md) |
+| ADR-0011 | [The harness is a fixed foundation running a mutating variant](decisions/ADR-0011-foundation-and-variants.md) | Decision | Accepted; implemented in 5.0.0 | [PROP-0009](architecture/proposals/PROP-0009-foundation-and-variants.md), [Foundation and variants](architecture/00-overview.md#foundation-and-variants) |
+| ADR-0010 | [Lessons from ordinary runs live in the Wiki](decisions/ADR-0010-lessons-in-the-wiki.md) | Decision | Accepted; working tree implementation | [PROP-0008](architecture/proposals/PROP-0008-lessons-from-runs.md), [08 Memory and history](architecture/08-memory-and-history.md), [feature-gap review](study/feature-gap-review.md) |
+| ADR-0009 | [Publish the Harness CLI as xharness](decisions/ADR-0009-xharness-command.md) | Decision | Superseded by ADR-0024 | [PROP-0005](architecture/proposals/PROP-0005-xharness-cli-name.md), [11 Terminal](architecture/11-terminal.md) |
+| ADR-0007 | [A fixed Reporting section shapes the final reply](decisions/ADR-0007-reporting-section.md) | Decision | Accepted; working tree implementation | [PROP-0001](architecture/proposals/PROP-0001-reporting-section.md), [04 Prompt](architecture/04-prompt.md) |
+| EXP-0002 | [OpenTUI typing latency against Pi and opencode](experiments/EXP-0002-opentui-typing-latency/plan.md) | Experiment | Completed on one local machine (Apple M2) | ADR-0006, EXP-0001, [Profile instructions](terminal-tui.md#input-performance-profile) |
+| ADR-0006 | [OpenTUI is the only terminal frontend](decisions/ADR-0006-opentui-only-terminal.md) | Decision | Accepted; working tree implementation | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |
+| ADR-0004 | [Fullscreen terminal layout with a fixed dock](decisions/ADR-0004-fullscreen-terminal-layout.md) | Decision | Superseded by ADR-0006 | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |
 | ADR-0003 | [Shared asynchronous subagents with native-history delivery receipts](decisions/ADR-0003-shared-asynchronous-subagents.md) | Decision | Accepted; working tree implementation | ADR-0002, [Embedding API](../README.md) |
 | ADR-0002 | [Native subagent lifecycle in Harness sessions](decisions/ADR-0002-native-subagent-lifecycle.md) | Decision | Superseded by ADR-0003 | [Embedding API](../README.md) |
 | ADR-0001 | [Own the terminal frontend and keep Pi as the session runtime](decisions/ADR-0001-owned-terminal.md) | Decision | Accepted; working tree implementation | [Terminal architecture and evidence](terminal-tui.md) |

package/docs/architecture/00-overview.md

@@ -0,0 +1,171 @@
+# 00 Overview
+
+## Purpose
+
+`@xingular/harness` runs one agent run well, on Pi, for any application that embeds it. It owns
+what a model is told (the variant and the compiled prompt), what it can do (tools, the gate,
+connected apps), what it remembers (Wiki notes, run history), how a run is recorded, and how a variant
+of the harness is improved from evidence (refinement). It knows a *caller*, a *session* and a
+*run*. It does not know what an application is or what its objects mean.
+
+## Layers
+
+```text
+Host (for example the App repo)             presentation, windows, PTY, keychain, native OS bridges, host-only surfaces
+   │  seven extension points (01) and the server protocol (10)
+Harness (this package)                      every capability: variants, prompt, sessions, runs, gate, Wiki, history,
+                                            plugins, MCP, refinement, world tools, worktrees, annotations,
+                                            and the reference terminal frontend
+   │  Pi SDK: createAgentSession, ModelRuntime, SessionManager, DefaultResourceLoader
+Pi                                          model calls, native JSONL history, tool execution, extensions
+```
+
+- **Pi** supplies the model runtime, native history, tool execution and the extension API.
+- **The harness** decides everything Pi is given: the account folder, the prompt, the tools, the
+  extensions, skills and prompts it may load, and the gate in front of each tool call. It records
+  every run. It owns every capability a person uses, and its standalone terminal surfaces each one
+  (page 14, `INV-PAR-1`).
+- **A host** presents the same capabilities with its own UI, supplies what only it knows through
+  the extension points, and reads what the harness records. The terminal and a host offer the same
+  capabilities; a host may add registered host-only surfaces (`INV-PAR-4`).
+
+**Belongs in the harness:** Pi sessions and accounts, variants and refinement
+(Propose–Probe–Compose, selection, the experience library), the prompt compiler and its delivery,
+project notes (the Wiki), recall, the tool gate and standing approvals, connectors (MCP), terminal
+sessions and their owned standalone frontend, generic web/isolated-browser tools, managed git
+worktrees (PROP-0016), page annotations (PROP-0017), and the server protocol.
+
+**Stays in the host:** windows, the PTY, the keychain, native operating-system bridges (a WebKit
+tab, computer control) behind Harness contracts (`INV-PAR-3`), presentation, and registered
+host-only surfaces (`INV-PAR-4`). Orchestration across agents (organizations, routed chats, group
+chats, delegated work queues) is not a Harness capability; a host that wants it must first bring it
+here through a proposal, with a terminal surface.
+
+This package is consumed as source by the App's sidecar and is meant to be embedded by other
+applications, so a change here changes every application built on it.
+
+The application side of the boundary is described in
+[`App/docs/architecture/overview.md`](../../../App/docs/architecture/overview.md).
+
+## Foundation and variants
+
+The harness has two halves, and every page uses these two words for them.
+
+- The **foundation** is the part that is fixed. Code and release change it; nothing running
+  through it can. It is the Pi hookup, the prompt compiler and its budgets, sessions, runs and the
+  run recorder, the tool gate and standing approvals, accounts and their isolation, plugin-code
+  trust, the variant surface with its validator and always-on cap, the refinement method (its
+  budget identity and answer-free rule), the seven extension points and the server protocol.
+- A **variant** is the part that mutates: one tree of eight components (c1–c8) for one scope,
+  stored as immutable, validated versions (page 03). A scope's *head* is the variant it runs now;
+  a *version* is a recorded variant; a *candidate* is a variant refinement proposed.
+
+"The harness" means the foundation together with the variant it is running.
+
+```text
+  foundation  ──runs──►  variant (pinned head)  ──►  run record, events, trajectories
+      ▲                                                        │
+      │ person adopts                                          ▼
+      └──────────  candidate variants  ◄── refinement (improvers edit a copy)
+```
+
+1. The foundation runs a session on a pinned variant and records everything the run did.
+2. Refinement reads those records, lets improver sessions edit a *copy* of the variant, probes
+   each candidate and picks one final output without seeing a score (page 05).
+3. A person adopts a candidate. Only then does it become the head, and only with its plugin code
+   trusted. The next run pins the new head.
+
+The rule between the halves is one-way. A variant decides what the agent is told and which
+skills, scripts, subagents and plugins it may load. It cannot alter the compiler, the gate, the
+recorder, accounts or trust: variant plugins run inside the tool loop, but the gate is always the
+last extension loaded (`INV-GATE-2`). Refinement never edits the foundation (`INV-FND-1`) and has
+one door into a variant (`INV-FND-2`).
+
+When a rule is unclear, ask which half the thing belongs to. If an agent or an improver could
+legitimately change it, it is a variant concern. If changing it would need a release, it is the
+foundation. Page 04 and DESIGN-0001 draw the same line inside the prompt: foundation text is
+contract prose about mechanics, variant text is work guidance.
+
+The improver prompts in `refine/prompts.ts` and the evidence folder's `harness/` names keep the
+Harness² paper's own vocabulary, where "the harness" is what the improver edits. They are method
+text, and changing them would change the method (`INV-REF-3`).
+
+## Components
+
+`Harness` (`src/harness.ts`) is the composition root. `createHarness(options)` builds one and
+opens the data root.
+
+| Member | Type | Module | Page |
+|---|---|---|---|
+| `env` | `HarnessEnv` (`root`, `directory`, `productName`) | `core/env.ts` | 01 |
+| `accounts` | `Accounts` | `accounts/` | 09 |
+| `sessions` | `Sessions` | `sessions/sessions.ts` | 02 |
+| `runs` | `RunRegistry` | `sessions/registry.ts` | 02 |
+| `subagents` | `Subagents` | `sessions/subagentService.ts` | 02 |
+| `approvals` | `Approvals` | `sessions/approvals.ts` | 07 |
+| `trust` | `VariantTrust` | `variant/trust.ts` | 03 |
+| `refine` | `Refinements` | `refine/service.ts` | 05 |
+| `plugins` | `Plugins` | `plugins/plugins.ts` | 06 |
+| `hooks` | `Hooks` | `plugins/hooks.ts` | 06 |
+| `apps` | `ConnectedApps` | `mcp/service.ts` | 09 |
+| `hub` | `Hub` | `hub/hub.ts` | 09 |
+| `terminals` | `Terminals` | `terminal/terminals.ts` | 11 |
+| `worktrees` | `Worktrees` | `worktrees/service.ts` | 02, 14 |
+| `bus` | `Bus` (state-changed notices) | `core/bus.ts` | 10 |
+
+Modules with no member of their own: `variant/` (functions over the variant store), `prompt/compile.ts`,
+`wiki/notes.ts`, `history/`, `tools/`, `capabilities/`, `server/`.
+
+### Lifecycle
+
+1. **Construct.** `isolateProcess` removes inherited credentials and points Pi's fallback folder
+   away from `~/.pi` before anything else. Stores and services are created.
+2. **Open a data root** (`open(dataRoot)`). Lays out folders, moves an earlier Wiki aside once,
+   migrates connection scopes, marks runs that never settled as interrupted (unless another live
+   process owns them), and syncs the recall index. Returns a `Recovery`, which lists the
+   interrupted runs; the application may continue one as a new run (`continueFrom`, page 02).
+3. **Serve.** Sessions, refinements, terminals and RPC calls run. Every run event is persisted,
+   then relayed to listeners; finished runs are indexed for recall and announced to hooks.
+4. **Close** (`close()`). Stops the hub, refinements, terminals and live runs, settles hooks,
+   closes connected apps and the index.
+
+## ETCLOVG: the harness's share
+
+| Letter | The harness owns |
+|---|---|
+| **E** Execution | Isolated account folders, the Pi session, the terminal launch spec |
+| **T** Tools | History, trajectory, Wiki notes, skill loading, `ask_user`, the run todo list, the connected-apps broker, the tool gate |
+| **C** Context | The compiler, stable prefix and updates, the versioned variant (c1–c8), skills, on-demand Wiki notes |
+| **L** Lifecycle | Run state, interrupt, recovery, approvals and questions, subagents, refinement |
+| **O** Observability | Validated run events saved per run; usage counters |
+| **V** Verification | Isolated refinement probes and answer-free selection |
+| **G** Governance | The per-call gate, standing approvals, account pinning, redaction |
+
+The host's column (PTY, windows, native bridges, presentation) is in the parent `AGENTS.md` and
+the App's architecture pages. Page 14 states how the terminal and a host share capabilities.
+
+## Invariants
+
+- **INV-BND-1** The harness imports nothing from an application. Application data reaches it only
+  through the extension points (page 01) or the server protocol (page 10).
+- **INV-BND-2** The harness names no application or application concept (agent role, group, task,
+  pane, handoff, App browser workspace, computer use) in code paths it reads or text a model or
+  person sees, except for its canonical product name `Xingular Agent`. Text names the product through
+  `env.productName` (default `Xingular Agent`; `{product}` in a tool description); an embedding host
+  may supply another product name. Ids such as `agentId`, `projectId` and a variant `scope` are opaque;
+  names come from `Directory` or `CallerContext.agentName`. A managed git worktree is a Harness
+  object since PROP-0016.
+- **INV-BND-3** A new need of one application is met by a generic extension point or option,
+  never by a branch on an application's name or concept.
+- **INV-BND-4** Variants, the prompt compiler and Wiki notes are synchronous (`variant/`, `prompt/`,
+  `wiki/`). A synchronous function is the critical section; do not make them async. Accounts, Pi,
+  MCP and refinement are async.
+- **INV-BND-5** The process never launches against `~/.pi`, `~/.codex` or `~/.claude`, and never
+  inherits a credential variable (`isolateProcess`, page 09).
+- **INV-BND-6** Tests never make a model request; they use a fake `SessionFactory`.
+
+## Source map
+
+`src/harness.ts`, `src/index.ts` (public exports), `src/core/` (env, caller, bus, errors, fs,
+text, index), `src/cli.ts` (command line). Boundary decisions: [PROP-0015](proposals/PROP-0015-one-capability-surface.md),
+[ADR-0017](../decisions/ADR-0017-one-capability-surface.md).

package/docs/architecture/01-extension-points.md

@@ -0,0 +1,78 @@
+# 01 Extension points
+
+## Purpose
+
+An application adds what it knows to the harness through exactly seven surfaces. They are the
+whole interface in the application-to-harness direction; anything else an application needs is
+added as a new generic surface, by proposal.
+
+## Components
+
+Each surface is an option of `createHarness` (`HarnessOptions`) or a per-run input, and has a
+server-protocol equivalent for a host that is not a Node program (page 10).
+
+| # | Surface | Declared in | How it is supplied | Over the protocol |
+|---|---|---|---|---|
+| 1 | Prompt sections | `Launch` in `prompt/compile.ts` (`sections: HostSection[]`, `toolGroups: HostToolGroup[]`, `references: Reference[]`) | `SessionRunInput.launch` per run | `sessions.run` params |
+| 2 | Tool providers | `ToolProvider`, `ToolSpec`, `ToolSession` in `tools/types.ts` | `harness.sessions.provide(provider)` | `tools.register` + host call `tools.call` (`--host-tools`) |
+| 3 | `ToolPolicy` | `sessions/policy.ts` (`scope`, `authorize`, `approval`, `connections`) | `HarnessOptions.policy` | host calls `policy.*` (`--host-policy`) |
+| 4 | `SecretStore` | `accounts/secrets.ts` (`get`, `set`, `delete`) | `HarnessOptions.secrets` (default: owner-only file in the state dir) | host calls `secrets.*` (`--host-secrets`) |
+| 5 | `Directory` | `core/env.ts` (`agentName`, `sessionAgent`) | `HarnessOptions.directory` | `directory.set` (`--host-directory`) |
+| 6 | Plugin descriptions | `PluginDescriptor` in `plugins/types.ts` | `HarnessOptions.plugins`, `harness.describe()` | `plugins.describe` |
+| 7 | `RefineHost` | `refine/host.ts` (`prepareWorkspace`, `session`, `deliverable?`) | `HarnessOptions.refineHost` (default: temp copy of the source, Pi file and shell tools) | — (Node only today) |
+
+The caller is not an extension point but the frame every call carries: `CallerContext`
+(`core/caller.ts`) holds opaque `agentId`, `projectId`, `sessionId`, `runId`, `agentName`,
+`actor` (`Chat` or `Code`), `surface`, `recallExcludeAgents` and an opaque `policyContext` that the
+harness forwards to the policy and never reads.
+
+## Contracts
+
+1. **Prompt sections.** A `HostSection` has `id`, `title`, `body` (`null` declares a withdrawn
+   slot), `budget`, `order`, optional `dynamic` and `pinned`. The harness places it among its own
+   sections by `order` (page 04).
+2. **Tool providers.** Providers are asked in the order they were added, for each session. Only
+   names in the run's frozen capability set are registered. A `ToolResult` may carry
+   `attachments` as `{ id, name, mimeType }` references; bytes stay with the provider.
+3. **`ToolPolicy`.** `scope(call)` → `ScopeDecision { allowed, requiresApproval?, automatic?,
+   humanOnly?, allowGlobalApproval?, reason? }`; `authorize(call)` throws to block and is asked
+   again after an approval; `approval(...)` returns `ApprovalFacts { unattended?, readOnly?,
+   inScope? }`; `connections(...)` narrows the connected apps. With no policy, every enabled tool
+   may run and gated tools ask the person.
+4. **`SecretStore`.** Keys are `<account id>/<name>` (`secretKey`).
+5. **`Directory`.** Every lookup may answer `null`.
+6. **Plugin descriptions** are data. They change what `plugins.list` and `plugins.inventory`
+   report, never what runs. A descriptor with a harness plugin's id is ignored.
+7. **`RefineHost`.** `prepareWorkspace` returns an isolated folder (never one a person works in)
+   and an optional `cleanup`; `session` returns a `RolloutSession` (caller, tools, launch, model,
+   account); `deliverable` maps file names to readable text.
+
+## Invariants
+
+- **INV-EXT-1** There are seven extension points. Adding, removing or changing the shape of one is
+  an architecture change; update this page and affected contracts in the same change.
+- **INV-EXT-2** Every extension point is optional. The harness runs with none of them supplied.
+- **INV-EXT-3** An extension point carries data or decisions the application owns. It never
+  carries an application's name or a branch for one application (`INV-BND-3`).
+- **INV-EXT-4** Each Node extension point has a protocol equivalent, or the page says it is
+  Node-only (today only `RefineHost`).
+- **INV-EXT-5** `CallerContext` fields are trusted host context, never model arguments. A tool may
+  not let the model set them.
+
+## Data
+
+None of its own. Secrets go to the `SecretStore`; everything else is passed per call.
+
+## Source map
+
+`src/core/caller.ts`, `src/core/env.ts`, `src/prompt/compile.ts` (`Launch`), `src/tools/types.ts`,
+`src/sessions/policy.ts`, `src/accounts/secrets.ts`, `src/plugins/types.ts`
+(`PluginDescriptor`), `src/refine/host.ts`, `src/server/remote.ts` (protocol equivalents).
+
+## Provider diagnostics
+
+Tool providers optionally carry `diagnostics(context)` metadata (PROP-0011). Checks expose local
+readiness callbacks and declared live probes. Existing callable provider functions remain valid.
+This extends surface 2; the number of extension points remains seven. `WorldPart` forwards the
+same callback. Remote `tools.register` accepts diagnostic descriptors; `tools.diagnose` returns
+local readiness data. Optional remote single-tool probe recipes go through the normal gate.