@xingular/harness 0.1.7 → 1.1.1

package/docs/README.md

@@ -1,10 +1,52 @@
 # 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 |
 |---|---|---|---|---|
+| 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) |
 
 Living reference pages describe checked source behavior. Accepted decisions record the choice;

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 checklist, 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 (proposal required).
+- **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.

package/docs/architecture/02-sessions-and-runs.md

@@ -0,0 +1,203 @@
+# 02 Sessions and runs
+
+## Purpose
+
+A *session* is a native Pi conversation. A *run* is one tracked execution interval of a session:
+one turn from a request to an outcome. The harness opens Pi for each run with a pinned account,
+a pinned variant, a frozen capability set, a compiled prompt and a gated tool list, then
+records everything the run does as validated events.
+
+## Components
+
+| Type | Module | Role |
+|---|---|---|
+| `Sessions` | `sessions/sessions.ts` | Starts a turn: `run(input: SessionRunInput)`, `provide(provider)`. Builds the gate. |
+| `runTurn`, `piSessionFactory`, `loadResources` | `sessions/runner.ts` | Opens the Pi session, loads resources in a fixed order, streams events, settles the run. |
+| `RunRegistry`, `ActiveRun` | `sessions/registry.ts` | Live runs: `emit`, `requestApproval`, `requestAnswer(s)`, `onInterrupt`, `onSteer`, `finish`; `listen` for observers. |
+| run store functions | `sessions/runStore.ts` | `saveRun`, `updateRun`, `persistEvent`, `appendEvent`, `readEvents`, `markInterruptedRuns`, `runFamily`, `listRuns`. |
+| `RunRecord`, `RunEvent`, schemas | `sessions/contracts.ts` | The one contract every session shares. |
+| `Subagents` | `sessions/subagentService.ts` | `spawn`, `wait`, `results`, delivery receipts, recovery. |
+| `SideQuestions` | `sessions/sideQuestions.ts` | Starts, reads and interrupts independent tool-free runs using bounded context from the main conversation (PROP-0019). |
+| plan mode | `sessions/planMode.ts` | `planSection`, `planRefusal`, `PLAN_READ_ONLY_TOOLS`. |
+| `Approvals` | `sessions/approvals.ts` | Standing approvals (page 07). |
+| history selection | `sessions/history.ts` | `selectHistory`: which native history file a run continues. |
+| `runIndex`, `pricing`, `reasoningSummaries`, `lineageJoin`, `extensionUi` | `sessions/` | Run listing, cost, provider summaries, parent/child joins, extension UI as run events. |
+
+## Runtime flow of `sessions.run`
+
+1. Validate the input (`run.id`, `sessionId`, `text`; an `initialBashCommand` only on a new
+   interactive user turn).
+2. Select the native history (`selectHistory`) and resolve the account (`accounts.resolve`).
+3. Resolve the caller's capabilities, intersect with any narrower requested set, and **freeze**
+   them for the run (`capabilities/runSnapshot.ts::freezeRun`).
+4. **Pin** the variant once (`variant/materialise.ts::materialise`).
+5. `saveRun` with status `queued`, the account, `harnessScope` and `harnessVersion`.
+6. Compile the prompt (`sessionLaunch`, page 04): a stable system prompt and an optional context
+   update.
+7. `runs.start` the live run; build the tool list (broker, harness tools, the plan-eligible
+   `ask_user`, subagent tools, provider tools) and the gate.
+8. Open Pi through the `SessionFactory`, with resources loaded in order: disk extensions chosen by
+   the harness, variant extensions, inline extensions, and the gate last.
+9. Record `nativeSessionId`, register the run with `Subagents`, start `runTurn`, and return
+   `{ runId, nativeSessionId }`. The reply streams as run events.
+
+A session that cannot open ends its run as `failed` and returns `nativeSessionId: null`.
+
+## Contracts
+
+- **Run status:** `queued`, `running`, `waiting_for_approval`, `waiting_for_input`, `interrupted`,
+  `completed`, `failed`. The first four are active (`ACTIVE_STATUSES`).
+- **Run events** (`runEventTypeSchema`): `started`, `context.snapshot`, `message.delta`,
+  `message.completed`, `message.steered`, `tool.started`, `tool.completed`, `retry.started`,
+  `retry.ended`, `compaction.started`, `compaction.ended`, `approval.requested`,
+  `approval.resolved`, `question.requested`, `question.answered`, `extension.notice`,
+  `reaction.added`, `agent.message`, `checklist.updated`, `artifact.added`, `file.changed`, `usage.updated`,
+  `account.status`, `status.changed`, `failed`, `completed`. Each has a payload schema in
+  `runEventPayloadSchemas`.
+- **Question sketches** (PROP-0025, ADR-0026; originally PROP-0024, ADR-0025). `question.requested` may include `uiSketch: true`
+  and `sketch` text on each choice. If enabled, every choice must have a sketch; otherwise no
+  choice may carry one. A sketch is 1–24 LF-separated lines, at most 80 printable ASCII characters
+  per line (1,943 bytes maximum), with at least one visible character. Tabs, CR, other controls,
+  escape sequences and non-ASCII text are rejected. Whitespace, including interior blank lines and
+  trailing spaces, is preserved literally in the persisted request event. Tool guidance requests
+  contextual UI wireframes with actual panel/table structure and neighboring elements, consistent
+  across alternatives; generation quality is guidance, not a schema guarantee. Old events remain
+  valid without a data rewrite; readers with the old bounds must update before accepting larger
+  sketches. `question.answered` and `QuestionAnswer` are unchanged.
+- **Checklist** (PROP-0006): `checklist.updated` carries the whole list the model last wrote with
+  `checklist_write`, `{ items: { text, status: pending | in_progress | completed }[] }`, at most 50
+  items. The latest event replaces every earlier one; `checklistOf(events)` reads it.
+- **`RunRecord`** fields are listed in `sessions/contracts.ts`. `mode`, `harness`, `sessionType`,
+  `worktreeId`, `attachmentCount`, `exitCode`, `handoffId` and `trigger` belong to the
+  application: stored and returned, and only `mode` and `trigger` are read.
+- **Triggers the harness reads:** `user` (may carry an initial Bash command), `probe` and
+  `improver` (refinement, page 05), `reflection` (lessons, page 08). Runs with the last three are
+  never asked about: the gate refuses what would need a person, and they receive no question tool.
+  Only attended plan runs may newly receive `ask_user`.
+- **Side questions** (PROP-0019). `sideQuestions.start` creates a separate run with trigger and
+  relation `side-question`, a fresh native history, the selected account/model/effort, no variant,
+  and an empty frozen capability set. It combines the parent's persisted effective prompt and
+  public run events with the surface's visible transcript and selected references, after redaction
+  and fixed bounds. Hidden reasoning and attachment bytes are omitted. A supplied parent run must
+  belong to the supplied parent session. `sideQuestions.read` and `interrupt` require the side run's
+  session id. The run is not a subagent or continuation and never changes the parent.
+- **Subagents.** `spawn_subagent` / `wait_subagents` for the model; `subagents.spawn`, `wait`,
+  `results` for the host (`sessions.spawnSubagent` is a compatibility alias). Child runs have
+  `relation: 'subagent'` and `parentRunId`. Nesting defaults to 1, at most 3 (`subagentDepth`).
+  The child's record carries `title`, the short name the parent gave it (PROP-0030).
+- **Agent profiles** (PROP-0029). `agent` names a profile: built-in (`worker`, `explorer`),
+  `<data root>/agents/<name>.md`, `<project>/.xingular/agents/<name>.md`, or a c5 definition of
+  the parent's variant, later sources winning (`agents/profiles.ts`). A profile narrows the
+  child's tools and plugins (`agents/narrow.ts`), may choose its variant, model and effort, and
+  frames it with a "Your role" section. The child's record carries `profile`; the spawn result
+  carries `agent` and any `unavailableTools`. A run that may spawn lists every profile in its
+  `subagents` section.
+- **Plan mode** (`plan: true`). The stable system prompt is unchanged. An attended plan run may
+  include `ask_user`, subject to the caller's frozen capabilities; the gate refuses everything
+  outside `PLAN_READ_ONLY_TOOLS`, provider tools marked `readOnly`, and calls a provider marks
+  `planModeSafe`. The plan instruction arrives as a dynamic section; for UI-related plans it asks
+  the model to explore distinct design directions, compare trade-offs and recommend one, using
+  contextual `uiSketch` questions when helpful. The reply ends with one `<proposed_plan>` block.
+- **Continuation** (PROP-0007). `continuationOf(root, runId, sessionDir?)` (`runs.continuation`)
+  says whether a stopped run can be continued: `resumable`, a `reason` when not (`not_found`,
+  `active`, `completed`, `no_history`, `history_missing`), the exact native history to reopen,
+  the pinned account, variant version and capability set, the checklist, unanswered approvals and
+  questions, the last tool and whether it finished, and subagents that did not finish.
+  `SessionRunInput.continueFrom` starts a **new** run from it: it reopens that history, records
+  `resumedFromRunId`, pins the same account, variant version and capability set (anything different
+  fails with `continuation_mismatch`; a run that cannot be continued fails with
+  `continuation_unavailable`). If the earlier snapshot includes `ask_user`, an automatic or
+  refinement-triggered continuation fails with `continuation_mismatch` rather than narrowing it.
+  Empty text defaults to "Continue from where you stopped.", and the new run adds
+  a dynamic `continuation` section (order 26) saying where the earlier run stopped. The next run
+  without `continueFrom` withdraws it. `Recovery.interruptedRunIds` lists the runs `open` marked
+  interrupted.
+- **Worktrees** (PROP-0016). When `run.worktreeId` names a worktree in the Harness registry
+  (`worktrees/`), the run works in that worktree's folder (the given `cwd` is replaced), holds a
+  lease on it (holder: the session id, with `git worktree lock`) until the run completes, fails or
+  is interrupted, and records the id. An id the registry does not know is stored and returned as
+  the caller's own field, as before. A terminal session holds its worktree for its whole life.
+- **Usage** (`usage.updated`). `inputTokens` is uncached input; `cacheReadTokens` and
+  `cacheWriteTokens` are separate; `outputTokens` includes `reasoningTokens`. Totals are
+  cumulative for the run, not the native session. `contextTokens` is the latest request's size.
+- **Provider reasoning summaries.** For supported Responses API families, when reasoning is
+  enabled the runner requests a `detailed` summary and records only the provider's explicit summary
+  (bounded to 4,000 characters) in request-level usage. This does not change reasoning effort or
+  guarantee a provider will return a summary; raw reasoning is not used as a substitute.
+
+## Invariants
+
+- **INV-RUN-1** A run pins one account, one variant version and one capability set when it
+  starts. None of them changes during the run. A pinned account that cannot be used fails the
+  run; it is never swapped (`INV-ACC-2`). A side-question run is the explicit exception for the
+  variant: it pins no variant and uses the fixed Harness instruction plus a redacted main-run
+  context projection (PROP-0019).
+- **INV-RUN-2** A run's capability set is written once (`freezeRun`). A resumed or duplicate launch
+  with a different set fails with `capabilities_frozen`. A child run's set is the intersection of
+  its parent's, its profile's tools and plugins, and what it asked for; it never widens.
+- **INV-RUN-3** Every run event is validated against its schema, redacted, persisted, and only then
+  relayed to listeners, in order. An event that arrives after the run settled is kept as evidence
+  and never applied or relayed.
+- **INV-RUN-4** A restarted harness never restarts model work. On `open`, runs left active are
+  marked `interrupted` unless another live process owns them (`owner.json`). Recovery of a
+  subagent needs the same account, caller, working folder and history branch. Continuing is always
+  a new run the application asks for with `continueFrom`; it pins the earlier run's account, variant
+  version and capability set, and the earlier run's record is never reopened.
+- **INV-RUN-5** Unattended runs (`automatic: true`) load no extension found on disk, read no
+  context files, and never ask a person: anything that would need approval is refused. A variant's
+  own trusted plugins still load, except for side-question runs, which have no variant or plugin
+  code and use an empty capability set (PROP-0019).
+- **INV-RUN-6** Only the harness writes `runs/<id>/`; an application reads it. `run.json`,
+  `events.jsonl`, `owner.json` and `subagents.json` are written only through
+  `sessions/runStore.ts`. Side files are written by their owning module: `context.json`
+  (`prompt/compile.ts`), `caller.json` (`sessions/sessions.ts`), `capabilities.json`
+  (`capabilities/runSnapshot.ts`), `mcp-context.json` (`mcp/service.ts`). Adding another writer
+  or side file needs a proposal. (See drift D-1.)
+- **INV-RUN-7** Token accounting follows the usage contract above. Changing what a field means is
+  an architecture change.
+- **INV-RUN-8** Plan mode keeps the stable system prompt but has mode-specific tools: an attended
+  plan may include `ask_user`, subject to the frozen caller capabilities; newly resolved normal,
+  automatic, probe, improver and reflection runs omit it. The terminal activates `ask_user` and
+  `ask_user_question` only for a plan request, then restores its normal set. Plan refusals happen
+  before approvals and no approval can lift them. Provider-cache effects of the tool-list difference
+  are not assumed (page 04, `INV-PRM-8`).
+- **INV-RUN-9** Subagent results reach the parent at native turn boundaries, at most once
+  automatically (typed receipts in native history). A parent joins outstanding children before it
+  completes.
+- **INV-RUN-10** An initial Bash command is allowed only on a new interactive user turn (not
+  automatic, plan, resumed, continuing, relation, probe or improver runs), must match the leading `!` command
+  in the text, and passes the same gate as model-issued Bash.
+- **INV-RUN-11** A side-question run is independent, tool-free and temporary. It receives only a
+  bounded, redacted projection of the main run's effective prompt and public events plus the
+  surface's visible transcript and selected references. It excludes hidden reasoning and attachment
+  bytes, never reads the main native history, and never changes or steers the parent. Its own run
+  record and events use the normal store contract (PROP-0019).
+
+## Data
+
+`<data root>/runs/<id>/`: `run.json`, `events.jsonl`, `owner.json`, `subagents.json`,
+`context.json`, `caller.json`, `capabilities.json`, `mcp-context.json`. Native history lives in
+the session directory the caller passes (`sessionDir`), owned by Pi. Side-question native history
+uses a one-use OS temporary directory, removed when the run settles; its tracked run and events
+remain in the ordinary run store.
+
+## Source map
+
+`src/sessions/*.ts`, `src/capabilities/runSnapshot.ts`, `src/tools/spawnSubagent.ts`.
+Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (superseded),
+[ADR-0003](../decisions/ADR-0003-shared-asynchronous-subagents.md),
+[ADR-0022](../decisions/ADR-0022-plan-only-question-tools.md),
+[ADR-0023](../decisions/ADR-0023-contextual-side-question-runs.md),
+[ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md).
+
+## Native session names (PROP-0010)
+
+`session_name({ name: string })` adds or revises the current Pi session's name in embedded
+and terminal execution. The agent names meaningful work early and revises it when the overall
+objective changes, including a manual name. Agent-submitted names are imperative sentences
+of at most six whitespace-separated words; whitespace is normalized, and empty names,
+terminal escapes, non-whitespace controls and longer names fail without writing. Identical
+names are a no-op. Pi's native session-info history is the only storage; continuation and
+reopen preserve it. Each child names only itself. There is no additional model request or
+run-event schema. The normal capability selection and host gate apply; `harnessTools: false`
+omits the tool. Plan mode permits it as session metadata maintenance.

package/docs/architecture/03-variants.md

@@ -0,0 +1,103 @@
+# 03 Variants
+
+## Purpose
+
+A **variant** is the part of the harness that is allowed to change: everything that shapes an
+agent's behaviour apart from the model, the application's own sections and the foundation
+(page 00). It is eight components (c1–c8, after Harness²). Each caller scope has
+content-addressed, validated, immutable versions of its variant and a head, the variant it runs
+now. A run pins one version. Refinement (page 05) proposes new variants; a person adopts them.
+
+What a variant may contain is fixed by the foundation: the surface (`PI_SURFACE`), the validator
+and the always-on cap. A variant can change what the agent is told and which skills, scripts,
+subagents and plugins it may load. It cannot change the prompt compiler, the gate, the run
+recorder, accounts or trust.
+
+Earlier documents called this the "harness tree" and its invariants `INV-TREE-n`; those are now
+`INV-VAR-n`.
+
+## Components
+
+The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness runs.
+
+| c | Component | Path in the variant | Reaches a run | Group |
+|---|---|---|---|---|
+| c1 | System prompt | `systemprompt.md` | always (prompt section `system`, order 25) | context |
+| c2 | Guardrails | `guardrails.md` | always (`guardrails`, 40) | context |
+| c3 | Memory | `memory.md` | always (`memory`, 45) | context |
+| c4 | Tool guidance | `tool_guidance.md` | always (appended to the `tools` section) | tool interface |
+| c5 | Subagents | `sub_agents/<name>/AGENT.md` | own context; instruction-only agent profiles, listed with the other profiles in `subagents` (64, PROP-0029) | orchestration |
+| c6 | Skills | `skills/<name>/SKILL.md` (+ `scripts/`) | on demand, loaded by Pi as skills | context |
+| c7 | Scripts | `scripts/<name>.py` or `.mjs` | on demand, listed in `scripts` (66) | tool interface |
+| c8 | Plugins | `plugins/<name>.ts` | inside the tool loop, as Pi extensions | middleware |
+
+| Type / function | Module | Role |
+|---|---|---|
+| `Variant` (path → text), `SurfaceSpec`, `ComponentInfo` | `variant/surface.ts` | The editable surface and its patterns. |
+| `validate`, `readVariant`, `writeVariant`, `diffSummary`, `applyEdit`, `autotrigger` | `variant/variant.ts` | Validation and editing. |
+| `commit`, `seed`, `restore`, `head`, `lineage`, `fingerprint` | `variant/store.ts` | Versions and the head. |
+| `materialise`, `resolve`, `VariantChoice`, `Materialised` | `variant/materialise.ts` | Turns a version into prompt sections, skill paths and extension paths for one run. |
+| `VariantTrust` | `variant/trust.ts` | Which plugin code a person trusted, by hash; which scopes let probes run improver code. |
+| `seedVariant` | `variant/seed.ts` | A first variant for a scope. |
+| component library | `variant/components.ts` | Reusable skills, prompts and rules under `registry/` and built-in folders. |
+
+## Contracts
+
+- **`VariantChoice`**: `{ scope, version? }` (a scope's head or one version) or `{ dir, scope? }`
+  (a variant on disk, read and never written, such as a refinement candidate).
+- **Version source** (`VersionSource`): `seed`, `edit`, `refinement`, `import`, `restore`.
+- **Fingerprint**: first 16 hex characters of SHA-1 over sorted `path\0text\0` pairs.
+- **Validation** (`validate`) refuses a variant when: always-on text (c1–c4) exceeds 24,000
+  characters; a file is off the surface; a skill lacks `description:` or its `name:` differs from
+  its folder; a skill is never named in the always-on text; a subagent lacks `description:`; a
+  script does not compile; a plugin has no default export; an always-on file or skill invokes a
+  script that is not in the variant.
+
+## Invariants
+
+- **INV-FND-1** Only a variant mutates. No edit, improver session or adoption changes foundation
+  code, the surface, the validator or an invariant; those change by release, with a proposal.
+- **INV-FND-2** A variant changes only by committing a new validated version (`commit` →
+  `validate`, `INV-VAR-2`), and a refinement moves a head only when a person adopts
+  (`INV-REF-6`). There is no other door.
+- **INV-VAR-1** A variant is the only thing in the harness that shapes an agent's
+  instructions. The application adds its own sections through `Launch` (page 01); no other
+  harness code adds instruction text.
+- **INV-VAR-2** Every saved version is validated (`commit` → `validate`). An invalid variant is
+  refused with every problem listed.
+- **INV-VAR-3** A version is never edited. A change is a new version; `restore` moves the head
+  and appends to `restores.jsonl`.
+- **INV-VAR-4** A run resolves its variant once and pins it; a child run or later turn uses the same
+  files even if the head moves. A child whose agent profile names another variant resolves and
+  pins that one when it starts (PROP-0029).
+- **INV-VAR-5** c8 plugin code loads only when its exact text is trusted (SHA-256 in
+  `variant-plugin-trust.json`). A changed file asks again. The one exception: a refinement probe may
+  run improver-written code for a scope whose person allowed it (`probeCode`), and adopting that
+  variant still requires the code trusted.
+- **INV-VAR-6** The always-on cap exists because every always-on character costs every run.
+  Raising it is an architecture change.
+- **INV-VAR-7** Variant code is synchronous (`INV-BND-4`).
+
+## Data
+
+```text
+<data root>/variants/<scope>/
+  versions/<fingerprint>/variant/<rel>
+  versions/<fingerprint>/version.json
+  head.json
+  lineage.jsonl
+  restores.jsonl
+<state dir>/variant-plugin-trust.json
+<data root>/registry/{skills,prompts,rules}/   (component library)
+```
+
+## Source map
+
+`src/variant/*.ts` (`migrate.ts` renames state written before PROP-0009 on `open`). Method origin: Harness² (`harness2/core/tree.py`, Apache-2.0).
+
+## Terminal inspection
+
+The resource browser retains the materialised preparation snapshot and labels it pinned. The
+current scope head is separately labelled latest saved; browsing and comparison never rematerialise
+the head as the running variant. Directory-backed variants remain browse-only. Library additions
+use the existing validated commit door and affect future terminals.