@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/README.md

@@ -0,0 +1,143 @@
+# Harness architecture specification
+
+**Status:** binding. **As of:** 2026-10-27, checked against `src/` on branch `release/1.0.0`.
+
+This folder is the core specification of `@xingular/harness`. Code must conform to it. A change
+that alters what it says must update the affected pages in the same change (see
+[Changing the architecture](#changing-the-architecture)). Proposals are optional design records,
+not prerequisites or approval gates.
+
+Other documents explain and record; this folder decides. Where another document disagrees with a
+page here, this page wins, and the disagreement is listed under [Known drift](#known-drift).
+
+## How to read it
+
+Each page describes one part of the harness in the same order:
+
+1. **Purpose** — what the part is for, in one paragraph.
+2. **Components** — the modules and their main types.
+3. **Contracts** — the public API, server methods and file formats other code relies on.
+4. **Invariants** — numbered rules (`INV-<AREA>-<n>`). Cite them by ID in reviews and proposals.
+5. **Data** — what the part stores, and where.
+6. **Source map** — the files that implement it.
+
+Types named in a page are declarations in `src/`. Where a page describes a logical role that is
+not one class (a set of functions in one module, say), it says so.
+
+## Pages
+
+| Page | Covers | Invariant prefix |
+|---|---|---|
+| [00 Overview](00-overview.md) | What the harness is, the foundation/variant split, layers, module map, ETCLOVG ownership | `INV-BND` |
+| [01 Extension points](01-extension-points.md) | The seven surfaces an application extends the harness through | `INV-EXT` |
+| [02 Sessions and runs](02-sessions-and-runs.md) | A session turn, run records and events, approvals, questions, subagents, plan mode, usage | `INV-RUN` |
+| [03 Variants](03-variants.md) | The eight components, validation, versions, pinning, plugin-code trust; the rule that only a variant mutates | `INV-VAR`, `INV-FND` |
+| [04 Prompt](04-prompt.md) | The compiler, the stable prefix, context updates | `INV-PRM` |
+| [05 Refinement](05-refinement.md) | Propose–Probe–Compose, evidence, budget, selection, the experience library | `INV-REF` |
+| [06 Plugins and capabilities](06-plugins-and-capabilities.md) | What a session loads, attachments, hooks, capability sets | `INV-PLG`, `INV-CAP` |
+| [07 Tools and the gate](07-tools-and-gate.md) | The harness's own tools, tool providers, the per-call gate, standing approvals | `INV-GATE` |
+| [08 Memory and history](08-memory-and-history.md) | Wiki notes, recall, trajectories, the rebuildable index | `INV-MEM` |
+| [09 Accounts and connectors](09-accounts-and-connectors.md) | Isolated accounts, secrets, connected apps (MCP), the Hub | `INV-ACC`, `INV-MCP` |
+| [10 Server protocol](10-server-protocol.md) | The newline-delimited JSON protocol and the method table | `INV-SRV` |
+| [11 Terminal](11-terminal.md) | The Harness-owned terminal frontend and its process boundary | `INV-TUI` |
+| [12 Storage](12-storage.md) | The data root and state directory, and who writes what | `INV-STO` |
+| [13 World tools](13-world-tools.md) | Generic web and isolated browser backends, host boundary and diagnostics | — |
+| [14 Surfaces and parity](14-surfaces-and-parity.md) | Every capability is a Harness capability with a terminal surface; host-backed capabilities; host-only surfaces | `INV-PAR` |
+| [15 Remote control](15-remote-control.md) | Continuing a terminal session from a phone or iPad: pairing, sealed frames, the bind policy | `INV-RC` |
+| [Proposals](proposals/README.md) | Architecture change proposals and their status | — |
+
+Related records, not binding by themselves:
+
+- [`../terminal-tui.md`](../terminal-tui.md): terminal detail and verification evidence. Page 11
+  states which parts of it are binding.
+- [`../system-prompt-design.md`](../system-prompt-design.md): a draft prompt design (DESIGN-0001).
+  Only what page 04 states is binding.
+- [`../decisions/`](../decisions/): accepted decisions (ADRs). Each binding consequence of an
+  accepted ADR is stated on a page here.
+- [`../../README.md`](../../README.md): the embedding guide for application authors.
+- [`../../../App/docs/architecture/overview.md`](../../../App/docs/architecture/overview.md): the
+  application side of the boundary.
+
+## Glossary
+
+These words are used the same way across architecture pages and, for implemented concepts, in code
+and the data layout. Terms marked as planned are future vocabulary only; they do not describe
+current behavior.
+
+| Word | Meaning |
+|---|---|
+| **Foundation** | The fixed half of the harness: code and invariants that no edit, improver or adoption can change. Changes by release; contract changes update the specification and may use an optional proposal as a design record. |
+| **Agent Mode** | A planned foundation-level work style, with at most one mode active at a time. Plugins remain independently stackable contributions. This is distinct from plan mode and existing `mode` fields; it is not a runtime contract ([FW-0001](../future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode)). |
+| **Variant** | The mutating half: one tree of eight components (c1–c8) for one scope. Formerly "harness tree". |
+| **Component** | One of c1–c8 inside a variant (system prompt, guardrails, memory, tool guidance, subagents, skills, scripts, plugins). |
+| **Surface** | The foundation's definition of what a variant may contain (`PI_SURFACE`): paths, patterns, the always-on cap. |
+| **Scope** | The opaque id a variant belongs to. The application decides what it stands for. |
+| **Version** | A recorded variant: immutable, validated, named by its fingerprint. |
+| **Head** | A scope's current variant: the version a new run pins. |
+| **Lineage** | The parent chain of a scope's versions. |
+| **Candidate** | A variant that refinement proposed and a person has not adopted. |
+| **Adopt** | A person's act of committing a candidate as the head. The only way refinement's output reaches a run. |
+| **Trust** | A person's approval of the exact text of a variant's plugin code (c8), by hash. |
+| **Run** | One session turn on a pinned variant, recorded by the foundation. |
+
+## Changing the architecture
+
+Every coding agent and contributor follows these steps.
+
+1. **Read first.** Before changing code, read the pages for the modules you touch.
+2. **Within the spec: just do it.** If the change fits every contract and invariant, make it. If it
+   adds detail without changing a rule (a new server method in an existing group, a new optional
+   field), update the page in the same commit.
+3. **Outside the spec: implement and update.** If the change alters a contract, an invariant, a
+   layer boundary, an extension point, or the storage layout, implement the requested change and
+   update affected pages in the same change. A proposal may document the design, but is optional
+   and does not gate implementation.
+4. **Record lasting decisions.** Add an ADR in `../decisions/` when the choice is a lasting one.
+   Proposals may be added to the index when useful; no `Accepted` status is required before work.
+5. **Drift is reported, not fixed silently.** If code and a page already disagree, add the item to
+   [Known drift](#known-drift) and tell the user. When resolving drift within the requested scope,
+   update the code and spec together and record the rationale; do not silently change unrelated
+   behavior.
+
+When unsure whether a change alters the architecture, read the affected pages and update them in
+the same change. Use a proposal only when it helps explain the design.
+
+## Known drift
+
+Disagreements found while writing this specification. Record their evidence here and report them;
+resolve relevant drift by updating the implementation and specification together in the same change.
+
+| ID | Where | What disagrees |
+|---|---|---|
+| D-32 | Ordered and nested list wrapping, `opentui/markdown.ts` (`alignListItems`) | The transcript renderer was written to keep a list item's wrapped lines beneath its text (nested lists and ordered markers wider than one digit). A general OpenTUI `renderNode` drops the blank rows between paragraphs and headings, so the renderer is code-block-only (`codeBlockOnly`) and lists no longer reach `alignListItems`: they wrap as in the previous release, continuation rows at column 4 where 7 was wanted. The verifier no longer checks it. Open; needs either structured lists with the block spacing restored, or OpenTUI support for both. |
+| D-31 | `scripts/verify-terminal.py --markdown-only` — resolved 2026-11-04 | The fixture sent 100 list items and its checks read the 40 visible rows. It now sends three short lists (starting at 1, 10 and 100) on a 120x72 screen. The suite also found the blank rows between paragraphs and headings missing with the new renderer, which is why that renderer is now code-block-only (D-32). |
+| D-30 | `scripts/verify-terminal.py` focused suites — resolved 2026-11-04 | The `browser`, `palette`, `accounts` and `trajectory` suites asserted layouts the terminal no longer draws; the product was right. Browser: the skill's description wraps in the 40-column completion column ("Inspect a" / "browser fixture."). Palette: command names carry their owner (ADR-0061) and wrap, and a narrow palette shows three lines per row. Accounts at 120x40: the search field holds the typed text, so its placeholder is not shown. Trajectory at 120x40: a wide event row shows its summary, not the event type. The script now reads the name column down its rows, matches wrapped text and compares columns. |
+| D-29 | `scripts/verify-terminal.py`, approval titles — resolved 2026-11-03 | The script expected `Approve ask_user?` and `Approve workspace-write?`; the terminal titles dialogs with display names (`AskUser`, `WorkspaceWrite`), and a harness run asks `ask_user` questions without an approval. The script now accepts either title, and the question with or without an approval. |
+| D-28 | Client terminal record contract — resolved 2026-11-03 | The script asserted that a terminal run's `nativeSessionId` is a history file. Client terminal runs record Pi's session id, as host runs do (page 11, Identity); the script resolves either to the history file, and `/session` takes either. |
+| D-27 | Subagent compaction, pages 02 and 04 | A subagent compacted at the context threshold (run `5cd1d8aa`, 2026-11-01) produced a summary whose `## Goal` read "No specific research question or task was provided" while its split-turn section kept the brief. The model that continued still had the task through the turn context, but the summary's headline contradicts it. Not resolved here; the cause (the brief sits in the split part of the turn) is not confirmed. |
+| D-26 | App browser tool catalog, pages 13 and 14 (PAR-015) — rechecked with ADR-0082 | Brave mode now supplies all shared Harness browser tools except the App-only upload through `browserToolsForSession` (`agent-app/sidecar/src/app.ts:172-177`, `appTools.ts:91-126`); WebKit still filters unsupported snapshot/ref operations. The Rust `app.capabilities` response remains backend-agnostic (`src-tauri/src/app_tools.rs:111-123`), while its `TOOL_IDS` and shared contract contain the new Browser tools (`shared/contracts.ts:557-562`, `src-tauri/src/agents.rs:90-103`). Thus a connected Brave backend implements the advertised refs, but the capability catalog can still mark WebKit-unsupported tools available. Partly resolved; backend-aware capability reporting remains open. |
+| D-25 | Native WebKit interaction, page 13 — rechecked with ADR-0082 | The Brave adapter now uses the shared ref-based definitions, but the App's Rust backend still routes `browser_click`, `browser_type` and the App-only `browser_upload` by CSS `selector` (`agent-app/src-tauri/src/browser_workspace.rs:1493`, `agent-app/shared/appTools.ts:20`). The shared provider refuses those WebKit operations and never maps refs to selectors. Open: extend the contract to selectors or remove the native selector paths. |
+| D-24 | Plan instruction delivery, pages 02 and 04 — resolved | The plan instruction exceeded its 4,000-character section budget, and the compaction checkpoint separately clipped it at 4,000 characters, risking loss of outcome rules. Both bounds are increased and covered by delivery tests so the complete current instruction survives compilation and compaction. |
+| D-23 | Terminal model-tool caller identity, pages 07 and 08 — resolved | `ownTools` used the session caller without the active run id, so `trajectory_read` with `run: 'current'` failed over `tools.call`. It now derives the caller on each execution and clears the identity after settlement. |
+| D-1 | `AGENTS.md` (before this spec), `INV-RUN-6` | The old rule said only `sessions/runStore.ts` writes `runs/<id>/`. In code, four other harness modules also write side files there: `prompt/compile.ts` (`context.json`), `sessions/sessions.ts` (`caller.json`), `capabilities/runSnapshot.ts` (`capabilities.json`), `mcp/service.ts` (`mcp-context.json`). The spec states the rule the code keeps (see `INV-RUN-6`); whether to route all of them through `runStore.ts` is open. |
+| D-2 | Plugin proposal review surfaces | `plugin_propose` and hash-bound proposal APIs now exist; a terminal review UI is pending and no App review UI is claimed. See [PAR-017](../parity.md#gaps). |
+| D-3 | `README.md` "External curation" | Describes `externalMaintenance`, `vaultAccess`, `MAINTENANCE_PLUGIN`, `maintenance.*` methods and tools. None exist in `src/`. |
+| D-4 | `INV-BND-2` | Several names carry an application's name: the context message type `xingular-context`, the approval extension `xagent-approvals`, the MCP client name `xagent`, and the terminal commands `xagent-wiki` / `xagent-mcp`. The default product name `Xingular Agent` is allowed; these are not. |
+| D-5 | `INV-BND-2` | `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts. They are stored and returned, never read, and are documented as the application's fields. Since PROP-0016 (2026-10-23) `worktreeId` has Harness meaning when it names a registered worktree; only `handoffId` remains an application field. |
+| D-6 | `INV-BND-2` | Plan-mode instructions (`sessions/planMode.ts`) name a managed browser and computer controls, which the harness does not provide. |
+| D-7 | `INV-MEM-3` | `wiki/notes.ts::remove` keeps a version but does not call `noteChange`, so hooks hear saves but not removals. |
+| D-8 | old `AGENTS.md` | Listed `work` among the sections delivered as updates. The compiler's built-in dynamic sections are only `references` and `wiki`; `work` is dynamic only when the application marks it so. `INV-PRM-3` states the code's rule. |
+| D-9 | World/browser implementation | Resolved for the 1.0.0 candidate by PROP-0012/ADR-0014 and page 13: the Harness owns a generic isolated browser; App browser UI, tab sharing and computer integration remain with the host. |
+| D-10 | OpenTUI skill completion | At the start of PROP-0013, documentation claimed skill completion, but OpenTUI only rendered slash-command completions. The skill helper had no frontend caller. PROP-0013 explicitly resolves this drift. |
+| D-11 | `INV-RUN-5`, unattended approval and question paths | Source inspection on 2026-10-23 found that `SessionRunInput.automatic` disables resource discovery and extension dialogs (`sessions/runner.ts:574`), but the general gate does not receive that flag. `Sessions.gate` explicitly refuses approvals for `probe`, `improver` and `reflection` triggers, then otherwise calls `requestApproval` (`sessions/sessions.ts:198`). `ask_user` was also constructed independently of `automatic` when harness tools were enabled (`sessions/sessions.ts:397`, `tools/askUser.ts:69`). That question-tool gap is resolved for newly resolved runs by PROP-0022/ADR-0022 (2026-10-24); an unattended continuation of a run pinned with that tool is rejected. Thus the flag alone does not establish the invariant that every unattended run refuses human interaction; host policy and capability selection can narrow these paths. This is a static source finding, not a live reproduction. See [proactive autonomy research](../study/proactive-autonomy.md#current-foundation-and-the-missing-loop). |
+| D-12 | 12-storage layout | The isolated browser keeps device-local profiles and settings under `<state dir>/browser/` (`browser/config.ts`, `browser/session.ts`); page 12's layout did not list it. Resolved 2026-10-23: page 12 lists it. |
+| D-13 | `docs/study/feature-gap-review.md` row 8 | Says browser and computer interaction are not built in. Page 13 (PROP-0012) records a generic isolated browser in the foundation; computer interaction needs a host surface. |
+| D-14 | 12-storage layout — resolved with ADR-0082 | Page 12 now distinguishes `<state dir>/browser.json` (`BrowserConfig`) from `<state dir>/browser/` (profiles, downloads and owner-only extension pairing state), matching `browser/config.ts` and `browser/extension/bridge.ts`. |
+| D-15 | Terminal sketch verification status — resolved 2026-10-24 by PROP-0028 | Pages 11 and 14 and `terminal-tui.md` said connected-sketch implementation verification was pending, while retained PTY evidence and PAR-014 recorded it as verified. Updated the docs to distinguish deterministic fixture verification from owner visual acceptance, every-emulator rendering and live-model sketch quality. |
+| D-16 | Terminal slash-command highlighting — resolved 2026-10-24 | `terminal-tui.md` specified accent coloring for recognized leading commands while typing, but the OpenTUI composer only styled attachment labels. User-message bubbles also lacked command-token styling. The renderer now uses the active command registry for both surfaces. |
+| D-17 | `PROP-0039`, `ADR-0036`, `INV-GATE-3/8` | Implementation is in progress in the 1.2.0 worktree: native writes revalidate canonical targets and atomically replace files under an OS write scope; default Bash fails closed on external hard-link aliases and runs in a sandbox that prevents new cross-boundary links; outside-scope Bash requires approval before one execution and command output never triggers approval or replay. The filesystem root is rejected as a workspace, and approval details expose the complete command. Launcher selection uses fixed system paths. Same-user peer processes remain outside this boundary. Focused macOS tests, full Harness CI, App compatibility checks, and PTY verification at 40x20, 80x24, and 100x30 pass. Linux sandbox integration remains unverified locally because this Darwin host has no `bwrap` and Colima is stopped; both CI workflows now install bubblewrap and `scripts/ci.sh` fails if it is absent, but an Ubuntu run is still required. No candidate, tag, or publication exists. |
+| D-20 | Terminal pending queues, page 11 — resolved | The terminal now projects native and deferred pending messages above the working line. |
+| D-19 | Provider limits layout | Page 09 describes a centered Limits dialog; page 11 and `src/terminal/tui/pages/usagePage.ts` describe and implement a full-screen page. |
+| D-18 | `core/index.ts` migration 5 | The `run_stats` table has no writer in the Harness. PROP-0042's `usage_requests` ledger is the analytics source; whether to drop the older table is open. |
+| D-21 | `terminal-tui.md`, per-mode model and effort | The terminal page says the App reads and writes the per-mode choices through `accounts.choices` and `accounts.choose`. The App's source calls neither method: its account, model and effort are saved on the App Thread (App ADR-0023), and plan mode shares that Thread's tuple. Whether the App should adopt the Harness's per-mode store is an owner decision. |
+| D-22 | Plan outcomes, pages 02 and 11; ADR-0055 — resolved | Page 02 previously described a missing-block repair without distinguishing paths: the runner repaired but the terminal only warned, and neither classified clarification. ADR-0057 adds shared outcome classification and a bounded repair in both paths. |

package/docs/architecture/proposals/PROP-0001-reporting-section.md

@@ -0,0 +1,106 @@
+---
+id: PROP-0001
+title: A built-in Reporting section that shapes the final reply
+status: Implemented
+created: 2026-10-21
+updated: 2026-10-21
+affects: [INV-PRM-2, 04-prompt.md]
+---
+
+# PROP-0001: A built-in Reporting section that shapes the final reply
+
+Accepted by the user on 2026-10-21 and implemented the same day; see
+[ADR-0007](../../decisions/ADR-0007-reporting-section.md).
+
+## Problem
+
+Nothing in the compiled prompt says how a run should end. `src/prompt/compile.ts` emits the tree's
+sections, references, the Wiki pointer and the tools; a seed tree's `systemprompt.md` is empty
+unless the application gives instructions (`src/tree/seed.ts`). Final replies therefore vary in
+shape: the answer is often buried after a narration of steps, files changed are not listed, and
+unverified work is not called out.
+
+The person wants every final reply to answer first, list files read and changed, and say what is
+blocked, what is worth a look, what to check by hand, and what comes next, using Markdown tables
+where they help. The terminal already renders Markdown with tables (`docs/terminal-tui.md`,
+"Markdown transcript"), so the gap is only in the prompt.
+
+Other harnesses put this in their fixed prompt text:
+
+| Harness | Where | What it says |
+|---|---|---|
+| opencode | `external/opencode/packages/core/src/plugin/system-prompt/gpt.txt:19-23` | "Final Answer": lead with the outcome; only as much structure as needed; the final answer is self-contained; a blocking question goes there |
+| omp | `external/omp/packages/coding-agent/src/prompts/system/system-prompt.md:11-27, 249-257` | Numbers to compare → Markdown table; report only exercised verification; when blocked, state exactly what is missing and what was tried |
+| kimi-cli | `external/kimi-cli/src/kimi_cli/agents/default/system.md:152-159` | Concise; never more than the user wants |
+| Claude Code | published prompt (no clone) | Outcome first, tl;dr style; report failed or skipped checks; `path:line` references |
+| Codex CLI | published prompt (no clone) | "Final answer structure": headers only when useful, bullets, file paths, a natural next step |
+
+## Affected rules
+
+- `04-prompt.md`, Section order: "`SECTION_ORDER`: `system` 25, `guardrails` 40, `memory` 45,
+  `references` 50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90."
+- **INV-PRM-2** "The system prompt holds only stable text: identity, role, the tree's sections, tool
+  guidance and the tool manifest. Changing state never enters it."
+
+## Proposal
+
+The compiler adds one harness-owned section to every pack:
+
+- id `reporting`, title "Reporting your work", `SECTION_ORDER.reporting = 95` (after `tools`).
+- Fixed text in `src/prompt/compile.ts` (`REPORTING_GUIDANCE`), budget 2,000 characters, never cut,
+  no volatile values. It is not dynamic, so `sessionLaunch` puts it in the stable prefix and
+  terminal sessions get it through `compile` + `render`.
+- It names no application. It yields to any other format the person, the application or the
+  current mode (for example plan mode) asks for.
+
+INV-PRM-2 becomes: "The system prompt holds only stable text: identity, role, the tree's sections,
+the harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it."
+
+Section text:
+
+```markdown
+When you finish work, write the final reply for a person who did not watch you work.
+
+- Start with the answer or outcome in one or two sentences. If they asked a question, answer it first.
+- Then add only the parts that have content, in this order, under short bold labels:
+  - **Files**: what you read that mattered and what you changed, as `path:line` with a few words each. Use a table (File | Change | Why) when there are three or more.
+  - **Blocked**: what stopped you, what you tried, and what you need from the person.
+  - **Worth a look**: risks, surprises, or choices the person may disagree with.
+  - **Check by hand**: what you could not verify yourself and how to check it. Name the checks you ran and their result; never claim a check you did not run.
+  - **Next steps**: one to three concrete actions, the most useful first.
+- Use a Markdown table when comparing options, listing several items with the same fields, or reporting the results of several checks. Use prose or bullets otherwise.
+- Keep it short. Skip a part instead of writing "none". A one-line question gets a one-line answer.
+- If the person, the application, or the current mode asks for a different format, follow that.
+```
+
+## Alternatives
+
+- **Do nothing.** Reply shape stays model-dependent; the request is not met.
+- **Default text in the tree (`systemprompt.md`).** Refinement could tune it per scope, but trees
+  created before the change never get it, and an adopted refinement could drop it.
+- **An application section.** Every application would have to repeat it, and the terminal has none.
+- **A harness-built file list from run events.** Always exact, but needs terminal and protocol
+  work. Deferred; the model writes the list for now.
+
+## Consequences
+
+- Every system prompt gains about 1,200 characters. The prefix changes once, so each existing
+  session's provider cache misses once after upgrade; afterwards it is byte-stable.
+- Applications need no change. The App's sidecar bundle must be rebuilt to pick it up.
+- No change to stored data or the server protocol. `runs/<id>/context.json` lists the new
+  section in `sections` and `delivery.systemSectionIds`.
+
+## Migration
+
+None for data. Undo by removing the section; the prefix changes once more.
+
+## Checks
+
+- `compile.test.ts`: section-id lists end with `reporting`; the section is in the `sessionLaunch`
+  system prompt, byte-identical across compiles, and never in a context update.
+- Harness `npm run typecheck`, `npm test`; App `npm run typecheck`, `npm test`,
+  `npm run check:layers`, `cd src-tauri && cargo test`.
+- By hand: a terminal run that reads and edits files ends with a reply in this shape, and its
+  table renders.
+- Cache effect measured with the App's `scripts/probe-chat-cache-app.py`, only with the account
+  owner's permission (INV-PRM-8).

package/docs/architecture/proposals/PROP-0002-retain-rollout-workspaces.md

@@ -0,0 +1,104 @@
+---
+id: PROP-0002
+title: Opt-in retention of each refinement execution's workspace
+status: Implemented
+created: 2026-10-21
+updated: 2026-10-21
+affects: [05-refinement.md, 10-server-protocol.md, 12-storage.md, INV-REF-1]
+---
+
+# PROP-0002: Opt-in retention of each refinement execution's workspace
+
+## Problem
+
+An external measurement of refinement must grade the files that the base executions and the
+chosen final produced. Examples are a `.docx` memo, an `.xlsx` model, or a repository a verifier
+runs tests in. Today those files are gone by the time the refinement finishes:
+
+- `PiExecutor.execute` (`src/refine/pi.ts:83-119`) runs in the host's workspace, then always calls
+  `workspace.cleanup()` in `finally`.
+- `DEFAULT_REFINE_HOST.prepareWorkspace` (`src/refine/host.ts`) removes its temporary folder in
+  that cleanup.
+- Only `defaultDeliverable` survives, under `rollouts/<label>/deliverables/`. It keeps the reply and
+  the *text* files that changed, and drops binary files (`readable` rejects any buffer containing
+  `0`). It also stops at `FILES_LIMIT`.
+
+An application can work around this by supplying its own `RefineHost` in-process. A client of the
+server protocol cannot: `refine.start` has no host parameter, and it should not have one.
+
+The request comes from the Evaluation repository. It needs to replicate the Harness² paper's
+benchmarks (JobBench, LAB, WorkBuddy-Bench) and grade the base executions and the chosen
+execution after selection, as upstream `harness2-judge` and `harness2-judge --bases` do.
+
+## Affected rules
+
+- 05 Contracts: "`start({ task: { id, scope, prompt, ... }, k?, mode?: 'parallel' | 'sequential',
+  baseVersion?, improver? })` returns `{ id }` at once".
+- 05 Data: `<data root>/refine/<id>/  summary.json, task.json, harnesses/<label>/, rollouts/<label>/, ...`.
+- 10 Server protocol: the `refine.start` parameters.
+- INV-REF-1 (unchanged, restated so it covers the new folder): "No rubric, score, grader output or
+  reviewer verdict reaches an improver, the selector or the library."
+
+## Proposal
+
+**05 Contracts** become:
+
+- `start({ task, k?, mode?, baseVersion?, improver?, retainWorkspaces? })`. When `retainWorkspaces`
+  is `true`, each execution's workspace is copied to `rollouts/<label>/workspace/` once the run has
+  settled and before the host's `cleanup` runs. The copy is whole: binary files, hidden files and
+  nested folders. Symbolic links are copied as links and are not followed. The default is `false`,
+  which keeps today's behaviour.
+- The option covers base, candidate and final executions alike. `refine.candidates` reports
+  `workspace: '<path>' | null` on each execution, so a caller can find it without knowing the
+  layout.
+- A failed copy is recorded as `workspaceError` in `rollout.json`. It never fails the execution or
+  the refinement.
+
+**05 Data** gains `rollouts/<label>/workspace/`, which exists only with `retainWorkspaces`.
+
+**INV-REF-1** gains one sentence: "Retained workspaces are output for measurement after the fact.
+Evidence, selection, reflection and the library never read them." The evidence builder keeps
+reading `deliverables/` only. A test asserts that no evidence folder contains a path under
+`workspace/`.
+
+**10 Server protocol.** `refine.start` accepts `retainWorkspaces: boolean`. The CLI gains
+`refine run ... --retain-workspaces`.
+
+The option names no application concept, and every host benefits from it, including the default
+host and an application's own host.
+
+## Alternatives
+
+- **Do nothing; the evaluator supplies a `RefineHost` whose `cleanup` is a no-op.** This only
+  works in-process. Evaluation drives the harness through the server and the CLI, as its
+  production adapters do. It would have to embed the harness as a library, which differs from the
+  production path it is meant to measure.
+- **Let `deliverable` keep binary files.** This changes what improvers and the selector see:
+  binary bytes in the evidence, and a larger pool. That is a change to the method itself, not to
+  measurement.
+- **Retain only the chosen final.** The base arm is measured on the base executions, as in
+  upstream `--bases`, so they are needed too. Retaining every execution is simpler and costs only
+  disk.
+
+## Consequences
+
+- **Applications:** none, unless they opt in. A host's own `cleanup` still runs after the copy.
+- **Stored data:** opted-in refinements grow by about R = 4k workspace copies. This is
+  disk-heavy for large sources. The option stays opt-in for that reason, and the docs say so.
+- **Server protocol:** one optional parameter and one optional field on candidate views. Both are
+  additive. The App's sidecar schemas need the optional `workspace` field.
+
+## Migration
+
+None. Existing records have no `workspace/` folder, and their candidate views report `null`.
+Undoing the change means removing the option; retained folders stay as inert files.
+
+## Checks
+
+- A unit test: a fake executor run with `retainWorkspaces` keeps a binary file and a nested
+  folder under `rollouts/<label>/workspace/`. Without the option, the folder is absent.
+- A unit test: evidence folders never include `workspace/`, so the INV-REF-1 tripwire still holds.
+- `npm run typecheck`, `npm test`, `npm run prove` (the CLI flag), and
+  `node dist/cli.js refine demo --k 2 --retain-workspaces`.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.
+  The sidecar schema test parses the new field.

package/docs/architecture/proposals/PROP-0003-executor-settings.md

@@ -0,0 +1,81 @@
+---
+id: PROP-0003
+title: Name the model and account of refinement's executions on refine.start
+status: Implemented
+created: 2026-10-21
+updated: 2026-10-21
+affects: [05-refinement.md, 10-server-protocol.md, 01-extension-points.md (RefineHost)]
+---
+
+# PROP-0003: Name the model and account of refinement's executions on refine.start
+
+## Problem
+
+`refine.start` lets a caller choose the model, effort and account of the improver, selector and
+reflector sessions (`improver: ImproverSettings`). It does not let the caller choose them for the
+executions (base, candidates, finals):
+
+- `PiExecutor.execute` (`src/refine/pi.ts`) takes `model`, `effort`, `accountId` and `poolId` only
+  from `RefineHost.session(...)`.
+- With no host (a plain `xharness serve`, which Evaluation drives), `DEFAULT_REFINE_HOST`
+  returns none of them. The executions then run on whatever Pi resolves as the default account's
+  default model.
+- Runs do not consult saved per-mode choices either (`accounts.choices` is terminal-only).
+
+So a server client cannot say "execute with `openai-codex/gpt-6-luna` on account X". Evaluation
+cannot meet its own rule ("Live runs require an explicitly selected credential, model, and bounded
+configuration. Do not silently substitute models or accounts"), and a measured run could silently
+use a different executor model from the one recorded in its config.
+
+## Affected rules
+
+- 05 Contracts: "`start({ task: { id, scope, prompt, ... }, k?, mode?, baseVersion?, improver?, retainWorkspaces? })`".
+- 01 Extension points, `RefineHost.session` supplies the rollout's session settings. This stays
+  true; the proposal only adds a caller-supplied default beneath it.
+- 10 Server protocol: the `refine.start` parameters.
+
+## Proposal
+
+**05 Contracts:**
+
+- `start` gains `executor?: { model?, effort?, accountId?, poolId? }`, with the same shape as
+  `ImproverSettings`.
+- For each execution, the settings come from the host's `session(...)` value first, then from
+  `executor`, then from the account default.
+  - A host keeps full control.
+  - A caller with no host can still pin the model.
+- `summary.json` records `settings: { executor, improver }` as the refinement was started. Each
+  probe run's own record holds the model it resolved, so the run records stay authoritative.
+
+**10 Server protocol:** `refine.start` accepts `executor`, and `refine run` accepts
+`--executor-model <id>`. The existing `--model` keeps meaning the improver model. Its usage text
+says so.
+
+No application concept is named. The default behaviour, with no `executor`, is unchanged.
+
+## Alternatives
+
+- **Do nothing; set Pi's default model in the account's agent folder.** This relies on Pi's
+  settings file layout, which is an internal of the account folder, and it is not recorded with
+  the refinement. Rejected.
+- **A `refine.host` RPC so a client can describe a host.** This is far larger: callbacks over the
+  protocol for `prepareWorkspace` and `deliverable`. The only need today is the session settings.
+- **Reuse `improver` for executions.** The paper separates executor and editor models (GLM-5 or
+  Gemini executors, an Opus editor). Conflating them would make that design impossible to express.
+
+## Consequences
+
+- **Applications:** none. The App supplies a host, and the host's values still win.
+- **Stored data:** one optional object in `summary.json`.
+- **Protocol:** one optional parameter, which is additive.
+
+## Migration
+
+None. Old summaries have no `executor` field.
+
+## Checks
+
+- A unit test: with no host, a refinement started with `executor.model` runs every probe with
+  that model. With a host that names a model, the host's model wins.
+- `npm run typecheck`, `npm test`, `npm run prove`.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.

package/docs/architecture/proposals/PROP-0004-flexible-reporting-guidance.md

@@ -0,0 +1,71 @@
+---
+id: PROP-0004
+title: Flexible final-reply guidance with an optional human-inspection heading
+status: Implemented
+created: 2026-10-21
+updated: 2026-10-21
+affects: [INV-PRM-2, 04-prompt.md, ADR-0007, ADR-0008]
+---
+
+# PROP-0004: Flexible final-reply guidance with an optional human-inspection heading
+
+Accepted by the user and implemented; see [ADR-0008](../../decisions/ADR-0008-flexible-reporting-guidance.md).
+
+## Problem
+
+The stable `reporting` section in `src/prompt/compile.ts` prescribes a fixed sequence of headings,
+including **Worth a look** and **Check by hand**. This can force generic report structure when it adds
+no value, and “Worth a look” does not clearly distinguish a concrete action that needs human
+inspection because the agent could not perform it. The user requests flexible, content-driven
+headings and a clearer label for genuinely unverified work.
+
+## Affected rules
+
+- `04-prompt.md`, Reporting: “It is fixed text that shapes the final reply” and currently specifies
+the ordered parts Files, Blocked, Worth a look, Check by hand, and Next steps.
+- **INV-PRM-2**: “The system prompt holds only stable text: identity, role, the tree's sections, the
+harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it.”
+  The invariant remains unchanged; the reporting text remains stable.
+- [ADR-0007](../../decisions/ADR-0007-reporting-section.md) records the prior fixed heading list;
+it is superseded by [ADR-0008](../../decisions/ADR-0008-flexible-reporting-guidance.md).
+
+## Proposal
+
+Keep the harness-owned reporting section, its position, stable delivery, and concise outcome-first
+rule. Replace the mandatory fixed heading sequence with guidance to use only structure that helps
+explain the outcome; do not require generic headings such as **Worth a look** or **Check by hand**.
+
+When a concrete verification step requires a person because the agent could not perform or observe
+it, use the optional heading **Need human inspection**. Say what remains unverified, why the agent
+could not verify it, and the specific check the person should perform. Do not use this heading for
+checks the agent ran or for speculative, non-actionable risks. Continue to report checks truthfully
+and honor any format requested by the person, application, or current mode.
+
+## Alternatives
+
+- **Do nothing.** Keep the fixed headings, even when they produce generic or misleading sections.
+- **Remove all guidance about unverified work.** This avoids a fixed heading but makes it easier to
+  omit concrete human follow-up.
+- **Make “Need human inspection” mandatory.** Rejected because many tasks have no check requiring a
+  person.
+
+## Consequences
+
+- The system prompt stays stable and harness-owned; all applications receive the revised guidance.
+- Existing sessions get one provider-prefix change and may miss the prompt cache once after upgrade.
+- No stored data or server protocol changes. Applications bundling the harness must rebuild to pick
+  up the new guidance.
+
+## Migration
+
+None for stored data. The new text supersedes the reporting instructions in ADR-0007; reverting the
+change would alter the stable prefix again.
+
+## Checks
+
+- `src/prompt/compile.test.ts`: assert the stable system prompt carries the flexible guidance,
+  does not require the old fixed headings, and describes **Need human inspection** as conditional.
+- Harness `npm run typecheck` and `npm test`.
+- Xingular Agent `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.
+- Provider-cache impact is measured only with real application requests and the account owner's
+  permission, as required by INV-PRM-8.

package/docs/architecture/proposals/PROP-0005-xharness-cli-name.md

@@ -0,0 +1,78 @@
+---
+id: PROP-0005
+title: Rename the published CLI command to xharness
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [11-terminal.md, package.json#bin, CLI documentation]
+---
+
+# PROP-0005: Rename the published CLI command to xharness
+
+## Problem
+
+The published `@xingular/harness` package exposes the `xingular-harness` executable through its
+`bin` entry. The requested public command is `xharness`, which should open the existing standalone
+OpenTUI terminal when invoked without a subcommand. The CLI already routes a no-command invocation
+to that terminal; this proposal changes the published executable name and its documentation, not
+the terminal runtime.
+
+The npm registry currently reports `3.0.0` as the latest version. Removing the published command
+is a breaking CLI change.
+
+## Affected rules
+
+- `docs/architecture/11-terminal.md` identifies the standalone terminal application as
+  `xingular-harness`.
+- `package.json#bin` and the package lock expose `xingular-harness` as the installed command.
+- CLI help and user documentation use `xingular-harness` for the public executable.
+
+## Proposal
+
+Publish `@xingular/harness` version `4.0.0` with a single `xharness` executable pointing to
+`dist/cli.js`. Do not retain `xingular-harness` as an alias, consistent with the requested
+replacement. Invoking `xharness` without arguments starts the existing OpenTUI terminal; `terminal`
+and the existing subcommands remain available.
+
+Update the CLI help/comments, package manifest and lockfile, terminal architecture page, README,
+terminal guide and changelog to use `xharness` for invocations. Add regression coverage for the
+published `bin` name and help text. Keep the npm package name `@xingular/harness`, the data and
+state directory names, and `XINGULAR_HARNESS_*` environment variables unchanged.
+
+Build and verify the package with the repository CI checks, inspect the packed tarball, install the
+local tarball to test `xharness --help` and interactive TUI startup, publish to npm, then verify the
+registry metadata and a fresh global install.
+
+## Alternatives
+
+- Keep `xingular-harness` as a compatibility alias while recommending `xharness`. This reduces
+  disruption but does not fully replace the command as requested.
+- Rename the npm package itself. This is unnecessary: the request concerns the executable, and
+  changing the package name would create a separate migration.
+- Do nothing. This leaves the published interface unchanged.
+
+## Consequences
+
+- Existing scripts and instructions invoking `xingular-harness` must change to `xharness`.
+- Removing the old executable is a breaking change, hence the proposed major version bump.
+- Existing Harness data, account state and environment-variable overrides remain in place; no data
+  migration is needed.
+- The package still requires Node 22.19+ and Bun 1.3.14+ to build and run the standalone TUI.
+
+## Migration
+
+Install `@xingular/harness@4.0.0` and launch the terminal with `xharness`. Update scripts or shell
+aliases that invoke `xingular-harness`. Existing `~/.xingular-harness/{data,state}` contents are
+reused without conversion.
+
+## Checks
+
+- `npm run ci` passed: typecheck, 742 tests (3 skipped), build and standalone proof.
+- `npm pack --dry-run` passed and included the CLI and OpenTUI bundles.
+- A temporary global install from the tarball exposed only `xharness`; `xharness --help` showed the
+  new usage and a TTY launch rendered the Harness welcome screen.
+- Publication was attempted, but npm returned E404. `npm whoami` returned E401, and the registry
+  still reports `3.0.0` as latest; `4.0.0` has not been published. Retry after restoring npm
+  authentication and package publish permission.
+
+The decision is recorded in [ADR-0009](../../decisions/ADR-0009-xharness-command.md).