@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/experiments/EXP-0003-performance-audit/plan.md

@@ -0,0 +1,109 @@
+---
+id: EXP-0003
+title: Layered Xingular terminal and Harness runtime performance audit
+status: completed
+created: 2026-10-25
+updated: 2026-10-25
+related: [EXP-0002]
+---
+
+# EXP-0003 — Layered performance audit
+
+## Question and falsifiable hypothesis
+
+How much of the user-visible delay belongs to terminal input/rendering, fresh-process startup, and
+Harness session orchestration? After the OpenTUI work in EXP-0002, the hypothesis is that steady
+keystroke-to-screen latency is comparable to Pi and OpenCode, while the Harness layers show up more
+strongly in cold startup and memory. A long transcript should not materially increase Harness input
+latency.
+
+The comparison can falsify this: if Harness p95 grows after history, stays above OpenCode during
+streaming, or Harness session calls contribute large repeatable latency with the injected session,
+those are separate regression candidates.
+
+## Targets and controls
+
+- **Xingular Harness:** built `node dist/cli.js`, with temporary `--state` and `--data` roots, an
+  isolated API-key account, and a loopback OpenAI-compatible model.
+- **Pure Pi:** `@earendil-works/pi-coding-agent` 1.2.0 with an isolated `PI_CODING_AGENT_DIR`.
+- **OpenCode:** v2.1.4 with `--standalone`, isolated XDG roots and a loopback-compatible provider.
+- Each terminal target runs in its own PTY and temporary profile. A local deterministic SSE provider
+  supplies the same fixture response to all targets. No external provider, OAuth profile, or
+  credential is used.
+- Main terminal runs use a 160×45 PTY, 35 ms key interval, two rounds of 30 typed characters and
+  five independent launches for idle, stream and burst. The first eight keys in each round are
+  excluded from latency scoring; each idle run therefore scores 44 keys and each stream/burst run
+  scores 22. Target order rotates between repeats.
+- History uses three launches per target. Each history is an 80-turn local tool loop (about 240
+  transcript messages) before typing is measured. The question scenario is Harness-only and uses
+  plan mode. A separate 80×24 run checks a compact terminal once per target; it is sensitivity data,
+  not a repeated comparison.
+- The runtime benchmark runs in a separate Node process with temporary state/data and a deterministic
+  injected session. It measures SDK import, Harness initialization, cold/warm `terminal.prepare`,
+  run-to-first-persisted-delta/completion, and one local tool-event path. It does not start Bun or a
+  real model.
+
+## Metrics
+
+- Input latency is the time between writing a key to the PTY and the first time its typed prefix is
+  visible on a `pyte` virtual screen (p50/p95/p99/max). Missed keys are reported separately. This
+  includes the PTY and `pyte` parser, not a terminal emulator's physical paint.
+- Startup is measured from process launch to first output, first nonblank visible screen, and a
+  quiet screen (750 ms with no further output). Process-tree RSS is sampled at that initial stable
+  screen. CPU and RSS are process-tree measurements; typing CPU is measured over the typing window.
+- Terminal comparison summaries take the median of each run's metric (including each run's p95); they
+  are not pooled per-key percentiles. Session-runtime summaries use the median of measured samples.
+- No credentialed run is required. The profiler rejects `--real` unless it is exactly one Xingular
+  run; this audit does not invoke `--real`.
+
+## Reproduction
+
+Build the CLI and create an isolated Python environment for the PTY screen parser:
+
+```sh
+npm run build
+python3 -m venv /tmp/harness-perf-venv
+/tmp/harness-perf-venv/bin/python -m pip install -r scripts/requirements-performance.txt
+```
+
+Main repeated comparison:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 5 --scenarios idle,stream,burst \
+  --rounds 2 --length 30 --interval 0.035 --width 160 --height 45 \
+  --warm-idle-seconds 2 --idle-seconds 2 --stream-seconds 4 \
+  --output /tmp/harness-perf-wide
+```
+
+History and compact-terminal sensitivity runs:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 3 --scenarios history \
+  --rounds 2 --length 30 --interval 0.035 --width 160 --height 45 \
+  --warm-idle-seconds 1 --idle-seconds 1 --stream-seconds 2 \
+  --output /tmp/harness-perf-history
+
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 1 --scenarios idle,stream,burst \
+  --rounds 2 --length 30 --interval 0.035 --width 80 --height 24 \
+  --warm-idle-seconds 2 --idle-seconds 1 --stream-seconds 4 \
+  --output /tmp/harness-perf-compact
+```
+
+Harness-only question latency and deterministic runtime overhead:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular --repeats 1 --scenarios question --rounds 2 --length 30 \
+  --width 160 --height 45 --warm-idle-seconds 1 --idle-seconds 1 \
+  --stream-seconds 3 --output /tmp/harness-perf-question
+
+npm run profile:session-runtime -- --iterations 5 --warmup 1 \
+  --output /tmp/harness-session-runtime.json
+```
+
+For terminal behavior verification, run `python scripts/verify-terminal.py` with the same Python
+environment. `npm run profile:terminal-input` measures the local draft-control socket separately;
+it is not a substitute for the PTY latency run.

package/docs/experiments/EXP-0003-performance-audit/results.md

@@ -0,0 +1,151 @@
+# EXP-0003 — Results
+
+- **Status:** audit completed; one terminal behavior verification check failed (details below).
+- **Run date:** 2026-10-25.
+- **Code:** base commit `6f72a07` with a dirty worktree (81 changed/untracked paths were present).
+  Product changes in that worktree predate this audit; this audit added benchmark tooling and report
+  artifacts only.
+- **Machine/runtime:** macOS 27.0, arm64, 8 logical CPUs; Node v26.8.2; Bun 1.4.2; Harness
+  1.1.1; Pi 1.2.0; OpenCode v2.1.4; Python 3.12.12; pyte 0.8.2.
+- **Credentials/network:** terminal comparisons used a loopback model in isolated temporary
+  profiles. The session-runtime benchmark used an injected deterministic session. No provider,
+  OAuth credential, or user profile was used; `--real` was not run.
+
+Raw terminal and runtime JSON is in [`data/`](data/): `terminal-wide.json`,
+`terminal-history.json`, `terminal-compact.json`, `terminal-question.json`,
+`session-runtime.json`, and `session-runtime-replication.json`. The OpenCode executable field is
+normalized to `opencode` to avoid publishing a machine-specific path; measurements are unchanged.
+
+## Terminal comparison
+
+Main repeated comparison: 160×45 PTY, five launches per target, 2 rounds of 30 characters at 35 ms
+per key, 2 s warm-idle and 2 s idle measurement. The table shows the median of per-launch values;
+latency is milliseconds p50/p95 and CPU is process-tree CPU during the typing window. Every target
+had zero missed keys.
+
+| Scenario | Target | p50 / p95 (ms) | CPU (%) |
+|---|---|---:|---:|
+| Idle typing | Xingular | 5.11 / 9.98 | 7.7 |
+|  | Pure Pi | 5.32 / 6.39 | 3.1 |
+|  | OpenCode | 7.17 / 10.41 | 26.5 |
+| After ~240 transcript messages | Xingular | 5.09 / 10.05 | 8.9 |
+|  | Pure Pi | 5.44 / 10.34 | 4.3 |
+|  | OpenCode | 9.47 / 12.70 | 32.6 |
+| Regular stream | Xingular | 9.13 / 19.91 | 14.2 |
+|  | Pure Pi | 3.18 / 22.26 | 10.5 |
+|  | OpenCode | 10.02 / 24.87 | 41.5 |
+| Burst stream | Xingular | 5.01 / 10.73 | 12.3 |
+|  | Pure Pi | 4.72 / 6.31 | 5.5 |
+|  | OpenCode | 10.42 / 21.85 | 33.2 |
+
+History setup took a median 7.5 s for Xingular, 6.5 s for Pi, and 9.8 s for OpenCode. Xingular's
+idle p95 was 9.98 ms before history and 10.05 ms after it, so this run found no meaningful
+history-related typing regression. The median streaming p95 was lower than both comparisons; burst
+p95 was below OpenCode but above Pi. Xingular idle p95 was roughly on par with OpenCode and 1.56×
+Pure Pi; burst p95 was 1.70× Pure Pi. Thus the prior EXP-0002 p95 criterion of “no worse than
+OpenCode” held for these four scenarios, while “within 1.5× Pi” did not hold for idle or burst.
+
+The five-run p95 ranges show why the medians should not be read as precise rankings: idle ranges
+were 9.64–10.19 ms (Xingular), 6.04–9.92 ms (Pi), and 9.58–11.08 ms (OpenCode); stream ranges
+were 18.32–20.25, 22.02–23.38, and 19.00–26.36 ms; burst ranges were 8.87–12.08, 5.81–33.23,
+and 12.86–26.00 ms respectively. Each run scores 44 idle keys and 22 stream/burst keys; p95 values
+are medians of per-run p95, not pooled per-key percentiles.
+
+### Fresh launch and memory
+
+`first visible` is the first nonblank PTY screen; `stable screen` is measured after 750 ms without
+output. Process-tree RSS is sampled at that initial stable screen.
+
+| Target | First visible (ms) | Stable screen (ms) | Process-tree RSS (MiB) |
+|---|---:|---:|---:|
+| Xingular | 2,814 | 3,768 | 392 |
+| Pure Pi | 261 | 1,035 | 134 |
+| OpenCode | 304 | 1,107 | 489 |
+
+On this machine, Xingular's end-to-end first-visible time was about 10.8× Pi and 9.3× OpenCode;
+its process-tree RSS was about 2.9× Pi and 0.8× OpenCode. This launch comparison includes the
+Harness CLI and its terminal child, while Pi and OpenCode have different process architectures. It
+measures the user-visible path, not the renderer alone. A separate 80×24 single-run sensitivity
+check showed idle p95 of 4.66/5.08/8.11 ms and stream p95 of 10.95/5.72/18.61 ms for
+Xingular/Pi/OpenCode respectively; it supports the same broad pattern but is not a repeated result.
+
+The Harness-only plan-question scenario passed after the profiler was changed to enter plan mode:
+44 keys, no misses, p50 5.03 ms, p95 9.53 ms (one run; not a cross-target comparison). The raw
+record is `data/terminal-question.json`.
+
+A separate 2 s post-warm-up idle-resource window in the wide run measured median process-tree CPU
+of 2.0% for Xingular, 0.5% for Pi, and 1.5% for OpenCode. These short windows are coarse and should
+not be treated as a stable ranking.
+
+## Harness runtime overhead
+
+Two invocations of the isolated runtime benchmark contributed ten measured samples per warm
+operation (five iterations and one warmup per invocation). It imports the built SDK and uses a fake
+session seam; these values exclude model/provider latency and real Pi startup.
+
+| Operation | Median | Sample range |
+|---|---:|---:|
+| Warm `terminal.prepare` | 9.65 ms | 7.69–11.78 ms |
+| `sessions.run` to first persisted delta | 25.65 ms | 21.78–29.44 ms |
+| `sessions.run` to completion | 33.86 ms | 27.96–39.06 ms |
+| Tool run to `tool.started` | 29.12 ms | 25.74–31.92 ms |
+| Tool run to `tool.completed` | 29.50 ms | 26.12–47.31 ms |
+| Tool run to completion | 38.96 ms | 37.07–58.24 ms |
+
+Across the two process starts, SDK import was 246–347 ms and Harness initialization was 27.8–28.5
+ms. Cold `terminal.prepare` varied substantially, from 261 to 1,158 ms; its description includes
+first socket-listener setup. Treat the warm path as the repeatable figure and cold preparation as a
+signal to instrument further, not as a stable estimate. Every run verified the persisted event
+sequence; the temporary state/data roots were removed.
+
+## CPU profile notes
+
+Profiles were captured separately from the comparison runs and are not included in their latency
+medians. A one-run Bun profile of Xingular during startup and streaming (16.19 s, 846 samples) had
+highest self-time in terminal output writing (`writeBuffered` 14.0%, Node `_write` 9.3%), key
+matching (`matchesKey` 5.6%), OpenTUI stdout draining (4.5%), and the terminal socket `send` (3.2%).
+This identifies output/key/event plumbing worth inspecting, but does not isolate one application
+function as the cause of input latency.
+
+A separate one-run Node profile of the Harness process (6.98 s, 5,576 samples) was 69% idle in the
+profiler, with `spawnSync` at 11.2% and `readdir` at 3.2%. This is consistent with a startup path
+that includes process and I/O waits rather than being dominated by one CPU-heavy JavaScript loop;
+it is not a phase-by-phase startup trace. Profiles are diagnostic single runs and profiling itself
+adds overhead.
+
+## Verification
+
+- `npm run typecheck` — passed.
+- `npm test` — passed: 150 test files, 1,140 tests passed, 3 skipped.
+- `npm run build` — passed.
+- `npm run prove` — passed all 15 standalone proof cases.
+- `npm run profile:terminal-input` — passed; 120 local draft-control socket requests, p50 0.022 ms,
+  p95 0.053 ms. This measures the socket path, not key-to-screen rendering.
+- `profile-terminal-latency.py --real --targets pi` — rejected before launch as intended; `--real`
+  is restricted to one Xingular run.
+- `python scripts/verify-terminal.py` — **failed** during `/settings` at a narrow terminal width.
+  The verifier expected `Esc close` on the last row; the observed footer was truncated to
+  `Enter change · type to search · Tab/`. This is a terminal behavior verification failure, not a
+  performance measurement. No product UI code was changed as part of this audit.
+
+## Conclusions and follow-up
+
+- **Steady typing:** competitive with OpenCode at 160×45, especially for streaming p95; history
+  does not increase Xingular's measured p95. Xingular still trails Pi on idle and burst p95, and
+  has higher CPU than Pi while typing/streaming.
+- **Fresh start:** the clearest gap. Xingular takes about 2.8 s to first visible output and uses
+  about 392 MiB at the initial screen. The runtime benchmark makes warm Harness preparation look
+  inexpensive, but cold preparation is variable. Break startup into Node CLI, Harness account and
+  context setup, terminal preparation, Bun launch, and first render before attributing or optimizing
+  the gap.
+- **Next measurements:** add phase markers for fresh startup and process-by-process RSS; repeat on a
+  slower machine; investigate burst input alongside `matchesKey`/output writes; and triage the
+  narrow `/settings` footer verification failure separately.
+
+## Limits
+
+One arm64 machine and a dirty worktree; no clean-commit A/B or slower-device run. The loopback stream
+is regular and excludes network/provider delay. PTY/pyte timing excludes physical terminal paint.
+The compact-screen and question results are single runs. CPU profiles are single instrumented runs.
+The runtime benchmark's session is injected and deterministic, so it measures Harness runtime and
+persistence costs, not real model inference or the complete Pi AgentSession startup path.

package/docs/features/README.md

@@ -0,0 +1,46 @@
+# Harness features
+
+The Harness is a reusable Pi runtime: its fixed foundation runs a configurable agent, records each
+run, and can use that evidence to propose improvements. These pages organize current capabilities
+by area.
+
+The feature guide is descriptive. The [architecture specification](../architecture/README.md) is
+binding and defines the contracts and invariants.
+
+| Area | Includes | Guide |
+|---|---|---|
+| Core runtime | Foundation, accounts, sessions and runs, prompt compilation, tool governance | [Cores](cores/README.md) |
+| Harness² | Harness Variants (HVs), recursive refinement, evidence-backed experience | [Google Harness²](google-harness2/README.md) |
+| Automations | Subagents, recovery, optional run reflections, plugin hooks | [Automations](automations/README.md) |
+| Memory | Wiki notes, run recall, trajectory search and reads | [Memory](memory/README.md) |
+| Integrations | Application extension points, plugins, connected apps and Hub | [Integrations](integrations/README.md) |
+| Interfaces | Node embedding, standalone terminal and JSON-lines server | [Interfaces](interfaces/README.md) |
+
+## Built-in plugin ownership
+
+PROP-0020 groups Harness-managed feature plugins by responsibility. These labels are an architecture
+taxonomy only; they are not runtime plugin categories or public metadata. Foundation-owned
+infrastructure remains the security and lifecycle boundary around each feature.
+
+| Category | Features |
+|---|---|
+| Foundation | Accounts, sessions, run recording, prompt/variant validation, gate, plugin loading/trust/attachments, resource browser, server and terminal framework |
+| World | Web tools, browser tools and page annotations; generic isolated browser engine stays in Foundation |
+| Memory | Wiki, history and trajectory |
+| Automation | Subagents, ask-user, checklist, lessons and refinement |
+| Integrations | Connected apps/MCP and Hub |
+| Operations | Doctor and worktrees |
+
+See [06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md#built-in-ownership-taxonomy-prop-0020) for the binding ownership boundary.
+
+## Planned: Agent Modes
+
+An **Agent Mode** selects one overall work style at a time; plugins remain stackable strategies and
+contributions. The first planned mode is **Router Agent Mode**: the user works through one continuous
+chat and browser experience with a router agent that proactively plans, delegates across persistent
+subagent threads, and receives their messages. This is a future direction, not an implemented
+capability. See [FW-0001](../future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode) for
+the backlog entry and required architecture decisions.
+
+**Harness Variant (HV)** is the short name used in these feature pages. The architecture
+specification uses the canonical term *variant*.

package/docs/features/automations/README.md

@@ -0,0 +1,41 @@
+# Automations
+
+The Harness includes bounded ways to coordinate or react to work. It supplies run-level mechanisms;
+the embedding application decides when to dispatch application work and owns schedules and broader
+orchestration.
+
+## Subagents
+
+An interactive run can spawn child runs and wait for their results. A child receives no wider
+capabilities than its parent, and the parent joins outstanding children before it completes. Nesting
+is bounded. The host can also spawn and wait for subagents through the Harness API.
+
+## Recovery and continuation
+
+The Harness records interrupted runs and exposes what was left unfinished. It never restarts model
+work automatically. The application chooses whether and when to continue an interrupted run; a
+continuation starts as a new run with the earlier account, variant version, and capability set pinned.
+
+## Optional run reflections
+
+The first-party `lessons` plugin is off by default. When enabled, a qualifying completed top-level
+run may trigger a bounded reflection that keeps a general lesson in the Wiki. Reflection runs with
+read-only file tools and cannot ask a person or act outside its allowed workspace.
+
+## Plugin hooks
+
+Trusted hooks can listen for supported events such as a saved Wiki page or an ended run. Hooks run
+after the event, cannot block or change the originating write, and have a time limit. They run only
+while their plugin is enabled and trusted.
+
+## Refinement is human-adopted
+
+Refinement is another multi-step workflow, described in [Google Harness²](../google-harness2/README.md).
+Its probes and improvers run unattended, but refinement never adopts a candidate by itself.
+
+## Further reading
+
+- [02 Sessions and runs](../../architecture/02-sessions-and-runs.md) — subagents, interruption, and continuation.
+- [05 Refinement](../../architecture/05-refinement.md) — isolated refinement executions.
+- [06 Plugins and capabilities](../../architecture/06-plugins-and-capabilities.md) — hooks and plugin trust.
+- [08 Memory and history](../../architecture/08-memory-and-history.md) — optional lessons behavior.

package/docs/features/cores/README.md

@@ -0,0 +1,39 @@
+# Core runtime
+
+The core is the Harness's reusable, fixed foundation for running one agent turn well. It controls
+the Pi session, compiles context, limits available tools, applies the call-by-call gate, and records
+what happened. Application-specific behavior enters through the [integration points](../integrations/README.md),
+not application-specific branches in the core.
+
+## Capabilities
+
+- **Isolated accounts** — Each session uses a pinned Pi account and its own account folder;
+  credentials are supplied through a secret store.
+- **Sessions and runs** — A session is a native Pi conversation; each run pins its account, variant
+  version, and capability set. Validated events are saved before they are relayed.
+- **Compiled context** — One compiler combines variant, Harness, and host sections, applies budgets,
+  and separates stable prompt text from changing context updates.
+- **Tool governance** — A frozen capability set controls which tools are registered. Every tool call
+  passes through the gate, which applies host policy, standing approvals, and—when needed—a person's
+  decision.
+- **Controlled resource loading** — The Harness chooses session resources and requires trust for
+  plugin code; plugins cannot bypass the final tool gate.
+
+## Foundation and Harness Variant
+
+The **foundation** is fixed: code and contracts such as session execution, the prompt compiler, run
+recording, account isolation, and the tool gate change through releases. A **Harness Variant (HV)**
+is the configurable behavior used by a scope. A run pins one validated HV version; it can shape the
+agent's instructions and resources, but cannot change the foundation. See [Google Harness²](../google-harness2/README.md)
+for its components and refinement process.
+
+The Harness provides the single-run runtime. Higher-level orchestration—such as application agents,
+tasks, scheduling, and UI—belongs to the embedding application.
+
+## Further reading
+
+- [00 Overview](../../architecture/00-overview.md) — foundation/variant split and module ownership.
+- [02 Sessions and runs](../../architecture/02-sessions-and-runs.md) — execution lifecycle and run records.
+- [04 Prompt](../../architecture/04-prompt.md) — compilation and delivery.
+- [07 Tools and the gate](../../architecture/07-tools-and-gate.md) — tool registration, permissions, and approvals.
+- [09 Accounts and connectors](../../architecture/09-accounts-and-connectors.md) — account isolation and secret handling.

package/docs/features/google-harness2/README.md

@@ -0,0 +1,52 @@
+# Google Harness²
+
+Harness² is the recursive-harnessing approach described in the [Harness² paper](https://arxiv.org/abs/2610.14224)
+(Apache-2.0, Google LLC). The Harness applies the idea to improve agent behavior while keeping
+model weights fixed: runs produce evidence, refinement proposes changes to a Harness Variant, and
+a person decides whether to adopt them.
+
+## Harness Variant (HV)
+
+**HV** is the short name for **Harness Variant**. An HV is a validated, versioned set of eight
+components for one scope. A run pins a version so its behavior does not change mid-run.
+
+| Component | What it controls |
+|---|---|
+| c1 — System prompt | Agent instructions |
+| c2 — Guardrails | Behavioral constraints |
+| c3 — Memory | Always-on memory guidance |
+| c4 — Tool guidance | Guidance for using available tools |
+| c5 — Subagents | Named subagent instructions |
+| c6 — Skills | On-demand skills and their scripts |
+| c7 — Scripts | On-demand scripts |
+| c8 — Plugins | Plugin extensions in the tool loop |
+
+An HV changes agent guidance and selected resources, not the foundation. It cannot change the prompt
+compiler, tool gate, run recorder, accounts, or trust rules. A candidate is not used until a person
+adopts it as the scope's head version.
+
+## The Propose–Probe–Compose loop
+
+1. Run the current HV on a task in isolated workspaces and capture evidence.
+2. Improver sessions propose edits to copies of the HV from two perspectives: **INV** (how the agent
+   works) and **DOM** (what a practitioner knows).
+3. Probe candidates, then compose behavior from observed contrasts.
+4. Select a final output blindly from anonymized candidates. Improvers and the selector never receive
+   scores, rubrics, or reviewer verdicts.
+5. Return a candidate for a person to adopt; refinement never updates the active HV by itself.
+
+Parallel mode explores more alternatives; sequential mode refines more deeply. Both follow the
+method's budget identity of **R = 4k executions** and **P = 3k improver sessions**.
+
+## Experience across tasks
+
+Each scope has an experience library containing adopted HVs and evidence-backed lessons about their
+edits. Future task improvers can consult that library. The library preserves the variants themselves
+rather than only summaries.
+
+## Further reading
+
+- [03 Variants](../../architecture/03-variants.md) — component surface, validation, versions, and trust.
+- [05 Refinement](../../architecture/05-refinement.md) — full method, evidence contract, budgets, and selection.
+- [ADR-0011](../../decisions/ADR-0011-foundation-and-variants.md) — the fixed-foundation/mutating-variant decision.
+- [Harness² paper](https://arxiv.org/abs/2610.14224).

package/docs/features/integrations/README.md

@@ -0,0 +1,40 @@
+# Integrations
+
+The Harness stays application-neutral. An embedding application contributes its own data and
+capabilities through generic extension points; plugins and connected apps are loaded and governed by
+the Harness.
+
+## Application extension points
+
+The Harness has seven extension points:
+
+1. **Prompt sections** — application context added to the compiled prompt.
+2. **Tool providers** — application tools offered to eligible sessions.
+3. **Tool policy** — per-call scope, authorization, approvals, and connector limits.
+4. **Secret store** — application-chosen credential storage.
+5. **Directory** — names for opaque application identifiers.
+6. **Plugin descriptions** — attribution for tools, sections, and groups supplied by a plugin.
+7. **RefineHost** — isolated workspaces, sessions, and deliverables for refinement.
+
+The server protocol provides equivalents for non-Node hosts except `RefineHost`, which is Node-only
+today.
+
+## Plugins and capabilities
+
+Plugins can contribute instructions, skills, commands, tools, connections, extension code, and themes.
+The Harness selects what loads, keeps capabilities scoped to callers, and requires trust for
+executable plugin code. Enabling a plugin does not by itself grant tool permission; calls still pass
+the gate.
+
+## Connected apps and Hub
+
+Connected apps use an MCP broker with scoped session access, approval for non-read calls, and
+redaction of stored traces. The Hub installs exact catalog versions of skills, prompts, rules, and
+Pi packages. Installation does not automatically enable, trust, or authorize the installed resources.
+
+## Further reading
+
+- [01 Extension points](../../architecture/01-extension-points.md) — the application-to-Harness contract.
+- [06 Plugins and capabilities](../../architecture/06-plugins-and-capabilities.md) — loading, trust, and frozen capability sets.
+- [07 Tools and the gate](../../architecture/07-tools-and-gate.md) — per-call authorization.
+- [09 Accounts and connectors](../../architecture/09-accounts-and-connectors.md) — secrets, connected apps, OAuth, and Hub.

package/docs/features/interfaces/README.md

@@ -0,0 +1,29 @@
+# Interfaces
+
+The same Harness runtime can be embedded by a Node application, hosted as a child process by another
+language, or used through its standalone terminal.
+
+## Node embedding
+
+A Node host constructs the package with `createHarness(...)`, supplies application-owned capabilities
+through the extension points, and uses its sessions, runs, accounts, variants, and other services
+directly. The [embedding guide](../../README.md#using-it-from-node) has a code example and API details.
+
+## Server protocol
+
+A non-Node host can run the Harness server and exchange newline-delimited JSON messages over stdin
+and stdout. The protocol exposes the Harness API, saved run events, state-change notices, and calls
+for host-provided extension points.
+
+## Standalone terminal
+
+`xagent` provides the Harness-owned OpenTUI terminal over a persistent Pi session. An embedding
+application may host the terminal in its own PTY; the Harness owns the terminal UI and session
+behavior, while the host owns PTY and process supervision.
+
+## Further reading
+
+- [01 Extension points](../../architecture/01-extension-points.md) — how an embedding application extends the Harness.
+- [10 Server protocol](../../architecture/10-server-protocol.md) — wire format and method contract.
+- [11 Terminal](../../architecture/11-terminal.md) — terminal ownership and runtime.
+- [Terminal guide](../../terminal-tui.md) — implementation details and verification evidence.

package/docs/features/memory/README.md

@@ -0,0 +1,28 @@
+# Memory and history
+
+The Harness keeps two kinds of information outside a run's prompt configuration: reference notes in
+the Wiki and evidence from earlier runs. Both are searchable; the run index is derived and rebuildable.
+
+## Wiki
+
+The Wiki stores linked, versioned Markdown notes for projects and shared knowledge. Notes are
+reference material, not instructions: they do not replace or modify a Harness Variant's guidance.
+Selected references may be delivered as changing context, but the Wiki itself is not an always-on
+prompt.
+
+## Run history and trajectories
+
+History supports scoped recall over earlier conversations. Trajectory tools search and read bounded
+pages of recorded run events, including context, tool calls, decisions, retries, and usage. Reads are
+redacted and report evidence; they do not score runs.
+
+## Lessons and the experience library
+
+The optional `lessons` plugin may turn a completed run into a general Wiki lesson; see
+[Automations](../automations/README.md). The [Harness² experience library](../google-harness2/README.md#experience-across-tasks)
+is separate: it stores adopted Harness Variants with evidence-backed lessons about their edits.
+
+## Further reading
+
+- [08 Memory and history](../../architecture/08-memory-and-history.md) — Wiki, recall, trajectories, and indexing.
+- [12 Storage](../../architecture/12-storage.md) — data root and state directory.

package/docs/future-work.md

@@ -0,0 +1,48 @@
+# Future feature backlog
+
+This backlog records candidate directions. An entry here does not change the binding architecture,
+approve implementation, or describe an available feature. A change to an architecture contract,
+invariant, layer boundary, extension point, or storage layout still requires a reviewed proposal.
+
+## FW-0001: Agent Modes, starting with Router Agent Mode
+
+**Status:** Candidate; future architecture proposal required before implementation.
+
+### Concept
+
+An **Agent Mode** selects one overall work style, with only one mode active at a time. Plugins remain
+stackable strategies and contributions that can be used within a mode; they do not select the
+agent's overall work style.
+
+The first planned mode is **Router Agent Mode**. The user interacts with one user-facing agent through
+one continuous chat and browser experience. That router proactively plans and delegates work across
+persistent subagent threads, receives their messages, and coordinates the overall work while the user
+can continue sending messages.
+
+### Intended ownership
+
+This is intended as a Harness foundation capability. The current architecture describes subagents as
+child runs and assigns persistent teams, broader orchestration, and the application's shared UI to
+the embedding application ([02 Sessions and runs](architecture/02-sessions-and-runs.md), [feature-gap
+review](study/feature-gap-review.md)). This backlog entry proposes revisiting that boundary; it does
+not change it.
+
+### Decisions required before a proposal
+
+- Define the mode selection scope and lifetime, including how one active mode applies to sessions,
+  runs, and child agents.
+- Define persistent subagent thread identity, history, communication, delegation, recovery, and
+  resource limits while preserving the run's account, variant, capability, and gate guarantees.
+- Define how the router receives worker messages and incorporates them while accepting continued
+  user input in one conversation.
+- Define how the single chat and browser experience maps to the Harness terminal, server protocol,
+  and embedding hosts, including which UI responsibilities remain with the host.
+- Identify the storage, run-event, and public API changes needed to support the mode and migrate or
+  coexist with current run-scoped subagents.
+
+### Next step
+
+When implementation is scheduled, write a formal architecture proposal from the proposal template,
+identify every affected contract and invariant, and obtain acceptance before changing code or binding
+specification pages. Record a lasting accepted architecture choice in an ADR. Until then, Agent Mode
+and Router Agent Mode are planning terms only; no runtime behavior or public interface is implied.