@xingular/harness 0.1.7 → 1.1.1

package/README.md

@@ -1,30 +1,63 @@
 # Xingular Harness
 
-A Pi agent harness, as one TypeScript package (`@xingular/harness`). It is everything a model
-needs to work for someone over time, and nothing about any particular application:
-
-| Part | Folder | What it does |
+A Pi agent harness built on **recursive harnessing** ([Harness²](https://arxiv.org/abs/2610.14224),
+Apache-2.0, Google LLC), as one TypeScript package (`@xingular/harness`). It lets a running host
+improve the harness itself, with model weights fixed. To say that precisely, the harness has two
+halves:
+
+- **The foundation is fixed.** Pi sessions, the prompt compiler, the run recorder, the tool gate,
+  accounts, plugin-code trust, the refinement method and the extension points. Only a release
+  changes it.
+- **A Harness Variant (HV) mutates.** It is what a model is told and can load: eight components
+  (c1–c8) for one scope. Each scope has versioned, validated HVs; a run pins one version, and
+  refinement proposes a better HV that a person adopts.
+
+*The foundation runs a variant, records how it went, and lets refinement propose a better
+variant; only a person adopts one.* Refinement edits a copy of a variant and never the
+foundation. See [Foundation and variants](docs/architecture/00-overview.md#foundation-and-variants).
+
+Recursive refinement proposes HV improvements from run evidence. A person adopts candidates;
+model weights and the foundation stay fixed. See the [Google Harness² feature guide](docs/features/google-harness2/README.md)
+for the method and HV components.
+
+| Area | Main features | Guide |
 |---|---|---|
-| Accounts | `src/accounts/` | Several isolated Pi accounts and pools, sign-in, model lists, health and limits. A session keeps the account it started with. |
-| Sessions | `src/sessions/` | Pi SDK turns, run records and `events.jsonl`, interrupt, approvals, questions, recovery after a crash. |
-| Prompt | `src/prompt/` | The system prompt compiled from sections with budgets and profiles; a stable prefix, and changing state delivered as updates in native history. |
-| Memory | `src/memory/` | The Wiki: pages, facts, memory blocks, revisions, proposals with an evidence gate, undo, an Inbox, recall over past runs, and sleep-time consolidation. |
-| Skills | `src/skills/` | Skills, prompts, and rules: a person's own in the data root, and built-in ones shipped with the harness or the application. |
-| Plugins | `src/plugins/` | What a Pi session loads, chosen by the harness and never by Pi's own discovery; trust for a working folder's code; the list of every plugin and what reaches one caller. |
-| Tools | `src/tools/` | Tool definitions, the memory tools, `ask_user`; a gate that asks the application's policy, then standing approvals, then the person. |
-| Connected apps | `src/mcp/` | MCP connections, OAuth, per-session grants, redaction, a trace of what each call returned. |
-| Terminal | `src/terminal/` | A Harness-owned terminal frontend over persistent Pi sessions, isolated accounts, compiled instructions, the tool gate and telemetry bridge, native history, plugin UI, `/plugins`, `/hub`, `/accounts`, and the existing session socket. |
-| Server | `src/server/` | The same API over newline-delimited JSON, for a host that is not a Node program. |
-
-It was split out of Xingular Agent, which is now an application built on it.
-The [documentation index](docs/README.md) links current terminal architecture and decisions.
+| Core runtime | Accounts, sessions and runs, prompt compilation, tool governance | [Cores](docs/features/cores/README.md) |
+| Harness² | HVs, recursive refinement, answer-free selection, experience library | [Google Harness²](docs/features/google-harness2/README.md) |
+| Automations | Subagents, recovery, optional run reflections, plugin hooks | [Automations](docs/features/automations/README.md) |
+| Memory | Wiki notes, run recall, trajectory search and reads | [Memory](docs/features/memory/README.md) |
+| Integrations | Application extension points, plugins, connected apps and Hub | [Integrations](docs/features/integrations/README.md) |
+| Interfaces | Node embedding, standalone terminal and JSON-lines server | [Interfaces](docs/features/interfaces/README.md) |
+
+The binding design of every part is the [architecture specification](docs/architecture/README.md).
+
+Try refinement with no model and no credentials: `npm run build && node dist/cli.js refine demo --k 2`.
+The [feature guide](docs/features/README.md) groups capabilities by area; the [documentation
+index](docs/README.md) links the architecture and other project records.
 
 ### Session options for applications
 
-- `subagents: { maxDepth }` offers `spawn_subagent`: the model may start a child run of the same caller (`relation: 'subagent'`). The child has no more tools than the parent and settles before the tool returns.
+- Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
+- `harness.subagents.spawn({ parentRunId, brief, agent?, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. `agent` names an agent profile (below). It returns `{ runId, nativeSessionId, agent?, unavailableTools? }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
+- **Agent profiles** (PROP-0029) are what a subagent starts from: the built-in `worker` (reads, edits, writes, runs commands) and `explorer` (reads only), a person's own `<data root>/agents/<name>.md`, a repository's `<project>/.xingular/agents/<name>.md`, and the variant's c5 subagents, later ones winning. A profile is Markdown with frontmatter (`description`, `color`, `tools`, `plugins`, `variant`, `model`, `effort`) and its body is the role. It only narrows the parent's tools and plugins. `listProfiles`, `resolveProfile`, `createProfile` and `removeProfile` (RPC `agents.list|get|create|remove`) read and write them, and the child's `RunRecord.profile` names the one it used.
+- The model's `spawn_subagent` returns immediately by default; `wait: true` returns an inline result. `wait_subagents` joins selected children. The SDK and standalone terminal share this execution service. Terminal calls use its private control channel, including when connected apps are disabled.
+- Parents receive results at native turn boundaries and join outstanding children before completing. Typed native-history receipts prevent duplicate automatic delivery; explicit waits can reread results. Ownership is recorded before startup so an explicit resume can recover even a lost spawn return. Startup reservations without a run become interrupted outcomes. A restarted Harness never restarts model work automatically. Recovery requires the same recorded account, caller, working folder, and selected history branch. Session IDs are opaque; consumers follow `parentRunId` and `relation`.
 - `providers: false` runs a session with the harness's own tools only.
-- On the caller, `vaultAccess: 'propose'` writes no memory directly, and `recallExcludeAgents` hides those agents' conversations from recall.
-- `maintenanceRunTrigger: false` (a harness option) leaves memory to explicit proposals and scheduled merges.
+- `variant: { scope }` runs the session on that scope's head variant (or `{ scope, version }`, or `{ dir }` for a variant on disk). The version is pinned for the run and recorded on it.
+- On the caller, `recallExcludeAgents` hides those agents' conversations from history and trajectory tools.
+- `harnessTools: false` runs a session without the History, Wiki and skill tools (and without `ask_user` and `checklist_write`).
+- Every session with harness tools gets `checklist_write`: the model sends its whole checklist (`pending`, `in_progress`, `completed`, at most 50 steps) and the run records it as a `checklist.updated` event. `checklistOf(events)` or the `runs.checklist` method reads the latest one. Plan mode allows it.
+- `continueFrom: <run id>` continues a run that stopped before it finished (interrupted or failed) as a new run. `harness.recovery.interruptedRunIds` lists the runs `open` marked interrupted, and `continuationOf(root, runId, sessionDir)` (`runs.continuation`) says whether one can be continued and what it left: checklist, unanswered approvals and questions, the last tool and whether it finished, unfinished subagents. The new run reopens the same native history, records `resumedFromRunId`, keeps the account, variant version and capability set (`continuation_mismatch` otherwise), and the model is told where the earlier run stopped. The harness never continues a run by itself; which runs to continue, and when, is the application's choice.
+- The first-party `lessons` plugin (off by default) reflects on a completed top-level run with enough tool calls and may keep one general lesson in the Wiki under `library/lessons/`, in refinement's cue/lesson shape. It uses the run's own account and model, read-only file tools, and is capped (`minToolCalls`, `maxLessons`, `maxChars`). See PROP-0008.
+
+Every session also gets `trajectory_search` and `trajectory_read` from the built-in History plugin.
+Search lists runs in the current data root, including active runs, with filters and a continuation
+cursor. Read returns pages of the canonical execution events, including captured prompt/context,
+tool, decision, retry, compaction, and usage evidence. Active runs show the latest events saved so
+far; settled reads stop at the first outcome. Payloads are bounded and marked when truncated, and
+the tools omit account identifiers, credential fields, attachment bytes, native adapter payloads,
+and provider reasoning text or summaries.
+They report recorded evidence without scoring runs, and do not backfill older records.
 
 ## Using it from Node
 
@@ -32,16 +65,19 @@ The [documentation index](docs/README.md) links current terminal architecture an
 import { createHarness } from '@xingular/harness'
 
 const harness = createHarness({
-  dataRoot: '/path/to/data',        // knowledge and history: wiki/, registry/, runs/, index.sqlite
+  dataRoot: '/path/to/data',        // variants/, library/, refine/, wiki/, registry/, runs/, index.sqlite
   stateDir: '/path/to/state',       // device-local: accounts, approvals, connections, sockets
-  productName: 'My App',            // how the harness names itself to a model (default 'Xingular Harness')
+  productName: 'My App',            // how the harness names itself to a model (default 'Xingular Agent')
   secrets,                          // SecretStore; defaults to an owner-only file in stateDir
   policy,                           // ToolPolicy: what a run may do, and what needs a person
   directory,                        // names for the ids the application uses
   builtins: ['/path/to/builtin'],   // folders of built-in skills, prompts, and rules
-  plugins: [myPlugin]               // the application's own parts, described as plugins
+  plugins: [myPlugin],              // the application's own parts, described as plugins
+  refineHost                        // where refinement executions work, as whom, with which tools
 })
 
+harness.refine.start({ task: { id, scope: 'agent-1', prompt }, k: 1, mode: 'parallel' })
+
 harness.sessions.provide((session) => myTools(session))   // the application's own tools
 harness.runs.listen((event, run) => show(event))            // every run event, after it is saved
 
@@ -49,6 +85,7 @@ await harness.sessions.run({
   run: { id, sessionId },
   cwd, sessionDir, text,
   caller: { agentId, agentName, actor: 'Chat' },
+  variant: { scope: 'agent-1' },
   launch: { sections: [{ id: 'identity', title: 'Identity', body, budget: 2000, order: 10 }] },
   tools: { allow: ['read', 'bash', 'my_tool'], gated: ['bash'] }
 })
@@ -56,14 +93,14 @@ await harness.sessions.run({
 
 ## How an application extends it
 
-The harness knows a caller (an opaque id that owns memory), never an agent, a group, or a task.
-An application adds what it knows through six points:
+The harness knows a caller and a harness scope (opaque ids), never an agent, a group, or a task.
+An application adds what it knows through seven points:
 
 1. **Prompt sections** (`Launch.sections`, `Launch.toolGroups`, `Launch.references`). Each
-   section has an `order` and may be `dynamic`. The harness adds its own (`blocks` 30, `rules` 40,
-   `references` 50, `skills` 60, `knowledge` 80, `tools` 90), applies budgets and the caller's
-   context profile, keeps stable sections in the system prompt, and sends dynamic ones as
-   updates.
+   section has an `order` and may be `dynamic`. The harness adds its own (`system` 25,
+   `guardrails` 40, `memory` 45, `references` 50, `subagents` 64, `scripts` 66, `wiki` 80,
+   `tools` 90), applies budgets, keeps stable sections in the system prompt, and sends dynamic
+   ones as updates.
 2. **Tool providers** (`harness.sessions.provide`). A provider returns `ToolSpec`s for a session;
    only the names in the session's `allow` list are registered, in that order.
    A tool may return `attachments` as `{ id, name, mimeType }` references. The harness records
@@ -72,9 +109,6 @@ An application adds what it knows through six points:
    The harness provides the web tools itself: `webTools({ secrets })` gives `web_search` (Brave Search,
    key read from the secret store) and `web_fetch` (checked reads of public pages). An application
    passes it to `harness.sessions.provide` and switches the names on for each agent.
-   `registryTools({ harness })` gives `registry_write` (a skill, rule, or prompt) and `plugin_write`
-   (a plugin). Each writes for the calling agent only: the item is on for that agent, and a plugin's
-   code is trusted once written. An item others already use goes to the Inbox instead.
 3. **`ToolPolicy`**. `scope` says whether a call is inside what the run may do (or needs one
    approval). A decision with `humanOnly` is for a person alone: the always-approve switch and
    remembered answers do not apply to it. `authorize` says whether the tool is still switched on;
@@ -87,6 +121,11 @@ An application adds what it knows through six points:
    the application and says which tools, prompt sections and tool groups it provides. It is data:
    it changes what `plugins.list` and `plugins.inventory` report, never what runs. `WEB_PLUGIN`
    describes the web tools. A host that is not a Node program sends them with `plugins.describe`.
+7. **`RefineHost`** (`HarnessOptions.refineHost`). Where a refinement execution works
+   (`prepareWorkspace`: an isolated folder, such as a git worktree), as whom and with which tools
+   (`session`), and what it produced (`deliverable`). Executions run as unattended runs with
+   trigger `probe`, so a `ToolPolicy` can refuse anything with effects outside that folder;
+   improver sessions run with trigger `improver`, file tools only, on a copy of the evidence.
 
 `apps.expose(...)` additionally offers the application's tools through the connected-apps
 broker (`mcp_list_tools`, `mcp_call_tool`), which is how a terminal session reaches them.
@@ -95,7 +134,7 @@ broker (`mcp_list_tools`, `mcp_call_tool`), which is how a terminal session reac
 
 A plugin is a bundle with a title, a description and contributions: instructions, skills,
 commands, tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it
-is; so are the harness's own parts (Memory, Wiki, History, Ask the user, Connected apps, Pi), the
+is; so are the harness's own parts (Harness, Wiki, History, Subagents, Ask the user, Connected apps, Pi), the
 application's, a person's registry ("Yours"), the folder every account shares, and what a
 working folder brings.
 
@@ -129,11 +168,10 @@ working folder brings.
   input does so before the gate sees it. Every resource reload revalidates the parent's original
   trusted selection; changed or revoked code requires review and a fresh terminal.
 - **A required part can be extended.** A package names the part it adds to and, optionally, a
-  hooks file: `"harness": { "extends": ["memory"], "hooks": "./hooks.mjs" }`. The harness runs
-  hooks itself (`src/plugins/hooks.ts`), in its own process, because most memory is written while
-  no session is open. `export default function (harness) { harness.on('memory.saved', async
-  (event, ctx) => …) }`; the events are `memory.saved`, `memory.block.changed`,
-  `wiki.page.saved` and `history.run.ended`. A hook is told after the write and cannot stop it,
+  hooks file: `"harness": { "extends": ["wiki"], "hooks": "./hooks.mjs" }`. The harness runs
+  hooks itself (`src/plugins/hooks.ts`), in its own process, because notes are often written while
+  no session is open. `export default function (harness) { harness.on('wiki.page.saved', async
+  (event, ctx) => …) }`; the events are `wiki.page.saved` and `history.run.ended`. A hook is told after the write and cannot stop it,
   has 30 seconds, and what it throws is kept in `plugin-hooks.json` and shown on its plugin. It
   runs only while its plugin is switched on for everyone and trusted; what is loaded is checked
   against that before each delivery. `ctx.call(connection, tool, args)` reaches a connected app
@@ -157,10 +195,11 @@ working folder brings.
   terminal process claims once (`control.claim`) and shares with its bridge in memory; the socket's
   `plugins.list` is open to the session, and `plugins.attach`, `plugins.detach`, `plugins.trust`
   and `plugins.untrust` refuse without that key. A change applies when the session restarts.
-  Outside a session, `xingular-harness plugins list | show | install | remove | update | attach |
+  Outside a session, `xagent plugins list | show | install | remove | update | attach |
   detach | trust | untrust` acts directly, as the person who typed it; `trust` shows the files
   and wants a typed yes or `--yes`. It does not open the data root, so it settles no run.
-- **Unattended runs and memory maintenance load no extension**, as before.
+- **Unattended runs load no extension found on disk.** A variant's own trusted plugins still
+  load, so a refinement probe runs the plugin it is testing.
 - **A person switches things on and off for a scope.** `plugins.attach` and `plugins.detach`
   take a plugin's or a contribution's `id` and a `scope` (`{}` for everywhere, `{ agentId }`, or
   `{ projectId }`). The narrowest scope that says something wins: an agent, then a project, then
@@ -204,7 +243,8 @@ table. With the `--host-*` flags the harness calls the host for `secrets.get|set
 `policy.scope|authorize|approval|connections`, and `tools.call`; the host registers its tools
 with `tools.register` and its names with `directory.set`.
 
-`skills.import` accepts complete user-owned skill folders:
+`variants.importComponents` adds complete skill folders, or single-file rules and prompts, to the
+component library:
 
 ```ts
 { skills: [{ name, files: [{ path, content, encoding }] }] }
@@ -215,7 +255,8 @@ It validates bounded relative paths and file encodings, requires a root
 has no knowledge of the application feature that may call it.
 
 `npm run prove` starts that server on a throwaway data root, with no application present, and
-exercises accounts, memory, skills, the prompt, connected apps, and a recorded session.
+exercises accounts, variants, the Wiki, the prompt, connected apps, a recorded session, a
+plugin hook, and the refinement demo end to end.
 
 ## Run it as a standalone Harness terminal
 
@@ -223,13 +264,12 @@ After the CLI package is published to npm or your company's npm registry, instal
 
 ```sh
 npm install --global @xingular/harness
-xingular-harness
+xagent
 ```
 
-The machine needs Node 22.19 or newer. Harness runs its own terminal frontend through the
-active Node runtime on every platform, using its pinned Pi SDK; no separate global `pi`
-installation is required. On first launch, it creates a `Default` isolated account. Use
-`/accounts` or `/login` to sign in.
+The machine needs Node 22.19 or newer and Bun 1.3.14 or newer. Harness runs its own OpenTUI
+terminal frontend with Bun, using its pinned Pi SDK; no separate global `pi` installation is
+required. On first launch, it creates a `Default` isolated account. Use `/accounts` to sign in.
 
 Provider sign-in progress lives in the running Harness process. An embedding application can call
 `accounts.loginStatus` after reconnecting to recover the current device code or prompt by account;
@@ -244,30 +284,95 @@ npm run dev
 ```
 
 `npm run dev` rebuilds the CLI and opens the Harness terminal in the current working directory.
-It uses the normal Harness data and state directories. Press `/quit` or Ctrl+C to close it.
-For separate development data, pass the usual `--data <dir>` and `--state <dir>` arguments:
-`npm run dev -- --data <dir> --state <dir>`.
-
-Building a checkout does not update an existing global `xingular-harness` installation.
+It uses separate development directories by default: `~/.xingular-harness-dev/data` and
+`~/.xingular-harness-dev/state`. This keeps development harness data and device settings—including
+accounts, Pi settings, approvals, and connections—separate from the installed command. Press
+`/quit`, Ctrl+C or Ctrl+D to close it. Override either directory with `--data <dir>` or
+`--state <dir>`; for example: `npm run dev -- --data <dir> --state <dir>`. An omitted option keeps
+its development specific default.
+
+The OpenTUI/Solid frontend is the only terminal. Install Bun 1.3.14 or newer and run
+`npm run build:tui` (or `npm run build`); without Bun the build fails rather than producing a
+terminal that cannot start. The harness runs `dist/terminal-opentui.js`, which uses the same
+session runtime, accounts, command pages, approvals, questions, plugins and run records as the
+embedded SDK. See [the terminal guide](docs/terminal-tui.md).
+
+### Worktrees
+
+Run `xagent --worktree` (or `-w [name]`) inside a git repository to start in a fresh managed
+worktree: a detached checkout under `<state dir>/worktrees/` that carries your uncommitted
+changes, copies ignored files named in `.worktreeinclude`, and runs the repository's
+`.xharness/worktree-setup` once you trust it (`xagent worktree trust-setup`). The 15 most recent
+managed worktrees per repository are kept; older ones are pruned, and unsaved work is kept as a
+snapshot you can restore. `/plugin:worktree` in a session, `xagent worktree <command>` in a shell, and
+the `worktrees.*` server methods offer the same actions: new, switch, create branch, hand off to
+or from the main checkout, remove, restore, prune and adopt. An application passes a worktree's id
+as `run.worktreeId` and the session works in it. See
+[PROP-0016](docs/architecture/proposals/PROP-0016-managed-worktrees.md).
+
+### Page notes
+
+`/plugin:annotate [url]` opens a visible capture browser (its own window and profile, separate from the
+agent's browser). Note the whole page, select a passage, or click an element there, then write the
+note in the terminal. `/plugin:notes` lists, edits, resolves, reveals and deletes notes. A note is private
+until you share it with the session; its agent then reads it with `page_notes_list` and
+`page_notes_read`, with quoted page text marked untrusted. Notes live in `<data root>/annotations/`
+and the `annotations.*` server methods give a host the same store. A host with its own web view
+runs the same page helper (`annotations.pageScript`). See
+[PROP-0017](docs/architecture/proposals/PROP-0017-page-annotations.md).
+
+`/plugin:annotate` turns this into an inspector:
+- Hover a component in the browser or an app window, click it, and write a comment in the popover.
+- Then keep it as a note, add it to the agent's queue, or send it now. The agent reports back with `page_notes_mark_fixed`.
+- App windows work two ways:
+  - **DevTools port:** start an Electron app with `--remote-debugging-port=9229` and run `/plugin:annotate --app 9229`.
+  - **Page bridge:** for a macOS web view such as Tauri, run `/plugin:annotate --bridge` and load the script tag it shows while developing the app. Allow `http://127.0.0.1:<port>` in the app's `script-src` and `connect-src`.
+- A host drives the same flow with `annotations.capture.*`, and sends to its own sessions with `annotations.compose` and `annotations.delivered`.
+
+See [PROP-0018](docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md).
+
+Building a checkout does not update an existing global `xagent` installation.
 To replace that command with this checkout, run `npm pack`, then install the exact tarball
 filename it prints with `npm install --global ./<tarball-filename>`. This is a local install;
 it does not publish a release. Close an already-running terminal session and launch the command
 again to load the new frontend. A package version alone cannot distinguish an unreleased local
 build from an older installed build with the same version.
 
-This opens the Harness-owned terminal frontend in the current working directory. Its
-presentation follows the inspected Oh My Pi 18.11.3 titanium and light palettes, centered welcome, filled
-status band and curved `╰─` prompt, with Harness identity and existing capabilities. Harness
-owns screen composition, editing/input dispatch, scrolling, command routing and plugin UI;
-Pi supplies the persistent execution runtime, native history and rich content components.
-The existing isolated account, compiled context, approval gate, telemetry and Wiki/socket
-commands remain behind the terminal. No Pi `InteractiveMode` is constructed.
-
-`/resume` stays inside the prepared history and working folder; `/import` accepts an explicitly
-selected native JSONL file only for the same working folder. Cancel an active response before
-changing or reloading a session. Full OMP visual parity is not established by the current
-verification. See [terminal architecture and evidence](docs/terminal-tui.md),
-[the decision](docs/decisions/ADR-0001-owned-terminal.md), and [third-party notices](NOTICE.md).
+This opens the Harness-owned OpenTUI terminal in the current working directory. Its presentation
+uses the Harness titanium palette and an OpenCode-inspired layout: the transcript above a
+borderless composer with the working status above it and the model, context and token line below.
+Harness owns screen composition, editing/input dispatch, scrolling, command routing and plugin UI;
+Pi supplies the persistent execution runtime, native history and rich content components. The
+existing isolated account, compiled context, approval gate, telemetry and Wiki/socket commands
+remain behind the terminal. No Pi `InteractiveMode` is constructed.
+
+Core terminal commands stay unprefixed. Built-in and Pi extension plugin commands use
+`/plugin:<command>`; for example, annotate a page with `/plugin:annotate https://example.com`.
+Old unprefixed plugin command forms are no longer aliases.
+
+`/resume` stays inside the prepared account history and working folder. Cancel an active response
+before changing or reloading a session. Full OMP visual parity is not established by the current
+verification. `/harness` opens one browser for Foundation, Variant, Skills, Plugins,
+Connections (MCP), Tools and Library. `/skills`, `/plugins`, `/connections` (`/mcp`) and `/tools`
+open its sections directly; `/hub` opens Discover and `/components` opens Library. Resource
+sections share Installed / Discover, source filters, search and a detail inspector. Tab focuses
+controls, arrows change the focused choice, Ctrl+F returns to search and Escape goes back.
+Skills show actual session availability even with invocation shortcuts off. With shortcuts on,
+Use inserts `$name` into the draft without sending it; typing `$` also completes loaded skills.
+To keep an existing message and attachments, open Ctrl+K, choose Skills, then Use.
+Variant inspection distinguishes the pinned session version from the latest saved version.
+Adding a library skill or rule creates a validated version for future sessions.
+
+`/accounts`, `/permissions`, `/settings`, `/plugin:trajectory` and `/log` retain their own centered pages.
+`/permissions` reviews device-local Pi terminal grants and the Full Permission switch; tool grants
+apply across terminal sessions sharing this Harness state, and Full Permission requires confirmation.
+`/plugin:trajectory` opens recorded runs for the current native conversation,
+with event navigation and a detail inspector. `/log` shows a static, redacted snapshot of Harness
+diagnostics and run events for the current conversation; press Escape to close. See
+[terminal architecture and evidence](docs/terminal-tui.md),
+[the ownership decision](docs/decisions/ADR-0001-owned-terminal.md),
+[the OpenTUI-only decision](docs/decisions/ADR-0006-opentui-only-terminal.md), and
+[third-party notices](NOTICE.md).
 
 ### `/accounts` in the terminal
 
@@ -279,36 +384,46 @@ command the model runs in the shell cannot make it.
 A running session stays on the account it started with. To use another account for this
 session, choose **Use for this session**: the terminal child restarts and the same conversation
 resumes on that account. Removing an account that a running terminal is using is refused. Only
-terminals in this process are counted, so an account used by another running `xingular-harness` window can
+terminals in this process are counted, so an account used by another running `xagent` window can
 still be removed; that session then asks for another account the next time it starts.
 
-The default data and device state directories are `~/.xingular-harness/data` and
-`~/.xingular-harness/state`. Override them with `--data <dir>` and `--state <dir>`. Session
-history is stored per working directory and can be reopened with the terminal's `/resume`
-command. The explicit `terminal` command is an alias for the default launch. Use `--help` to see the commands;
-`serve` remains the host-facing RPC service for integrations such as Xingular Agent/App.
+The installed standalone command defaults to `~/.xingular-harness/data` and
+`~/.xingular-harness/state`; `npm run dev` instead defaults to the separate
+`~/.xingular-harness-dev/data` and `~/.xingular-harness-dev/state`. Override either with
+`--data <dir>` and `--state <dir>`. Session history is stored per working directory and can be
+reopened with the terminal's `/resume` command. The explicit `terminal` command is an alias for
+the default launch. Use `--help` to see the commands; `serve` remains the host-facing RPC service
+for integrations such as Xingular Agent/App.
 
 ## Storage
 
 ```
 <data root>/
-  wiki/             home.md, library/, projects/<slug>/, facts/, blocks/, revisions, inbox, log
-  registry/         skills/, prompts/, rules/   (a person's own; never copied)
+  variants/<scope>/  versions/<fingerprint>/variant/, head.json, lineage.jsonl   (the eight components)
+  refine/<id>/      summary.json, task.json, variants/<label>/, rollouts/, context/, selection/, reflection/, improver/
+  library/<scope>/<area>/  INDEX.md, variants/<task>/{variant/, EXPERIENCE.md}   (the experience library)
+  wiki/             home.md, library/, projects/<slug>/   (project notes)
+  wiki-history/     earlier versions of notes
+  legacy/           what an earlier Wiki kept (memory blocks, facts, revisions, Inbox), moved once
+  registry/         skills/, prompts/, rules/   (the component library; the Hub installs here)
   plugins/<name>/   packages kept with a person's data; each is found as an installed plugin
-  runs/<id>/        run.json, events.jsonl, context.json, caller.json
-  config/           context profiles, what is switched on for whom (plugin-attachments.json),
+  runs/<id>/        run.json, events.jsonl, context.json, caller.json, subagents.json (reserved child IDs)
+  config/           what is switched on for whom (plugin-attachments.json),
                     settings the harness reads
-  index.sqlite      a rebuildable index of Wiki entries and runs (FTS5)
+  agents/<name>.md  a person's agent profiles (a repository keeps its own in .xingular/agents/)
+  index.sqlite      a rebuildable index of runs for recall (FTS5)
   projects.json     read only: the application owns it
 
 <state dir>/
   accounts/         registry, per-account Pi agent folders, audit log
   approvals.json    standing approvals
   plugin-trust.json       the code a person trusted, by hash, and whether earlier packages were taken over
+  variant-plugin-trust.json  harness-variant plugin code a person trusted, and scopes whose probes may run improver code
   plugin-registered.json  what each extension registered the last time a session loaded it
   plugin-hooks.json       what each hooks file listens for and how its last run went
   connections.json  connected apps (secrets are in the SecretStore)
   run/              the session socket and the terminal commands
+  harness.log       diagnostics from the standalone terminal, kept off its screen
 ```
 
 The files are the source of truth; `index.sqlite` can be deleted and rebuilt
@@ -318,28 +433,39 @@ The files are the source of truth; `index.sqlite` can be deleted and rebuilt
 
 ```sh
 npm run ci        # typecheck, unit/golden tests, and standalone proof; matches GitHub CI
-npm run build     # dist/cli.js (the xingular-harness command) and dist/terminal-pi.js
+npm run build     # dist/cli.js, dist/terminal-pi.js, and the OpenTUI frontend
+npm run build:tui # only the OpenTUI frontend
 ```
 
-Node 22.19 or newer.
+Node 22.19 or newer and Bun 1.3.14 or newer.
 
 ## Images
 
-`SessionRunInput.requiresImageInput` optionally requires a vision-capable resolved Pi model before a prompt is delivered. The check includes direct `images` input, and the generic tool wrapper rejects image results on text-only models. Direct prompt images use Pi's `{ type: 'image', data, mimeType }` content shape. Applications own file formats, attachment selection, extraction and image preparation; the Harness only transports typed image content and validates model capability.
+`SessionRunInput.requiresImageInput` optionally requires a vision-capable resolved Pi model before a prompt is delivered. The check includes direct `images` input, and the generic tool wrapper rejects image results on text-only models. Direct prompt images use Pi's `{ type: 'image', data, mimeType }` content shape. Applications own attachment selection, extraction and image preparation; the Harness transports typed image content and validates model capability. In the standalone terminal, pasting Finder-copied HEIC/HEIF files on macOS converts them to temporary PNGs so Pi can read their pixels. See [the terminal guide](docs/terminal-tui.md#clipboard-image-paste).
+
+`SessionRunInput.initialBashCommand` is an opt-in for one new interactive user turn. It must match
+the leading `!` command in `text`; Harness checks it through the same per-call gate as model-issued
+Bash, executes it once in Pi's native session, records its bounded result, and asks the model to
+inspect that result before replying. Automatic, plan, resumed, relation, probe, and improver runs
+cannot carry it. See the [terminal guide](docs/terminal-tui.md#bash-command-mode).
 
 ## Curated Hub
 
-`xingular-harness hub list [--refresh]`, `hub show publisher/name@version`, and
+`xagent hub list [--refresh]`, `xagent hub show publisher/name@version`, and
 `hub install publisher/name@version` browse and install exact catalog versions. `/hub` offers the
 same review in the interactive terminal, using its private control key for installation. Both the
-terminal and embedding applications use `hub.list`, `hub.get`, `hub.install`, and `hub.readDocument`.
-`hub.get { id, version, preview: true }` verifies data payload bytes without installing them.
+terminal and embedding applications use `hub.list`, `hub.get`, `hub.preview`, `hub.install`,
+`hub.uninstall`, and `hub.readDocument`. `hub.get { id, version, preview: true }` verifies data
+payload bytes without installing them. `hub.preview { id, version, offset }` returns bounded,
+UTF-8-safe pages of up to 16 KiB from a verified payload.
 
 Registry bundles import complete skills or single Markdown prompts/rules, disabled. Pi packages
 reuse the existing installer and require an exact npm version or full GitHub commit. Documents
 are saved as inert JSON for a compatible host to interpret; the harness does not apply them.
 Installation grants no attachment, trust, credentials, or permission. Writes are serialized and
-existing registry files are never overwritten.
+existing registry files are never overwritten. Receipts report whether their resources are intact;
+uninstall removes only the exact receipt's resources, including local edits within those paths, and
+revokes its attachment choices.
 
 Installed documents and provenance live under `<data root>/hub/`; the catalog cache is
 `<state dir>/hub/catalog.json`. An offline snapshot ships with the package. Explicit refresh keeps
@@ -358,9 +484,36 @@ An embedding application may set `externalMaintenance: true`, supply trusted `Ca
 `vaultAccess` (`self` or `curator`), and register `maintenanceTools`/`MAINTENANCE_PLUGIN`.
 Self callers directly edit only their own writable persona/notes; shared knowledge and text-resource
 writes become persistent proposals. Curator tools read original evidence, compare captured target
-revisions, apply reviewed changes, persist receipts and undo without overwriting later edits.
+revisions, read all host-assigned requests together, and apply reconciled Wiki proposals as one
+undoable change set. Resource proposals keep their own receipts; executable proposals remain inert
+until the user reviews/trusts them. Later user edits are never overwritten.
 `maintenance.list`, `maintenance.review` and `maintenance.retry` let the host dispatch its own
 recorded sessions. Curator runs do not recursively queue maintenance. Optional assigned IDs freeze
 which requests a batch may claim. These fields are trusted host context, never model arguments.
-Executable proposals remain inert until the user reviews/trusts them. Standalone callers that omit
-this option retain the existing lifecycle and direct-write contract.
+`maintenance_read_batch` reads those assigned requests together; `maintenance_apply_batch` records
+one decision for each and applies the evidence-checked Wiki set atomically. Standalone callers that
+omit this option retain the existing lifecycle and direct-write contract.
+
+## Readiness diagnostics
+
+Use `/plugin:doctor` in the terminal for local readiness checks and explicitly selected live probes. The same
+structured jobs are available through `harness.doctor` and `doctor.*` server methods. See
+[Doctor](docs/doctor.md) for coverage, consent, isolation, and provider callbacks.
+
+## Public 4.0.0 release candidate
+
+The public package is ESM: import from `@xingular/harness` or supported subpaths such as
+`@xingular/harness/variant/seed`. JavaScript and declarations are shipped in `dist/sdk`; a
+TypeScript loader is not required. Node 22.19 or later is required. The interactive terminal
+also requires Bun (release builds use 1.4.2); the CLI reports its version with `xagent --version`.
+Original project code is Apache-2.0. See LICENSE, NOTICE.md and THIRD_PARTY_LICENSES.md.
+
+A host providing its own browser tools sets `browser: false` on `createHarness` to disable the
+generic backend and prevent tool-name collisions. The desktop App uses this for shared tabs.
+The default standalone Harness keeps its isolated browser backend enabled.
+
+This additive release follows the published 1.0.0 baseline, which intentionally reset development
+numbering while preserving older published versions. See [4.0.0 release notes](docs/releases/4.0.0.md),
+[1.0.0 release notes](docs/releases/1.0.0.md), and the [release procedure](docs/releases/README.md).
+Publication requires registry verification, green CI on supported operating systems, and approval of
+the exact candidate and tag push.