@xingular/harness 0.1.7 → 1.0.0

package/docs/architecture/12-storage.md

@@ -0,0 +1,61 @@
+# 12 Storage
+
+## Purpose
+
+The harness keeps two folders. The **data root** holds knowledge and history that may be shared
+or synced: variants, refinements, the library, the Wiki, runs. The **state directory** holds
+device-local state that must never travel with the data: accounts, secrets, approvals, trust,
+connections, sockets. Files are the source of truth everywhere; the only database is a derived
+index.
+
+## Layout
+
+```text
+<data root>/
+  variants/<scope>/   versions/<fingerprint>/{variant/, version.json}, head.json, lineage.jsonl, restores.jsonl   (03)
+  refine/<id>/         summary.json, task.json, variants/, rollouts/, sessions/, context/, selection/, reflection/, improver/, or matrix.json + suite.json for evaluation matrices   (05)
+                       rollouts/<label>/workspace/ only when started with retainWorkspaces
+  library/<scope>/<area>/   INDEX.md, variants/<task>/{variant/, EXPERIENCE.md}   (05)
+  wiki/                home.md, library/ (library/lessons/ from the lessons plugin), projects/<slug>/   (08)
+  reflection/improver/lesson-<run id>/   a reflection's native history and reply   (08)
+  wiki-history/        earlier versions of notes   (08)
+  legacy/              an earlier Wiki's data, moved once   (08)
+  registry/            skills/, prompts/, rules/: the component library   (03)
+  plugins/<name>/      packages kept with the data   (06)
+  trash/plugins/       removed packages   (06)
+  hub/                 installed documents and provenance   (09)
+  runs/<id>/           run.json, events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json   (02)
+  config/              plugin-attachments.json and settings the harness reads   (06)
+  index.sqlite         derived index (FTS5)   (08)
+  projects.json        read only: the application owns it
+
+<state dir>/
+  accounts/            registry, per-account Pi agent folders, _shared/pi/, audit log   (09)
+  secrets.json         default SecretStore, owner-only   (09)
+  approvals.json       standing approvals   (07)
+  plugin-trust.json, variant-plugin-trust.json, plugin-registered.json, plugin-hooks.json   (03, 06)
+  connections.json     connected apps, no secrets   (09)
+  hub/catalog.json     catalog cache   (09)
+  run/                 the session socket and terminal commands   (11)
+  harness.log          standalone terminal diagnostics
+```
+
+## Invariants
+
+- **INV-STO-1** Device-local state (credentials, approvals, trust, connections, sockets) is never
+  written to the data root, and knowledge or history is never written to the state directory.
+- **INV-STO-2** Files are the source of truth. `index.sqlite` can be deleted and rebuilt
+  (`INV-MEM-5`); its migrations are append-only (`INV-MEM-6`).
+- **INV-STO-3** Each folder has one owning module, named on its page. Another module reads it
+  through that module's functions. A new top-level folder or a new file in `runs/<id>/` is an
+  architecture change.
+- **INV-STO-4** `projects.json` belongs to the application; the harness only reads it.
+- **INV-STO-5** Migrations of stored data are one-way and safe: the old data is backed up or left
+  as it was when a migration fails, and the failure is reported in `Recovery.migrationError`.
+- **INV-STO-6** Writes of shared JSON files are atomic (`core/fs.ts::atomicWrite`, `writeJson`).
+- **INV-STO-7** Files holding trust or secrets are owner-only (`0600`).
+
+## Source map
+
+`src/harness.ts` (`open`), `src/core/fs.ts`, `src/core/index.ts`, and the store module of each
+part, listed on its page.

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

@@ -0,0 +1,23 @@
+# 13 World tools
+
+The foundation supplies generic web and isolated browser tools through the existing tool-provider
+surface. Web requests use the public-address guard. Each browser session owns its context and
+profile; its tools pass the same capability and policy gate as other tools. 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.
+
+Ownership is recorded in PROP-0012 and ADR-0014. 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.

package/docs/architecture/README.md

@@ -0,0 +1,114 @@
+# Harness architecture specification
+
+**Status:** binding. **As of:** 2026-10-21, checked against `src/` on branch `harness2`.
+
+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 | — |
+| [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 on every page, in code and in the data layout.
+
+| 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. |
+| **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 Harness` 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. |
+| 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. |

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).