@xingular/harness 0.1.7 → 1.0.0

package/docs/experiments/EXP-0001-terminal-input-latency/results.md

@@ -0,0 +1,46 @@
+# EXP-0001 — Results
+
+- **Status:** completed on one local machine; slower-computer validation remains open.
+- **Run date:** 2026-10-20.
+- **Code:** base commit `24a9390` plus the shared, uncommitted worktree. Baseline and treatment
+  used the same profiler and workload; only the draft synchronization implementation differed.
+- **Runtime:** Node v26.8.2, Vitest 4.1.11, macOS arm64, Apple M2, 8 CPU cores.
+- **Workload:** 520 keys; 4 ms inter-key timer; 8 ms mocked draft reply; full TUI layout rendered per
+  key at 120 by 40, with terminal output intercepted. Separate local socket sample: 120 requests.
+
+| Variant | Draft RPCs | Draft queue drain | Total sequence | Full TUI frame p50/p95 | Input plus frame p50/p95 |
+|---|---:|---:|---:|---:|---:|
+| Serialized baseline | 520 | 1,101.67 ms | 4,557.45 ms | 1.975 / 3.402 ms | 2.145 / 3.605 ms |
+| Latest-state treatment | 401 | 11.63 ms | 3,440.87 ms | 1.953 / 3.199 ms | 2.155 / 3.410 ms |
+
+The treatment reduced draft requests by 22.9%, queue drain by 98.9%, and total sequence time by
+24.5%. Full-frame p95 was 6.0% lower and combined input/frame p95 was 5.4% lower in these single
+runs; the p50 frame time was effectively unchanged. The small p95 differences are directional only
+because there was one 520-key run per variant.
+
+The separately measured local socket p95 was 0.122 ms for the baseline and 0.118 ms for treatment.
+Editor-only input/render p95 was 0.157 ms and 0.161 ms respectively. These numbers indicate that
+the editor itself was inexpensive on this machine; the treatment mainly prevents request backlog
+when replies take longer than normal.
+
+## Uncertainty, failures and limits
+
+The mocked 8 ms response is about 65 times the measured 0.12 ms local socket p95, so the queue
+improvement is strongest evidence for slow-reply conditions. The profile does not observe physical
+terminal paint and was not run on the reported slower computer. That computer must run the profile
+before claiming the user's lag is fixed there.
+
+The focused Harness terminal/editor suites passed: 52 passed, 4 skipped. The opt-in profile passed
+all three profile tests. The full Harness suite had 611 passing tests and one failure in the existing
+untracked `src/terminal/tui/treeModel.test.ts` search expectation; Harness typecheck also reports
+two errors in the existing untracked `treePicker` files. Neither failure is in the changed files.
+
+Sibling App layer/UI checks, sidecar tests and Rust tests passed. App typecheck and root tests still
+fail on existing Guide fixture/content mismatches in the shared App worktree.
+
+## Conclusion
+
+The hypothesis is supported for backlog under slow draft replies: coalescing cuts queued updates
+and drain time without changing measured frame performance or the focused behavior tests. Whether
+this resolves the reported slow-computer typing lag is inconclusive until the profile is run there
+and the result is checked against interactive use.

package/docs/experiments/EXP-0002-opentui-typing-latency/plan.md

@@ -0,0 +1,70 @@
+---
+id: EXP-0002
+title: OpenTUI terminal typing latency against pure Pi and opencode
+status: completed
+created: 2026-10-21
+updated: 2026-10-21
+related: [EXP-0001, ADR-0006]
+---
+
+# EXP-0002 — OpenTUI terminal typing latency
+
+## Question and falsifiable hypothesis
+
+Why does typing in the Harness terminal feel slow, and do targeted frontend changes bring its
+keystroke-to-screen latency and CPU use in line with pure Pi and opencode while idle, after a long
+history, and while a reply streams?
+
+Hypotheses, from code review before measuring: (1) the renderer's continuous mode makes every key
+wait for a frame tick; (2) every change rebuilds the whole view and the Solid tree, and a streamed
+delta recreates the reply's markdown renderable; (3) each runtime event publishes synchronously, with
+no coalescing; (4) per-request socket connections add steady CPU. EXP-0001 measured the old Pi
+frontend, which ADR-0006 removed, so it says nothing about this frontend.
+
+## Targets and controls
+
+- **Xingular Harness:** `node dist/cli.js` with isolated `--state` and `--data`, an API-key account,
+  and the loopback model in the account's shared `models.json`.
+- **Pure Pi:** `@earendil-works/pi-coding-agent` 1.2.0 `dist/bundle/cli.js` with an isolated
+  `PI_CODING_AGENT_DIR` (never `~/.pi`).
+- **opencode:** v2.1.0, `--standalone`, isolated XDG folders and an `OPENCODE_CONFIG` that points an
+  `@ai-sdk/openai-compatible` provider at the loopback model.
+- **Fixed:** 160 by 45 PTY, `TERM=xterm-256color`, `COLORTERM=truecolor`; four rounds of 60 keys
+  from `zqxjkvwy` (never produced by the replies) at 35 ms; the first 8 keys of a round are not
+  scored; the loopback server answers all three targets identically.
+
+## Scenarios
+
+- **idle:** a fresh session, nothing running.
+- **history:** after the model has looped 80 `read` tool calls (about 240 messages).
+- **stream:** three rounds typed while a reply streams 60 markdown chunks per second for 30 s, with
+  headings and code blocks. In a full run this follows `history`, so it streams over a long session.
+- **approval / question** (Harness only): typing while a tool approval, then an `ask_user` question,
+  waits above the composer.
+- **real:** `--real` runs `stream` with each tool's own login; for Harness, the Codex account on
+  `openai-codex` / `gpt-6-luna`.
+
+## Metric and measurement
+
+Latency is the time from writing a key to the PTY until the typed prefix ending at that key is
+visible on a pyte virtual screen (nearest-rank p50/p95/p99, max). CPU is the tree's CPU time from
+`ps` over the typing window. Bytes per key is PTY output divided by keys. Hot paths were found with
+`bun --cpu-prof --cpu-prof-md` through `XINGULAR_HARNESS_BUN`.
+
+The metric includes the frontend, the PTY and pyte parsing; it does not include a terminal emulator's
+paint. A key that never appears (dropped) is stamped when later text shows, so dropped keys appear
+as very large latencies rather than as misses.
+
+## Success criteria
+
+Harness p95 at or below opencode's and within 1.5 times pure Pi's in every scenario, idle latency
+that does not grow with history, and streaming CPU no higher than opencode's.
+
+## Reproduction
+
+```sh
+npm run build
+python3 scripts/profile-terminal-latency.py --targets xingular,pi,opencode --output <dir>
+python3 scripts/profile-terminal-latency.py --targets xingular --scenarios question --output <dir>
+python3 scripts/profile-terminal-latency.py --real --targets xingular --setup /model '\r' gpt-6-luna '\r' --output <dir>
+```

package/docs/experiments/EXP-0002-opentui-typing-latency/results.md

@@ -0,0 +1,92 @@
+# EXP-0002 — Results
+
+- **Status:** completed on one machine; not yet repeated on a slower computer.
+- **Run date:** 2026-10-21.
+- **Code:** base commit `24a9390` on `harness2` plus the shared, uncommitted worktree (another session
+  was editing the same frontend in parallel; every run used the tree as built at that moment).
+- **Runtime:** macOS arm64, Apple M2, 8 cores; Node v26.8.2; Bun 1.4.2; OpenTUI 0.6.6; Pi 1.2.0;
+  opencode 2.1.0; pyte for the virtual screen.
+
+All latencies in ms, keystroke to visible on screen, p50 / p95 (p99 where it matters). Lower is better.
+
+## Final comparison (loopback model, identical replies)
+
+| Scenario | Xingular before | Xingular after | Pure Pi | opencode `--standalone` |
+|---|---:|---:|---:|---:|
+| idle | 13.1 / 19.2 | 5.1 / 10.1 | 3.9 / 6.2 | 7.5 / 10.9 |
+| history (≈240 messages) | 13.2 / 20.3 | 5.2 / 10.6 | 5.1 / 10.4 | 9.8 / 13.1 |
+| stream over history | 13.3 / 23.7 | 8.1 / 23.5 (p99 26.5) | 3.1 / 22.2 (p99 29.4) | 9.1 / 28.0 (p99 33.2) |
+| CPU while streaming | 73.3% | 15.0% | 14.3% | 36.3% |
+| CPU at rest, nothing typed | — | 2.5% | 0.0% | 3.4% |
+
+Harness-only scenarios:
+
+| Scenario | Before | After |
+|---|---:|---:|
+| typing into a tool-approval dialog during a run | 20.3 / 36.2 | 7.6 / 13.7 |
+| typing while an `ask_user` question waits | 5.7 / 1,154.5 (max 1,402) — keys dropped | 5.0 / 12.9 (max 74) |
+
+Real model (each tool's own login, `stream` scenario, three rounds while the reply streams):
+
+| Target | Model | p50 / p95 / p99 / max | CPU |
+|---|---|---:|---:|
+| Xingular, after | Codex account, `openai-codex` / `gpt-6-luna` | 6.2 / 12.9 / 32.5 / 48.1 | 15.2% |
+| opencode | its own login, MiniMax M3.1 Flash Free | 11.6 / 24.8 / 30.8 / 40.5 | 33.6% |
+
+Pure Pi was not run with real credentials: its only real logins are OAuth accounts whose refresh
+tokens rotate, and copying them into a second client could sign the Harness account out.
+
+## What each change did
+
+Full-run rows stream on top of `history`; the "stream only" rows start fresh and are compared only
+with each other.
+
+| Step | idle | history | stream | stream CPU |
+|---|---:|---:|---:|---:|
+| Baseline | 13.1 / 19.2 | 13.2 / 20.3 | 13.3 / 23.7 | 73.3% |
+| 1. Render on demand (no `renderer.start()`) | 4.9 / 9.0 | 7.2 / 8.5 | 16.5 / 26.3 | 72.2% |
+| 2. Store + `reconcile` by id, `<markdown streaming>`, coalesced `change()` at 16 ms | 4.8 / 8.8 | 4.7 / 9.1 | 18.0 / 28.1 | 30.2% |
+| stream only: 2 + publish at 33 ms | | | 19.4 / 28.1 | |
+| stream only: 2 + `maxFps: 120` | | | 13.6 / 20.0 | |
+| stream only: 2 + both | | | 7.7 / 20.0 | |
+| 3. 33 ms only while running, `maxFps: 120` | 4.8 / 9.7 | 4.8 / 9.0 | 10.0 / 24.0 (p99 34.7, max 45.0) | 25.0% |
+| 4. Socket keep-alive, statistics cache, per-message transcript cache | 4.9 / 6.0 | 4.7 / 6.1 | 6.0 / 19.2 (p99 23.3) | 14.9% |
+| 5. Input publishes at once, draft read at key time, dock reply fix | 5.1 / 10.1 | 5.2 / 10.6 | 8.1 / 23.5 (p99 26.5) | 15.0% |
+
+The CPU profile of the baseline stream (Bun `--cpu-prof`) attributed 34% of samples to `change()` →
+Solid updates, 18% to re-highlighting text (`startHighlight` → `setStyledText`), about 12% to
+destroying and recreating renderables, about 30% to native painting, and 16% to socket requests:
+two 100 ms polls and every draft update each opened a new Unix-socket connection.
+
+Step 5 fixed correctness problems found while measuring, at no material latency cost:
+
+- **Dropped keys:** while a question waited, letters the dock did not use reached nothing, so typing
+  showed only after an `x` happened to collapse the dock. They now move focus to the composer.
+- **Stale draft on Enter:** OpenTUI reports composer text in a microtask after all keys of one input
+  chunk. Keys and Enter arriving together (a busy machine, a paste ending in a newline) sent an empty
+  or truncated draft. The root now reads the composer before each key.
+- **Composer not cleared:** with coalesced publication, a send's cleared draft could be overwritten by
+  the composer's late report. Changes made while handling a key publish synchronously.
+
+An A/B of the per-key composer read gave idle p95 6.7 and 9.4 ms without it and 10.0 and 6.8 ms with
+it. Idle p95 alternates between about 7 and 10 ms from run to run: a key that lands within one
+120 Hz frame (8.3 ms) of the previous frame waits for it.
+
+## Against the success criteria
+
+- p95 at or below opencode's: met in every scenario (10.1 vs 10.9, 10.6 vs 13.1, 23.5 vs 28.0).
+- Within 1.5 times Pi's p95: met for history and stream; idle is 1.6 times in the final run and
+  1.1 times in step 4 and the A/B runs, inside the run-to-run spread above.
+- No growth with history: met (idle 5.1 / 10.1, history 5.2 / 10.6).
+- Streaming CPU no higher than opencode's: met (15.0% vs 36.3%).
+
+## Limits
+
+- One machine, one run per row; the spread of p95 between repeats is about 3–4 ms.
+- The metric includes PTY and pyte parsing but not a terminal emulator's paint.
+- The loopback stream is regular (60 chunks per second); real providers burst. The Luna run agrees
+  with the loopback figures at p50/p95.
+- `scripts/verify-terminal.py` still fails after `/settings` on a `Try "` placeholder from the
+  removed Pi frontend; that check predates this work (`verification.json` recorded `passed: false`
+  for OpenTUI on 2026-10-20). It now matches the rendered screen when pyte is installed, which fixed
+  the earlier false failure on "Keyboard controls".

package/docs/features/README.md

@@ -0,0 +1,20 @@
+# 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) |
+
+**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
+
+`xharness` 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/releases/1.0.0.md

@@ -0,0 +1,40 @@
+# Xingular Harness 1.0.0
+
+This release establishes @xingular/harness@1.0.0 as the stable baseline and retains the xharness
+command. It intentionally resets the earlier development numbering; historical tags and published
+versions remain unchanged. This document describes the candidate until registry publication is
+verified.
+
+## Included
+
+- Pi execution with isolated accounts, pinned models/capabilities, gated tools and recorded usage.
+- Foundation/variant architecture, validated c1–c8 variants, version history, continuation,
+  answer-free refinement and opt-in lessons.
+- Wiki notes, history/trajectory tools, MCP connectors, plugins, Hub installation and terminal UI.
+- Generic web search/fetch and isolated browser tools, plus account and backend diagnostics in
+  /doctor. Local inspection is the default; selected live probes require consent.
+- Compiled Node ESM SDK and TypeScript declarations, including supported subpath imports.
+- Apache-2.0 for original project code, with retained upstream attribution and license texts.
+
+## Installation and requirements
+
+Use `npm install --global @xingular/harness@1.0.0`, then `xharness`. Node 22.19 or later is required.
+The terminal additionally requires Bun; release CI uses Node 22.19.0 and Bun 1.4.2. Browser operation
+requires an installed compatible browser or a deliberately configured endpoint. Model credentials
+are configured inside an isolated Harness account.
+
+## Migration
+
+- SDK tree symbols/paths become variant symbols/paths: VariantChoice, seedVariant, variant/*.
+- Server harnesses.* methods become variants.*. Session/context inputs use variant; variant
+  snapshots use variant and materialisation returns files. Old method aliases are not provided.
+- Existing stored data is migrated without overwriting; historical run records remain readable.
+- Versions numerically above 1.0.0 will not receive this release through higher-major semver ranges.
+  Install the exact version or latest tag deliberately.
+
+## Diagnostics limitations
+
+Local readiness is not live connectivity. Doctor never signs in, switches accounts or repairs
+settings. Provider probes may incur charges. Computer input remains blocked when the embedding
+host cannot provide an isolated diagnostic surface. Runtime execution and compiled artifacts are
+validated independently from publication; see the release checklist for actual gate results.

package/docs/releases/README.md

@@ -0,0 +1,36 @@
+# Release procedure
+
+1. Review and commit completed Harness changes on release/1.0.0. Review App compatibility changes
+   separately. Preserve old tags and exclude outputs, external references and caches.
+2. Run npm run ci and the required App checks on unrestricted macOS/Linux runners. Install Bun
+   1.4.2 and use Node 22.19.0 for the release build. Do not waive failing checks.
+3. Run npm run release:pack. The unique output folder contains the candidate tarball, inventory,
+   SHA-256 checksum and npm integrity. Run npm run release:smoke -- <tarball> --terminal for a fresh
+   dependency installation and packaged SDK/server/terminal checks. --offline reuses the checkout's
+   installed dependency tree and is only a local smoke check, not fresh-install acceptance.
+4. Run npm run release:preflight. Verify npm scope ownership and trusted-publisher settings for
+   tanntnny/xingular-harness, workflow release.yml, direct publishing enabled. No login is started
+   automatically. Existing 1.0.0 or an unreachable registry blocks publication.
+5. Present the exact commit, candidate inventory/hash, notes and check results for approval. Pushing
+   v1.0.0 triggers publication; do not push the tag before this approval. Preserve historical tags.
+6. After approval, push the reviewed commits and tag. The workflow runs both OS checks, packages
+   and tests one candidate, then publishes that same tarball with OIDC provenance and --tag latest.
+   No local publishing token is needed. It verifies registry integrity/provenance and creates a
+   GitHub release. Inspect registry state before retrying any failed publication.
+
+A published version cannot be replaced. Corrections require a later version. This package's
+intentional 1.0.0 reset does not rewrite historical decisions or claim an ordering above older
+2.x–5.x development versions. Publication status and local evidence belong in the candidate report.
+
+## Current preparation evidence
+
+Local package inspection and the offline-dependency consumer smoke check pass. App compatibility
+checks pass (592 renderer tests, 40 sidecar tests, 240 Rust tests with one ignored, and type/layer/UI
+checks). A focused Harness run has 100 passing tests and the standalone proof passes. The full
+Harness run is blocked by sandbox IPC and native HEIC encoding restrictions. The public GitHub
+repository and absence of a remote v1.0.0 tag were verified through the connected GitHub service.
+The npm registry and trusted-publisher settings could not be verified from this environment.
+
+The release branch must run unrestricted CI and a fresh-install smoke check before a release-tag
+approval is requested. Branch upload itself is a separate approval because it shares the source
+with GitHub and starts CI; it does not publish npm. No local test failure is waived by this note.

package/docs/study/00-index.md

@@ -0,0 +1,78 @@
+# Harness arm study — index
+
+An audit of agent-harness designs, arm by arm: where each studied harness puts its
+prompt assembly, tools, memory, subagents, skills, context management, refinement,
+governance, execution and observability, and what to adopt into this harness.
+
+Positioning: this is analysis, not checked source behavior. Living contract docs and
+decisions stay in `docs/`; when a study produces an actual change here, an ADR is
+written and the claim moves to checked behavior. Cite material as
+`external/<name>/<path>:<line>` — never second-hand summaries.
+
+## Focused notes
+
+- [`/btw` side-question comparison](btw-comparison.md) — this terminal, the App-owned
+  side question, and checked-out external implementations.
+- [Harness feature-gap review](feature-gap-review.md) — task/goal management, long-running work,
+  memory, execution isolation, verification, and observability gaps against the studied peers.
+
+## Sources
+
+Clones live in `external/` (this repo). Field notes in `sources/`.
+
+| Source | Origin | Note | Stage |
+|---|---|---|---|
+| opencode | [sst/opencode](https://github.com/sst/opencode) — TypeScript, the tool this harness family runs sessions in | [opencode.md](sources/opencode.md) | arm-01 audited |
+| pi / omp | [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi) — tuned fork of [pi-mono](https://github.com/badlogic/pi-mono), the session runtime underneath this harness | [omp.md](sources/omp.md) | arm-01 audited |
+| deepseek-harness (`dsh`) | [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — MIT, Cordis, "everything is a plugin" | [deepseek-harness.md](sources/deepseek-harness.md) | arm-01 audited |
+| harness2 | [google-research/harness2](https://github.com/google-research/harness2) + paper *Harness²: Recursive Agent Harnessing for an Open World* (arXiv:2610.14224, PDF in the clone) | [harness2.md](sources/harness2.md) | arm-01 audited |
+| swe-agent | [SWE-agent/SWE-agent](https://github.com/SWE-agent/SWE-agent) | [swe-agent.md](sources/swe-agent.md) | inventory |
+| openhands | [All-Hands-AI/OpenHands](https://github.com/All-Hands-AI/OpenHands) (UI) + [OpenHands/software-agent-sdk](https://github.com/OpenHands/software-agent-sdk) (agent server runtime) | [openhands.md](sources/openhands.md) | inventory |
+| kimi-cli | [MoonshotAI/Kimi-CLI](https://github.com/MoonshotAI/Kimi-CLI) | [kimi-cli.md](sources/kimi-cli.md) | inventory |
+| smolagents | [huggingface/smolagents](https://github.com/huggingface/smolagents) — CodeAct | [smolagents.md](sources/smolagents.md) | inventory |
+| claude-code | [Anthropic Claude Code](https://www.anthropic.com/claude-code) — not open source; audit npm bundle, published prompts, observed behavior | [claude-code.md](sources/claude-code.md) | no clone |
+
+## Arms
+
+One doc per arm: *design space → per-source comparison → trade-offs → adoption
+candidates*. Adoption candidates feed a two-tier roadmap: Tier 1 = patterns already
+battle-tested in open harnesses (OpenCode / pi / dsh); Tier 2 = research-backed ideas
+(harness² and the literature) attempted after Tier 1.
+
+| # | Arm | Doc | Stage |
+|---|---|---|---|
+| 1 | System prompt / context assembly | [arms/01-system-prompt.md](arms/01-system-prompt.md) | core four audited (opencode, omp, dsh, harness²); 5 sources pending |
+| 2 | Tools | [arms/02-tools.md](arms/02-tools.md) | core four audited (opencode, omp, dsh + harness²/swe-agent/smolagents in person); partial |
+| 4 | Subagents | [arms/03-subagents.md](arms/03-subagents.md) | core four audited; openhands/claude-code pending |
+| 5 | Skills & loading | [arms/04-skills.md](arms/04-skills.md) | three sources audited (dsh, opencode, harness²) + our tree; omp partial |
+| 6 | Context management | [arms/05-context-management.md](arms/05-context-management.md) | core three audited; ours needs inventory |
+| 3 | Memory | [arms/06-memory.md](arms/06-memory.md) | core four audited + our Wiki |
+| 8 | Governance | [arms/07-governance.md](arms/07-governance.md) | core three audited; claude-code/openhands pending |
+| 9 | Execution | [arms/08-execution.md](arms/08-execution.md) | core three audited; hands pending |
+| 10 | Observability | [arms/09-observability.md](arms/09-observability.md) | core three audited; hands pending |
+| 7 | Refinement / self-improvement | [arms/10-refinement.md](arms/10-refinement.md) | **done in person — port confirmed**; judge delta + drift sync open |
+
+Wide comparison: [arms/00-matrix.md](arms/00-matrix.md). Standing conclusions:
+[insights.md](insights.md). Roadmap: [roadmap.md](roadmap.md).
+
+## Work order
+
+1. `sources/` inventories (all nine), then arms 01–02 (prompt, tools)
+2. Arms 03–06 (subagents, skills, context management, memory)
+3. Arms 07–09 (governance, execution, observability)
+4. Arm 10 (refinement ⭐ — the merge study against harness²) + `roadmap.md`
+5. `arms/00-matrix.md` last, from the finished arm docs
+
+## Method rules
+
+- **Ground truth first.** Read the code before forming a position; every claim in an
+  arm doc needs at least one `path:line` citation per source, or an explicit
+  "unverified".
+- **Describe, then judge.** The comparison table states what each harness does; the
+  trade-off section says why; only `adoption candidates` mentions this harness.
+- **Respect the boundary.** Nothing here changes `src/`; study docs name no product
+  concept that the harness would learn. Adoption goes through the extension-point
+  flow later.
+- **The anchor arms are the seven surfaces.** Prompt sections, tool providers,
+  `ToolPolicy`, `SecretStore`, `Directory`, plugin descriptions, `RefineHost` — map
+  foreign mechanisms onto these without inventing application concepts.