@xingular/harness 0.1.7 → 1.1.1

package/docs/architecture/13-world-tools.md

@@ -0,0 +1,45 @@
+# 13 World tools
+
+The Foundation owns the generic isolated browser engine, per-session contexts and profiles,
+network policy, and lifecycle. Built-in World plugins contribute the user-facing web search/page
+tools, browser tools and annotations through the existing tool-provider surface. Every tool passes
+the same capability and policy gate. Web requests use the public-address guard; browser requests
+use the device-local private-address setting. Read page content is untrusted. Sending, purchasing,
+deleting, changing accounts and granting access require explicit human approval. Sensitive fields
+are not filled by the agent.
+
+The App owns its shared WebKit browser UI, private/shared tab policy, selected-file uploads,
+windows and the native computer bridge. These application objects do not enter the Harness.
+Other hosts may add backend capabilities and diagnostics through ToolProvider or WorldPart.
+
+Browser configuration is device-local. User-configured CDP attachment is explicit; diagnostics
+never attach to it. Doctor browser probes instead use disposable headless profiles and an offline
+synthetic page. Their input runs only after live-check confirmation, and their resources are
+released on completion, timeout or cancellation. Computer interaction needs a host-provided
+isolated surface; without one it is blocked.
+
+Plugin ownership and the Foundation boundary are recorded in PROP-0012, ADR-0014 and PROP-0020.
+World providers are assembled through `BuiltinPluginRegistry`; no eighth extension point is added.
+
+An embedding host may set `browser: false` to disable the generic backend and its plugin
+descriptor before supplying its own browser tool provider. The App uses this option for its
+shared-tab browser, so matching tool names never silently select the wrong backend.
+
+## Page notes (PROP-0017)
+
+The `annotations` world part offers `page_notes_list` and `page_notes_read`, read-only, to SDK and
+terminal sessions. It is separate from the browser part, so a host that sets `browser: false` keeps
+it. A tool returns only notes a person shared with the calling session or agent; quoted page text
+and element names are marked untrusted. Capture happens in a visible capture browser in the
+terminal, or in a host's own web view running the same page helper (`annotations.pageScript`).
+
+**Inspector, queue and app targets (PROP-0018).**
+
+- **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with three choices: save, queue for the agent, or send now.
+  - A queued note is shared with its session.
+  - `annotations/delivery.ts` sends a batch as one instruction, and sends notes the person asked for while the session was busy when its run ends.
+  - The agent reports a fix with `page_notes_mark_fixed`, the only page-note tool that writes. It never resolves a note or changes grants.
+- **Targets.** Besides the browser window, capture can use an app's own windows:
+  - **DevTools port:** an app started with a DevTools port, on a loopback address only. It uses the app's existing windows, routes nothing, and never closes the app.
+  - **Page bridge:** a loopback server whose script an app loads while it is developed (`annotations/bridge.ts`), for web views without a DevTools port.
+- **Trust.** In Chromium targets the helper runs in an isolated script world, so the page cannot forge a comment. A send from the bridge, or from a host web view without isolation, waits for the person to confirm it.

package/docs/architecture/14-surfaces-and-parity.md

@@ -0,0 +1,89 @@
+# 14 Surfaces and parity
+
+## Purpose
+
+The harness has more than one front end: its own standalone terminal (`xagent`, page 11) and
+every application that embeds it. This page fixes how capabilities relate to those front ends, so
+that a person can do the same work in the terminal and in a host, and so that a reader knows that
+a capability is Harness work even when a request names a host.
+
+A *capability* is something a person or a model can do: start a session, approve a call, work in
+a worktree, annotate a page, inspect a run. A *surface* is how one front end presents it: a
+terminal command or page, a host screen.
+
+## Components
+
+| Kind | What it is | Example |
+|---|---|---|
+| Foundation service | A member of `Harness` with server methods | `sessions`, `accounts`, `apps`, `worktrees` (PROP-0016), agent profiles (`agents.*`, PROP-0029) |
+| Built-in feature plugin | A module in `BuiltinPluginRegistry` (`plugins/builtin.ts`) that may supply a `WorldPart`, server methods and terminal commands | web tools, browser tools, annotations, worktrees |
+| First-party plugin | A descriptor in the registry (`plugins/builtin.ts`) | lessons, checklist |
+| Terminal surface | A command, page or dialog in `terminal/` | `/plan`, `/doctor`, the resource browser |
+| Host surface | A host screen built on the same methods and tools | the App's chat, Capability and Harness screens |
+| Host-backed backend | An operating-system object only a host has, behind a generic Harness contract | the App's WebKit tabs, macOS computer bridge, keychain |
+| Host-only surface | Presentation a terminal cannot show (INV-PAR-4) | reserved: interactive agent output ("OpenUI") |
+
+## Contracts
+
+- A capability is reachable through server methods (page 10) and, where a model uses it, through a
+  tool that passes the gate (page 07). Both front ends use the same methods; neither has a private
+  path to Harness state.
+- Required built-in plugin commands and Foundation commands use unprefixed names. Optional built-in
+  plugin commands and Pi extension commands use `/plugin:<command>`. A bare command, alias or loaded
+  prompt owns its name; a colliding prefixed command is hidden and rejected. Built-in plugin
+  categories are documented in page 06 and are not public plugin metadata.
+- A capability may be limited to a run mode when Harness resolves the callable set; the register
+  records that restriction for both surfaces. `ask_user` is available only in attended plan runs,
+  and the terminal's `ask_user_question` alias follows the same restriction.
+- Question choice sketches use one optional validated event contract: up to 80 printable ASCII
+  columns by 24 LF-separated lines (1,943 bytes maximum; page 02). Both surfaces use the same
+  literal ASCII source, persisted unchanged, in one shared preview with access to overflow; neither
+  changes the answer payload (PROP-0025, ADR-0026; originally PROP-0024). The terminal may project
+  recognized ASCII table-border rows—including title-bearing rules—and enclosed vertical table
+  edges into connected box-drawing glyphs, retaining internal framed table widths. For a
+  high-confidence frame, it may fill a missing boundary cell or realign a displaced edge only
+  through whitespace to matched corner columns; interior text and ambiguous rows remain unchanged
+  (PROP-0028, ADR-0029). Bare standalone hyphen dividers expand to the larger of viewport width and
+  original sketch widest line and join the outer single-line frame with `├` and `┤` (PROP-0026,
+  ADR-0027). Prose, content operators and ordinary pipes are not globally substituted. Hosts may
+  retain literal ASCII previews: equivalent capability does not require identical structural
+  typography. No schema, validation-bound, persistence or answer-payload change follows from these
+  display amendments. Terminal geometry, scrolling and projection boundaries follow page 11; hosts
+  may use native presentation without narrowing accepted metadata. Existing hosts with the old
+  bounds must update before accepting larger sketches. Acceptance of the expanded contract on both
+  surfaces is tracked in the parity register. Isolated production PTY evidence verifies bounded
+  fixture topology, not every emulator/font or live-model sketch quality.
+- Side questions use one Harness service on both surfaces. Each caller supplies its visible
+  transcript projection; Harness adds the parent run's effective prompt and public events, then
+  starts an independent tool-free run.
+- The register of capabilities and their surfaces is [`docs/parity.md`](../parity.md). It is
+  descriptive; the invariants below are binding.
+- A host keeps its own register of host-only surfaces. The Harness names no host surface.
+
+## Invariants
+
+- **INV-PAR-1** Every capability a person can use in a host is a Harness capability: a foundation
+  service, a world part or a first-party plugin, reachable through server methods. The standalone
+  terminal surfaces it. A host is a presentation of it.
+- **INV-PAR-2** A capability is complete only when its terminal surface and its host surface both
+  pass acceptance. It lands in the Harness first, together with its terminal surface; the host
+  surface follows.
+- **INV-PAR-3** A host-backed capability needs an operating-system object only a host has. The
+  Harness defines the generic contract and a terminal fallback (for example the headed isolated
+  browser for page annotations). Without a fallback, the terminal shows the capability as
+  unavailable, with the reason, in `/doctor` and `/tools`.
+- **INV-PAR-4** A host-only surface owns no capability. Its actions are Harness methods or tools,
+  its data lives in Harness records, the terminal renders a text fallback, and each one is listed
+  in the host's register by an owner decision. A generic rich-output event kind for such surfaces
+  needs its own proposal; the name is reserved and nothing is designed.
+
+## Data
+
+None of its own. Each capability stores its data as its own page says.
+
+## Source map
+
+`src/harness.ts` (services), `src/world/world.ts` (world parts), `src/plugins/builtin.ts`
+(first-party descriptors), `src/terminal/` (terminal surfaces), `src/server/methods.ts` (methods).
+Decision: [PROP-0015](proposals/PROP-0015-one-capability-surface.md),
+[ADR-0017](../decisions/ADR-0017-one-capability-surface.md).

package/docs/architecture/README.md

@@ -0,0 +1,125 @@
+# Harness architecture specification
+
+**Status:** binding. **As of:** 2026-10-24, 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 would alter what it says needs a proposal the user approves first (see
+[Changing the architecture](#changing-the-architecture)).
+
+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` |
+| [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, and by proposal when a contract moves. |
+| **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: propose and stop.** If the change would alter a contract, an invariant, a
+   layer boundary, an extension point, or the storage layout, do not change code or pages yet.
+   Write `proposals/PROP-NNNN-<slug>.md` from the [template](proposals/README.md#template) with
+   status `Proposed`, add it to the proposals index, and ask the user to review it.
+4. **After approval.** The user sets or confirms status `Accepted`. Then implement it, update the
+   affected pages in the same change, and add an ADR in `../decisions/` when the choice is a
+   lasting one. A rejected proposal keeps its file with status `Rejected`.
+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. Do not change either side to match without
+   asking; resolving drift that changes a rule is itself a proposal.
+
+When unsure whether a change alters the architecture, treat it as if it does and write the
+proposal.
+
+## Known drift
+
+Disagreements found while writing this specification. Each needs a decision from the user (a
+proposal, or a correction to the other document).
+
+| ID | Where | What disagrees |
+|---|---|---|
+| 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 | `README.md` "Plugins" | Describes a `plugin_propose` tool and an Inbox for proposed plugins. No such tool exists in `src/`. |
+| 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 | Page 12 lists browser settings under `<state dir>/browser/`, while `browser/config.ts` stores configuration in `<state dir>/browser.json`; browser profiles and downloads use the `browser/` directory. The layout needs an owner decision before either side is changed. |
+| 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. |

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.