@xingular/harness 0.1.6 → 1.0.0

package/docs/README.md

@@ -0,0 +1,34 @@
+# 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.
+
+| ID | Record | Type | Status | Related |
+|---|---|---|---|---|
+| ADR-0014 | [Public release baseline](decisions/ADR-0014-public-release-baseline.md) | Decision | Accepted; candidate 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-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 | Accepted; implementation verified, npm publication pending authorization | [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;
+they do not establish publication or release. Evidence references on the terminal page identify
+the inspected upstream artifacts and bound the verification claims.

package/docs/architecture/00-overview.md

@@ -0,0 +1,159 @@
+# 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
+Application (for example the App repo)      agents, groups, tasks, projects, worktrees, UI, PTY, keychain
+   │  seven extension points (01) and the server protocol (10)
+Harness (this package)                      variants, prompt, sessions, runs, gate, Wiki, history, plugins, MCP, refinement, terminal
+   │  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.
+- **The application** supplies what only it knows, through the extension points, and reads what
+  the harness records.
+
+**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, and the server protocol.
+
+**Stays in the application:** agents, groups, conversations, tasks and coordination, projects and
+worktrees, App browser UI and tab sharing, computer use, windows, the PTY, the keychain, and application UI.
+
+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 |
+| `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 application's column (PTY, worktrees, roles, tasks, review, schedules, UI) is in the parent
+`AGENTS.md` and the App's architecture pages.
+
+## 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 and no application concept (agent role, group,
+  task, pane, worktree, handoff, App browser workspace, computer use) in code paths it reads or text a model or
+  person sees. Text names the product through `env.productName` (default `Xingular Harness`;
+  `{product}` in a tool description). Ids such as `agentId`, `projectId` and a variant `scope` are
+  opaque; names come from `Directory` or `CallerContext.agentName`.
+- **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).

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,146 @@
+# 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. |
+| 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, `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`.
+- **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.
+- **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`).
+- **Plan mode** (`plan: true`). The tool list is unchanged; 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; 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`), defaults empty text to "Continue from where you stopped.", and 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.
+- **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.
+
+## 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`).
+- **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 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.
+- **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 never changes the tool list or the system prompt, so switching it keeps
+  the cached prefix. Its refusals happen before approvals and no approval can lift them.
+- **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.
+
+## 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.
+
+## 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).
+
+## 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,95 @@
+# 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, listed in `subagents` (64) | 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.
+- **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).

package/docs/architecture/04-prompt.md

@@ -0,0 +1,102 @@
+# 04 Prompt
+
+## Purpose
+
+One compiler builds every model instruction the harness gives. It merges the pinned variant's
+sections, the harness's own sections and the application's sections into an ordered,
+budgeted pack, then splits the pack into a **stable system prompt** (cached by the provider) and
+a **context update** (changing state appended to native history). Keeping the two apart is what
+keeps provider caching effective across turns.
+
+## Components
+
+| Type / function | Role |
+|---|---|
+| `compile(env, caller, launch, variant)` → `ContextPack` | Builds the ordered, budgeted sections. |
+| `render(env, pack)` → `string` | One string for a session that takes a single prompt. |
+| `sessionLaunch(env, caller, launch, historyFile, variant)` → `{ system, update, pack }` | SDK sessions: stable prefix plus an update with only the dynamic sections that changed since the last delivered snapshot. |
+| `deliveredSnapshot(sessionFile)` | Reads the last delivered snapshot on the active history branch; a compaction forces a fresh one. |
+| `saveForSession`, `copyToRun` | Terminal sessions keep the pack they started with and copy it to each run. |
+| `record`, `load`, `packPath` | The pack each run was given, at `runs/<id>/context.json`. |
+| `toolGroups`, `fit`, `clip` | The tool manifest by group; cutting text to a budget at a paragraph boundary. |
+
+All in `prompt/compile.ts`. A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
+`body`, `sources`, `budget`, `size`, `cut`), `toolGroups`, `harness` (scope and fingerprint),
+`profile`, `compiledAt` and `delivery` (`systemSectionIds`, `updatedSectionIds`).
+
+## Section order
+
+`SECTION_ORDER`: `system` 25, `guardrails` 40, `memory` 45, `references` 50, `subagents` 64,
+`scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections sit among them by their `order`; plan
+mode uses `plan` at 25. Ties keep insertion order.
+
+Budgets (characters): variant sections 30,000 each (already capped at save, so never cut here);
+references 12,000; Wiki pointer 2,500; tools 8,000; reporting 2,000; application sections their
+own `budget`.
+
+## Reporting
+
+Every pack ends with the harness's `reporting` section ("Reporting your work",
+`REPORTING_GUIDANCE` in `prompt/compile.ts`). It is fixed text that shapes the final reply: lead
+with the answer or outcome, then use only headings or structure that help explain it; no fixed list
+of report headings is required. When a concrete verification requires a person because the agent
+could not perform or observe it, the optional **Need human inspection** heading says what remains
+unverified, why, and the specific check the person should make. Report only checks actually run,
+with their results. Markdown tables are used where they help compare options or present repeated
+fields or check results; any format the person, application or current mode asks for takes
+precedence. The section names no application, is never dynamic, and is never cut. See
+[PROP-0001](proposals/PROP-0001-reporting-section.md),
+[PROP-0004](proposals/PROP-0004-flexible-reporting-guidance.md), and
+[ADR-0008](../decisions/ADR-0008-flexible-reporting-guidance.md).
+
+## Delivery
+
+```text
+compile ──► pack ──► stable sections ──► system prompt (+ "Context updates" guidance)
+                └──► dynamic sections ──► compare with delivered snapshot ──► custom message
+                                                                              type xingular-context
+```
+
+- Dynamic sections are the built-in `references` and `wiki`, plus every application section with
+  `dynamic: true`.
+- An update lists only the dynamic sections that changed, and announces a withdrawn one.
+  `references` is always resent when present, because it belongs to the current request.
+- The session appends the update as a hidden custom message and saves its snapshot in the
+  message details (`xingularContext`); recording a pack does not mark it delivered.
+- Terminal sessions use `compile` + `render` once, pass it as `--append-system-prompt`, and keep
+  that pack for the life of the session.
+
+## Invariants
+
+- **INV-PRM-1** The prompt is assembled only in `src/prompt/compile.ts`. Nothing else builds model
+  instructions. SDK sessions use `sessionLaunch`; terminal sessions use `compile` + `render`.
+- **INV-PRM-2** The system prompt holds only stable text: identity, role, the variant's sections, the
+  harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it.
+- **INV-PRM-3** `references`, `wiki`, and every section the application marks `dynamic` are
+  delivered as context updates in native history, never in the system prompt.
+- **INV-PRM-4** An update carries only changed dynamic sections, so an unchanged turn appends
+  nothing. A compaction on the active branch forces the full snapshot again.
+- **INV-PRM-5** The pack only describes tools the caller can call (the frozen capability set).
+- **INV-PRM-6** Each run's pack is recorded beside the run. Failing to record it never fails the
+  session.
+- **INV-PRM-7** The compiler is synchronous (`INV-BND-4`).
+- **INV-PRM-8** Whether a prompt change keeps the provider's cache is measured with real requests
+  from the application, only with the account owner's permission. Tests do not stand in for it.
+
+## Relation to DESIGN-0001
+
+[`../system-prompt-design.md`](../system-prompt-design.md) is a draft design (not accepted). Only
+what this page states is binding. Adopting parts of that draft is an architecture change.
+
+## Source map
+
+`src/prompt/compile.ts`, `src/sessions/sessions.ts` (calls `sessionLaunch`),
+`src/terminal/terminals.ts` (calls `compile` + `render`), `src/variant/materialise.ts` (variant
+sections), `src/sessions/planMode.ts` (`plan` section).
+
+## Session naming guidance (PROP-0010)
+
+The Session tool group describes `session_name` when available: name meaningful work early
+with an imperative sentence of at most six words, and revise when the objective changes.
+This is fixed foundation guidance. The current name stays in native session metadata and
+the terminal snapshot; it is never interpolated into the stable system prompt.