@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/proposals/PROP-0052-terminal-refine-and-variant-switch.md

@@ -0,0 +1,111 @@
+---
+id: PROP-0052
+title: Refine from the terminal, version checkpoints, and switching a conversation's variant
+status: Implemented
+created: 2026-10-30
+updated: 2026-10-30
+affects: [INV-VAR-4, INV-RUN-1, INV-REF-1, INV-REF-2, INV-PRM-1, 02-sessions-and-runs.md, 03-variants.md, 04-prompt.md, 05-refinement.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity, ADR-0065, ADR-0066]
+---
+
+# PROP-0052: Refine from the terminal, version checkpoints, and switching a conversation's variant
+
+## Problem
+
+The harness has the whole Harness² method (page 05) and versioned variants (page 03), but a person
+in the terminal could not use them in the loop they work in:
+
+- Refinement needed a task file (`xagent refine run --task`), and its executions started from a copy
+  of a source folder. A request a person had just made in their repository could not be replayed.
+- A person could not say where to look. Improvers read every trajectory with no focus, even when the
+  person already knew the agent's weak spot.
+- The terminal showed versions but could not restore one, name one, or take back one component
+  from an earlier version.
+- `INV-VAR-4` pinned a conversation's variant for its whole life: an adopted improvement reached only
+  a new conversation.
+- A version did not say which model it was tuned on, although a variant tuned for one model can
+  hurt another.
+
+## Proposal
+
+**Checkpoints (page 03).** A scope gains tags, `name → fingerprint` in `tags.json`: labels that
+can move, never versions (`INV-VAR-3` holds). A reference is a fingerprint, a unique prefix, a tag,
+or `head`. `revertComponents` makes a new version from the head with chosen components taken from
+an earlier version; a selector is a component (`c4`, `toolGuidance`) or one item by path prefix
+(`skills/review`). It commits through the validator like any edit. A version made by adopting a
+refinement records `tunedFor: { model }`, the model its execution ran on.
+
+**Switching a conversation's version (ADR-0065).** `INV-VAR-4` changes: a later turn of a
+conversation uses the conversation's selected version, which changes only by the person's action
+(adopt, restore, revert, or choosing a version) and only at a turn boundary. The terminal frontend
+receives its compiled prompt, skills and plugins at launch, so a switch restarts the frontend on
+the chosen version and resumes the same native conversation, through the relaunch path the account
+switch already uses. Every run still pins one version for its whole life (`INV-RUN-1` unchanged);
+the prompt pack is compiled again for the new version, which costs the provider cache once.
+
+**Turn snapshots (ADR-0066).** At the start of each turn a person types in a git repository, the
+harness records `workspaceSnapshot: { repo, commit, omitted? }` on the run: a commit made through a
+throwaway index from tracked edits and bounded untracked files (5 MB a file, 100 MB, 10,000 files),
+with the working tree, the real index, HEAD and refs untouched. It is bounded to two seconds; a slow
+or failed snapshot records nothing and the turn goes on.
+
+**Replay and guidance (page 05, ADR-0066).** `refine.fromRun` builds a task from a recorded turn
+or a session's latest typed turn: its request text, the variant scope it ran, and its snapshot as
+`task.workspace`. The default `RefineHost` prepares each execution as a `--shared` clone of that
+snapshot in a temporary folder, so the person's repository gains no worktree, ref or file. A task
+may carry `guidance` (at most 2,000 characters, refused when it names measurement): a focus block
+in the INV, DOM, aggregate and compose missions that directs attention, not conclusions, and keeps
+`KEEP_BASE` valid. It never reaches the selector or the reflector. The budget identity is unchanged.
+
+**Terminal.** `/refine [--k N] [--mode m] [--model id] [--executor-model id] [guidance]` shows the
+request, focus, run count and models, asks for confirmation, then runs in the background with a
+status item; `/refine status | stop | review`. Review lists every candidate with the selector's pick
+marked, shows its changes and output, and adopts any one (optionally tagging it), then switches the
+conversation. Task runs default to this chat's model. `/variant` lists versions and offers switch,
+restore, compare, tag and take-components; `/variant use|restore|tag|untag|diff|revert` are the
+typed forms.
+
+## Surfaces
+
+Every capability is a Harness method (`variants.tag`, `variants.untag`, `variants.tags`,
+`variants.resolve`, `variants.revert`, `refine.fromRun`, `refine.candidateDiff`,
+`refine.candidateOutput`, `refine.adopt` with `tag`) with a terminal surface (`/variant`,
+`/refine`). The App's `/refine` and `/variant` open its Harness screen for now; replaying a turn
+from the App and switching an App conversation's version are App follow-ups (PAR-004).
+
+## Alternatives
+
+- **Hot reload inside the running frontend.** Pi's `reload` re-reads the paths the frontend was
+  launched with, and the harness refuses a changed variant there by design. Restarting on the
+  version reuses a tested path and keeps the conversation.
+- **Follow the head automatically.** A head moved by another client or another terminal would
+  change this conversation under the person. Only this session's own action switches it.
+- **Replay from the current folder.** The agent already did the work, so the answer would be in the
+  workspace. A HEAD worktree loses uncommitted work. The snapshot is the only honest start.
+- **Register a git worktree for each execution.** It writes into the person's repository; a shared
+  clone only reads its object store.
+- **Let guidance steer the selector.** A person's hunch would then outvote the evidence; the blind
+  selector stays answer-free (`INV-REF-2`).
+- **Do nothing.** Refinement stays a batch tool nobody runs on their real work.
+
+## Consequences
+
+- Run records gain the optional `workspaceSnapshot`; version records the optional `tunedFor`;
+  lineage rows carry `tags`. Existing readers ignore the new fields.
+- A git repository used with the harness accumulates unreferenced snapshot objects, which git's
+  garbage collection removes in time.
+- A terminal's harness session id changes when it restarts on another version; the native
+  conversation stays, and `refine.fromRun` also finds a turn by its native session.
+
+## Migration
+
+None. Old runs have no snapshot and cannot be replayed; old versions have no tags or `tunedFor`.
+Removing the feature leaves the extra fields unread.
+
+## Checks
+
+Store tests (tags, references, revert, `tunedFor`), snapshot tests (tree, index and HEAD untouched;
+racy same-second edits; bounds), replay-host tests (clone leaves the repository alone; deletions
+and new files reproduced), mission tests (guidance in improver and composer missions only, in both
+modes, with the budget identity), terminal control tests, and a standalone test that a switch
+restarts on a version that is not the head. `npm run typecheck`, `npm test`, `npm run prove`, and the
+App's checks.

package/docs/architecture/proposals/README.md

@@ -0,0 +1,123 @@
+# Architecture proposals
+
+Proposals are optional design records for changes to contracts, invariants, layer boundaries,
+extension points, or storage layout in [the specification](../README.md). They may be written before
+or alongside implementation, but do not gate code or spec changes. When a proposal is created, add
+it to the index and update its status as the work progresses.
+
+## Status
+
+| Status | Meaning |
+|---|---|
+| `Proposed` | A draft design record; implementation status is tracked separately. |
+| `Accepted` | The user approved the design. Approval is not a prerequisite to implementation. |
+| `Implemented` | Code and spec pages match the proposal. Link the commit or ADR. |
+| `Rejected` | The user declined it. The file stays as a record. |
+| `Withdrawn` | The author dropped it before review. |
+
+## Index
+
+| ID | Title | Status | Affects | Date |
+|---|---|---|---|---|
+| [PROP-0001](PROP-0001-reporting-section.md) | A built-in Reporting section that shapes the final reply | Implemented | INV-PRM-2, 04-prompt.md | 2026-10-21 |
+| [PROP-0002](PROP-0002-retain-rollout-workspaces.md) | Opt-in retention of each refinement execution's workspace | Implemented | INV-REF-1, 05-refinement.md, 10-server-protocol.md, 12-storage.md | 2026-10-21 |
+| [PROP-0003](PROP-0003-executor-settings.md) | Name the model and account of refinement's executions on refine.start | Implemented | 05-refinement.md, 10-server-protocol.md | 2026-10-21 |
+| [PROP-0004](PROP-0004-flexible-reporting-guidance.md) | Flexible final-reply guidance with an optional human-inspection heading | Implemented | INV-PRM-2, 04-prompt.md, ADR-0007, ADR-0008 | 2026-10-21 |
+| [PROP-0005](PROP-0005-xharness-cli-name.md) | Rename the published CLI command to xharness | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0009 | 2026-10-22 |
+| [PROP-0006](PROP-0006-run-checklist.md) | A run checklist the model writes, recorded as a run event | Implemented | 02-sessions-and-runs.md, 06, 07, 10-server-protocol.md | 2026-10-22 |
+| [PROP-0007](PROP-0007-run-continuation.md) | Continue a stopped run as a new run with the same pins | Implemented | INV-RUN-4, INV-RUN-10, 00-overview.md, 02-sessions-and-runs.md, 10-server-protocol.md | 2026-10-22 |
+| [PROP-0008](PROP-0008-lessons-from-runs.md) | Opt-in lessons from finished runs, kept in the Wiki | Implemented | INV-MEM-2, 02, 06, 08-memory-and-history.md, 12-storage.md, ADR-0010 | 2026-10-22 |
+| [PROP-0009](PROP-0009-foundation-and-variants.md) | Name the fixed half the foundation and the mutating half the variant | Accepted | INV-TREE→INV-VAR, new INV-FND-1/2, 00, 03, 05, 10, 12, ADR-0011 | 2026-10-22 |
+
+| [PROP-0010](PROP-0010-session-names.md) | Agent-managed native session names | Implemented | 02, 04, 07, 11 | 2026-10-22 |
+
+| [PROP-0011](PROP-0011-doctor.md) | Readiness diagnostics and explicit live probes | Accepted; implementation in working tree | INV-EXT-1/4, INV-GATE-1, INV-TUI-4, 01, 07, 09, 10, 11 | 2026-10-22 |
+
+| [PROP-0012](PROP-0012-release-baseline.md) | Public 1.0.0 distribution and generic browser ownership | Accepted; candidate implementation | INV-BND-2, 00, 07, 11, 13 | 2026-10-22 |
+
+| [PROP-0013](PROP-0013-resource-browser.md) | Unified terminal resource browser | Implemented; working tree verified | 03, 06, 09, 11 | 2026-10-22 |
+
+| [PROP-0014](PROP-0014-fullscreen-browser-tabs.md) | Full-screen browser with persistent section tabs | Implemented; working tree verified | 11, terminal-tui.md | 2026-10-23 |
+
+| [PROP-0015](PROP-0015-one-capability-surface.md) | One capability surface: the terminal and every host offer the same capabilities | Accepted | INV-BND-2, new INV-PAR, 00, 11, 14, AGENTS.md | 2026-10-23 |
+
+| [PROP-0016](PROP-0016-managed-worktrees.md) | Managed git worktrees in the terminal and every host | Harness/terminal in 4.0.0 candidate; App create integration, remaining actions PAR-012 | INV-BND-2, D-5, INV-STO-3, INV-SRV-1, 00, 02, 10, 11, 12, 14 | 2026-10-23 |
+
+| [PROP-0017](PROP-0017-page-annotations.md) | Page annotations captured in the headed browser or a host's web view | Harness/terminal in 4.0.0 candidate; App source pending native-gesture acceptance | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+
+| [PROP-0018](PROP-0018-annotation-queue-and-app-targets.md) | Inspector-style page notes, a fix queue to the agent, and app windows as capture targets | Harness/terminal in 4.0.0 candidate; App source present, native WKWebView acceptance pending | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+| [PROP-0019](PROP-0019-contextual-side-questions.md) | Harness-owned contextual side questions across surfaces | Implemented; working tree verified | INV-RUN-1/3/5, INV-GATE-1, INV-PLG-1/5, INV-CAP-1, INV-SRV-1/2, INV-PAR-1/2, 02, 04, 06, 07, 10, 11, 12, 14, ADR-0023 | 2026-10-24 |
+| [PROP-0020](PROP-0020-builtin-feature-plugins.md) | Built-in feature modules and namespaced plugin commands | Implemented; included in 4.0.0 candidate | INV-PLG-5/6, INV-TUI-2/7, INV-SRV-1, 06, 11, 13, 14 | 2026-10-24 |
+| [PROP-0021](PROP-0021-command-namespaces-and-duplicates.md) | Required built-in commands and duplicate command suppression | Implemented | INV-TUI-7, INV-PAR-1, 11, 14, ADR-0021 | 2026-10-24 |
+| [PROP-0022](PROP-0022-plan-only-questions.md) | Keep question tools available only in interactive plan mode | Implemented | INV-RUN-8, 02, 04, 06, 07, 11, 14, parity, ADR-0022 | 2026-10-24 |
+| [PROP-0023](PROP-0023-xagent-cli-name.md) | Rename the published CLI command to xagent | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0024 | 2026-10-24 |
+| [PROP-0024](PROP-0024-question-sketch-previews.md) | Add bounded ASCII sketch previews to question choices | Implemented; working tree verified | INV-RUN-3, INV-PAR-1/2, 02, 10, 11, 14, parity, App question contract and plan-mode docs, ADR-0025 | 2026-10-24 |
+| [PROP-0025](PROP-0025-contextual-question-wireframes.md) | Strict question columns and contextual ASCII wireframes | Implemented; working tree and isolated fixtures verified | INV-RUN-3, INV-PAR-1/2, 02, 11, 14, terminal-tui.md, parity, ADR-0026 | 2026-10-24 |
+
+| [PROP-0026](PROP-0026-connected-sketch-display.md) | Connect structural sketch lines in the terminal display | Implemented; working tree and isolated fixtures verified | 11, 14, terminal-tui.md, parity, ADR-0027 | 2026-10-24 |
+| [PROP-0027](PROP-0027-xingular-agent-product-identity.md) | Use Xingular Agent as the default Harness product identity | Accepted; implemented and verified | INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md, terminal-tui.md, ADR-0028 | 2026-10-24 |
+| [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
+| [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
+| [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+| [PROP-0031](PROP-0031-plugin-command-owner-namespaces.md) | Namespace plugin commands by owner | Implemented; Harness and App checks passed | INV-TUI-7, 06, 11, 14, terminal-tui.md, README.md, ADR-0021, ADR-0031 | 2026-10-25 |
+| [PROP-0032](PROP-0032-planning-quality.md) | Evidence-grounded planning with read-only research delegation | Implemented; live model pilot pending authorization | INV-RUN-8, INV-GATE-3, INV-CAP-1, 02, 06, 07, 14, parity, ADR-0033 | 2026-10-25 |
+| [PROP-0033](PROP-0033-compaction-plan-checkpoints.md) | Rehydrate bounded run checkpoints after compaction | Accepted; implemented | INV-PRM-1/4/10, INV-RUN-8/12, 02, 04, 11, 14, ADR-0032 | 2026-10-25 |
+| [PROP-0034](PROP-0034-conversation-fast-mode.md) | Conversation-scoped provider fast mode | Proposed | INV-RUN-1/3, INV-PAR-1/2, 02, 09, 10, 11, 12, 14, parity, App thread runtime settings | 2026-10-25 |
+| [PROP-0035](PROP-0035-retain-subagent-status.md) | Retain terminal subagent status until the next run | Implemented; initial PTY failure resolved; full verifier passed at three sizes (2026-11-19) | 11-terminal.md, terminal-tui.md | 2026-10-25 |
+| [PROP-0036](PROP-0036-first-class-harness-commands.md) | First-class Harness terminal commands | Implemented | INV-PLG-10, INV-TUI-7, 06, 11, 14, terminal-tui.md, parity, ADR-0034 | 2026-10-25 |
+| [PROP-0037](PROP-0037-workspace-write-boundary.md) | Default filesystem writes to the active project workspace | Implemented | INV-GATE-1/3/8, INV-RUN-1, INV-TUI-8, 02, 04, 07, 10, 11, 12, 14, parity | 2026-11-19 |
+| [PROP-0038](PROP-0038-annotate-open-shadow-roots.md) | Annotate inside open shadow roots | Implemented | 13-world-tools.md, note target, PROP-0017, PROP-0018, parity | 2026-10-25 |
+| [PROP-0039](PROP-0039-workspace-boundary-hardening.md) | Harden workspace writes against inode escapes and unverified retries | Accepted; implementation validated on macOS, Linux validation pending | INV-GATE-3/8, INV-TUI-8, 02, 07, 11, 14, parity | 2026-10-26 |
+
+| [PROP-0040](PROP-0040-one-launch-path.md) | One launch path and command contract across front ends | Accepted; implementation in progress | 01–04, 06–07, 10–14, parity | 2026-11-19 |
+| [PROP-0041](PROP-0041-bounded-work-slices.md) | Bounded work slices, a durable checkpoint, and a stall guard for long replies | Implemented; terminal card, App presentation and /slices open (PAR-004) | INV-RUN-2/3/4/12, INV-PRM-1/2/4/5/10, INV-GATE-2, INV-STO-3, INV-PAR-1/2, 02, 04, 07, 10–12, 14, parity | 2026-10-26 |
+| [PROP-0042](PROP-0042-usage-and-provider-limits.md) | Usage analytics and provider limits as a built-in capability | Accepted; implemented | INV-MEM-5/6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02, 06, 08–12, 14, parity, ADR-0037 | 2026-10-26 |
+| [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
+| [PROP-0044](PROP-0044-work-slice-defaults.md) | Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap | Accepted; implemented | INV-RUN-13, 02, 10, 11, PROP-0041 | 2026-10-26 |
+| [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
+| [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039, targeted protections superseded by ADR-0053 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
+| [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
+| [PROP-0048](PROP-0048-simple-annotate.md) | One annotate page, two actions, and easy app attach | Implemented; ADR-0044 | PROP-0018, 07, 10, 11, 13, terminal-tui.md, parity.md | 2026-10-27 |
+| [PROP-0049](PROP-0049-context-attribution.md) | Context attribution: what fills the context window, by foundation, variant and application | Implemented | INV-PRM-6, INV-SRV-1, INV-PAR-1/2, INV-RUN-7, 04, 10, 11, 14, parity.md | 2026-10-28 |
+| [PROP-0050](PROP-0050-run-stop-codes-and-refusals.md) | Run stop codes and refusal evidence | Implemented; ADR-0059 | INV-RUN-3/4, INV-GATE-1, INV-TUI-3, INV-PAR-1 | 2026-10-29 |
+| [PROP-0052](PROP-0052-terminal-refine-and-variant-switch.md) | Refine from the terminal, version checkpoints, switching a conversation's variant | Implemented; ADR-0065, ADR-0066 | INV-VAR-4, INV-REF-1/2, INV-RUN-1 | 2026-10-30 |
+
+Numbers are four digits, start at `0001`, and are never reused.
+
+## Template
+
+Save as `PROP-NNNN-<short-slug>.md`.
+
+```markdown
+---
+id: PROP-NNNN
+title: <one line>
+status: Proposed
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+affects: [INV-..., 02-sessions-and-runs.md, ...]
+---
+
+# PROP-NNNN: <title>
+
+## Problem
+What is wrong or missing today, with evidence (code paths, failures, requests).
+
+## Affected rules
+Each invariant, contract or boundary this changes, by ID, quoted as it stands.
+
+## Proposal
+The new rule and design, stated as the spec page would state it after the change.
+
+## Alternatives
+Other options considered, and why they were not chosen. Include "do nothing".
+
+## Consequences
+What changes for applications built on the harness, for stored data, and for the server protocol.
+
+## Migration
+How existing data, runs and hosts move over. Whether it can be undone.
+
+## Checks
+How the change will be verified: tests, `npm run prove`, the App's checks.
+```

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -4,9 +4,9 @@ title: Own the terminal frontend and keep Pi as the session runtime
 status: accepted
 created: 2026-10-17
 updated: 2026-10-17
-related: []
+related: [ADR-0083]
 supersedes: null
-superseded_by: null
+superseded_by: ADR-0083 (runtime only)
 ---
 
 # ADR-0001 — Own the terminal frontend and keep Pi as the session runtime
@@ -34,7 +34,7 @@ Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatibl
 socket/controller bridge and its final gate. Keep the private control claim in process memory
 across native session replacement, revalidate prepared resource trust before every load, and
 scope native resume/import to the terminal's original working folder. Put unavoidable Pi
-implementation imports in one adapter checked against the pinned 1.2.0 version.
+implementation imports in one adapter checked against the pinned Pi version.
 
 Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
 commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and
@@ -85,3 +85,10 @@ had been reached. The isolated credentials were deleted, the source sign-in rema
 and terminal restoration passed; see the [live evidence](../evidence/terminal-2026-10-17-followup/live-codex/README.md).
 Successful live streaming/tool acceptance and App renderer acceptance remain open. This evidence
 does not establish a released package or exhaustive platform/visual parity.
+
+## Partly superseded — 2026-11-03
+
+[ADR-0083](ADR-0083-one-live-session-runtime.md) moved the terminal's persistent Pi runtime into
+the harness as a live session that every front end reaches through server methods; the client
+terminal is the default. The owned OpenTUI presentation decided here stays. The in-process runtime
+this record describes remains available with `XINGULAR_TERMINAL_RUNTIME=inprocess`.

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -59,10 +59,12 @@ recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async d
 receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
 terminal socket, private controls, native execution and child decision routing. RPC and App host
 regressions cover protocol shapes and ancestry. Tests use disposable storage without external
-model requests. These are working-tree changes, not a publication or live-provider acceptance claim.
+model requests. These changes shipped in `@xingular/harness` 2.0.0 (commit `44471bc`); release does not imply live-provider acceptance.
 
 Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
 build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
 and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
 pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
 user-data-root testing was performed.
+
+Release verification on 2026-10-18: npm 10 clean install, typecheck, 515 tests (two skipped), build and standalone proof passed. GitHub CI passed on Ubuntu and macOS, and the npm publish workflow released version 2.0.0 with provenance. No live provider requests were made during release verification.

package/docs/decisions/ADR-0004-fullscreen-terminal-layout.md

@@ -1,10 +1,11 @@
 ---
 id: ADR-0004
 title: Fullscreen terminal layout with a fixed dock
-status: accepted
+status: superseded
 created: 2026-10-18
-updated: 2026-10-18
+updated: 2026-10-21
 supersedes: none
+superseded_by: ADR-0006
 ---
 # ADR-0004 — Fullscreen terminal layout with a fixed dock
 

package/docs/decisions/ADR-0006-opentui-only-terminal.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0006
+title: OpenTUI is the only terminal frontend
+status: accepted
+created: 2026-10-21
+updated: 2026-10-21
+supersedes: ADR-0004
+---
+# ADR-0006 — OpenTUI is the only terminal frontend
+
+## Context and decision
+
+Harness carried two terminal frontends: the owned Pi terminal and an OpenTUI/Solid frontend behind
+`XINGULAR_HARNESS_TUI=opentui`. The split kept two launch paths, two input and rendering stacks, and
+a fallback that let the terminal start without the OpenTUI build. The requested terminal is the
+OpenTUI one, so the second frontend no longer earns its maintenance and test surface.
+
+`Terminals.prepare()` now always returns Bun with `--conditions=browser` and
+`dist/terminal-opentui.js`. The harness no longer reads `XINGULAR_HARNESS_TUI`, the CLI no longer
+has the internal `terminal-frontend` command, and the legacy frontend modules are removed.
+`TerminalAssets.openTui` is required. `XINGULAR_HARNESS_BUN` still selects the Bun executable.
+
+Bun 1.3.14 or newer is required to build and run the terminal. `npm run build:tui` fails with a
+clear error when Bun is unavailable instead of writing a placeholder or leaving the old frontend.
+`HarnessOptions.piProgram` remains accepted for source compatibility but is ignored.
+
+## Consequences
+
+- There is one launch path, one frontend test surface, and no silent fallback to a different UI.
+- A machine that installs the package must have Bun; Node remains the runtime for the CLI, server,
+  accounts and Pi sessions.
+- The OpenTUI page dialogs, composer, Bash mode and palette are the shipped presentation; the
+  fullscreen layout in ADR-0004 is history.
+- Embedders that construct `TerminalAssets` themselves must provide `openTui`.
+
+## Alternatives considered
+
+Keeping the legacy frontend as an unreachable fallback preserves dead code and two mental models
+for input, rendering and exit behavior. Keeping OpenTUI opt-in preserves the split the change was
+asked to remove. Both were rejected.
+
+## Evidence
+
+Unit and integration tests construct launches and exercise the shared runtime without a real
+provider request. A PTY probe of the standalone command with `XINGULAR_HARNESS_TUI` unset renders
+the OpenTUI home and exits 0; the capture and build hashes are in
+[the console evidence](../evidence/terminal-2026-10-20-console-tui/default-opentui-probe.json).

package/docs/decisions/ADR-0007-reporting-section.md

@@ -0,0 +1,33 @@
+---
+id: ADR-0007
+title: A fixed Reporting section shapes the final reply
+status: superseded
+created: 2026-10-21
+updated: 2026-10-21
+superseded_by: ADR-0008
+---
+# ADR-0007 — A fixed Reporting section shapes the final reply
+
+## Context and decision
+
+Nothing in the compiled prompt said how a run should end, so final replies buried the answer and
+rarely listed files changed, blockers or unverified work. Other harnesses (opencode, omp, Claude
+Code, Codex CLI, kimi-cli) keep final-answer rules in their fixed prompt text; the comparison is in
+[PROP-0001](../architecture/proposals/PROP-0001-reporting-section.md).
+
+The compiler now adds a harness-owned `reporting` section to every pack (`SECTION_ORDER.reporting`
+95, after `tools`; text `REPORTING_GUIDANCE` in `src/prompt/compile.ts`; budget 2,000, never cut,
+never dynamic). It asks for the answer first, then only the parts with content — Files, Blocked,
+Worth a look, Check by hand, Next steps — and Markdown tables where several items share fields. A
+format the person, the application or the current mode asks for takes precedence.
+
+## Consequences
+
+- Every session and every application gets the same reply shape without configuration.
+- The stable prefix changes once; existing sessions miss the provider cache once after upgrade.
+- The model writes the file list. A harness-built list from run events remains possible later.
+
+## Alternatives considered
+
+Default tree text (old trees never get it, refinement could drop it); an application section
+(every application repeats it, the terminal has none); doing nothing. All rejected.

package/docs/decisions/ADR-0008-flexible-reporting-guidance.md

@@ -0,0 +1,41 @@
+---
+id: ADR-0008
+title: Flexible reporting guidance with optional human inspection
+status: accepted
+created: 2026-10-21
+updated: 2026-10-21
+supersedes: ADR-0007
+amended_by: ADR-0073, ADR-0074
+---
+# ADR-0008 — Flexible reporting guidance with optional human inspection
+
+> **Amended by [ADR-0073](ADR-0073-large-reporting-prompt.md):** flexible headings stand; the `reporting` section now names required content blocks and ships worked examples, and the later fixed headings (ADR-0068) are gone. **Amended again by [ADR-0074](ADR-0074-report-content-not-report-blocks.md):** the required blocks are gone too, and human inspection is once more the only optional by-hand block.
+
+## Context and decision
+
+ADR-0007 added stable, harness-owned guidance for final replies, but its fixed heading list could
+produce generic sections and did not clearly identify when a person must perform a check the agent
+could not perform or observe. The user accepted [PROP-0004](../architecture/proposals/PROP-0004-flexible-reporting-guidance.md).
+
+Keep the `reporting` section in the stable system prompt and lead with the outcome, but do not
+require a fixed set of headings. Use only structure that helps explain the work. **Need human
+inspection** is an optional heading for a concrete verification that requires a person because the
+agent could not perform or observe it; state what remains unverified, why, and the specific check
+to make. Do not use it for checks already performed or generic risks. Report only checks actually
+run and their results.
+
+## Consequences
+
+- Every session receives the same concise, flexible reporting guidance.
+- The stable prefix changes once; existing sessions may miss the provider cache once after upgrade.
+- No stored data or server protocol changes. Applications bundling the harness need a rebuild to
+  receive the updated prompt.
+- Cache behavior is measured only with real application requests and the account owner's
+  permission, as required by INV-PRM-8.
+
+## Alternatives considered
+
+- Keep the fixed headings: rejected because they can add generic structure and mislabel follow-up.
+- Remove all guidance about unverified work: rejected because concrete human checks could be omitted.
+- Make **Need human inspection** mandatory: rejected because most tasks do not require a person to
+  perform a check.

package/docs/decisions/ADR-0009-xharness-command.md

@@ -0,0 +1,39 @@
+---
+id: ADR-0009
+title: Publish the Harness CLI as xharness
+status: superseded
+created: 2026-10-22
+updated: 2026-10-24
+related: [PROP-0005]
+supersedes: null
+superseded_by: ADR-0024
+---
+
+# ADR-0009 — Publish the Harness CLI as xharness (superseded)
+
+## Context and decision drivers
+
+The published package used `xingular-harness` as its executable, while the desired short command is
+`xharness`. The CLI already starts the Harness-owned OpenTUI terminal when invoked without a
+subcommand, so the frontend and session runtime need no changes. The npm registry's latest release
+is `3.0.0`; replacing the published executable is a breaking change.
+
+## Decision
+
+Publish `@xingular/harness` `4.0.0` with one binary, `xharness`, mapped to `dist/cli.js`. Do not
+ship `xingular-harness` as a compatibility alias. Keep the package name, `terminal` alias, host
+subcommands, data/state directory names, and `XINGULAR_HARNESS_*` environment variables unchanged.
+
+## Consequences
+
+- Users and scripts that invoke `xingular-harness` must migrate to `xharness`.
+- Running `xharness` with no command opens the existing OpenTUI terminal.
+- No account, data, or state migration is required.
+- The release requires Node 22.19+ and Bun 1.3.14+ for the standalone terminal build/runtime.
+
+## Implementation and verification
+
+- The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
+- CI, the packed-tarball smoke test and the npm publication blocker are recorded in
+  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md). The executable-name decision
+  is superseded by [ADR-0024](ADR-0024-xagent-command.md).

package/docs/decisions/ADR-0010-lessons-in-the-wiki.md

@@ -0,0 +1,31 @@
+---
+id: ADR-0010
+title: Lessons from ordinary runs live in the Wiki, not in trees or the refinement library
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+# ADR-0010 — Lessons from ordinary runs live in the Wiki
+
+## Context and decision
+
+[PROP-0008](../architecture/proposals/PROP-0008-lessons-from-runs.md) adds an opt-in reflection
+after a finished run. The harness already has three places that hold what agents learn: the
+harness tree (c3 memory, instructions), the refinement experience library (whole trees plus a
+lesson, per scope and area), and the Wiki (reference notes).
+
+Lessons from ordinary runs go to the Wiki, under `library/lessons/`, with refinement's lesson
+shape (cue, lesson, evidence, confidence, or nothing).
+
+- The tree changes only through refinement and a person's `adopt`. A lesson from one run is not
+  enough evidence to change instructions every later run receives.
+- The refinement library stores whole trees keyed by task area; an ordinary run has neither.
+- The Wiki is reference material by contract (INV-MEM-1): an agent reads a lesson when it searches,
+  and a person can read, edit or delete it like any note. A lesson that keeps proving itself is
+  evidence for a later refinement, which is where behaviour changes.
+
+## Consequences
+
+- Lessons are visible and editable through every Wiki surface, versioned, and announced to hooks.
+- They do not reach the stable prefix; only a count reaches the dynamic `wiki` pointer.
+- The lesson shape is shared with refinement (`parseExperience`), so the two stay comparable.

package/docs/decisions/ADR-0011-foundation-and-variants.md

@@ -0,0 +1,28 @@
+---
+id: ADR-0011
+title: The harness is a fixed foundation running a mutating variant
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+# ADR-0011 — The harness is a fixed foundation running a mutating variant
+
+## Context and decision
+
+[PROP-0009](../architecture/proposals/PROP-0009-foundation-and-variants.md). The harness lets a
+running host improve the harness itself, so two kinds of part must be told apart at all times: the
+ones that never move during that improvement, and the ones that are meant to.
+
+We call the first the **foundation** and the second a **variant**. A variant is one whole c1–c8
+tree for one scope. The foundation decides what a variant may contain and how it runs; a variant
+decides what the agent is told and may load. Refinement edits a copy of a variant, and only a
+person's `adopt` makes it the head.
+
+## Consequences
+
+- Specs, code, storage and the protocol use the two words (`variants/`, `variants.*`,
+  `VariantChoice`). `INV-FND-1` and `INV-FND-2` state the one-way rule.
+- The same split names the prompt-level design in DESIGN-0001 (foundation text and the adapting
+  surface).
+- Breaking release (5.0.0). Stored data is migrated on `open`.
+- The improver prompts keep the Harness² paper's wording, so the method is unchanged.

package/docs/decisions/ADR-0012-native-session-names.md

@@ -0,0 +1,34 @@
+---
+id: ADR-0012
+title: Agents name their own native Pi sessions
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+related: [PROP-0010]
+---
+
+# ADR-0012: Agents name their own native Pi sessions
+
+## Context
+The terminal already supports manual native Pi session names. The user requested agent
+creation and revision, with a six-word limit and a name after the working metrics, in all
+Harness execution paths. The user approved this implementation plan.
+
+## Decision
+A shared foundation tool binds to the current native session and uses Pi session-info
+history as the only writer and source of truth. The normal gate and capability selection
+apply. Plan mode permits naming as session metadata maintenance. Fixed tool guidance asks
+the agent to name work early and rename on objective changes; no changing name enters the
+system prompt. The terminal refreshes through the existing native metadata event.
+
+## Alternatives
+A separate model call adds latency and cost. Separate title storage duplicates native
+metadata and requires synchronization. Manual-only names do not meet the requested behavior.
+
+## Consequences and evidence
+No migration or new host RPC is needed. The agent chooses when to invoke the tool, so
+actual naming frequency depends on model compliance. Manual names can be revised by the
+agent. Tests in `src/tools/sessionName.test.ts`, `src/sessions/sessions.test.ts`, and the
+terminal lifecycle, runtime, working-line and application tests cover the contract.
+Implementation and verification status are tracked in
+[PROP-0010](../architecture/proposals/PROP-0010-session-names.md).

package/docs/decisions/ADR-0013-doctor.md

@@ -0,0 +1,27 @@
+---
+id: ADR-0013
+title: Evidence-based diagnostics with opt-in live probes
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+
+# ADR-0013 — Evidence-based diagnostics with opt-in live probes
+
+## Context and decision
+
+[PROP-0011](../architecture/proposals/PROP-0011-doctor.md) records the user-approved plan.
+A configured tool or locally available model is not evidence of a successful request.
+`/doctor` therefore checks readiness offline and labels live verification separately.
+
+The foundation owns bounded, cancellable diagnostic jobs and validated findings. Tool-provider
+callbacks supply backend-specific evidence using the existing extension point. Live tool calls
+use the production gate and current capabilities. One synthetic model request uses the selected
+account's Pi runtime and records usage in a separate diagnostic run.
+
+## Consequences
+
+Existing providers remain compatible. Unsupported checks are unverified, disabled capabilities
+are disabled, and permission or isolation constraints are blocked. No diagnostic changes an
+account, configuration or permission. Browser tests have a disposable profile and offline page;
+computer input tests require a host-supplied disposable surface. No live tests run automatically.

package/docs/decisions/ADR-0014-public-release-baseline.md

@@ -0,0 +1,22 @@
+---
+id: ADR-0014
+title: A compiled public SDK and explicit 1.0.0 baseline
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+
+# ADR-0014 — A compiled public SDK and explicit 1.0.0 baseline
+
+The user approved [PROP-0012](../architecture/proposals/PROP-0012-release-baseline.md) through the
+release implementation plan. Keep @xingular/harness and the then-current `xharness` executable, use
+Apache-2.0 for original code, publish compiled ESM/declarations, and preserve upstream notices and
+historical releases. The executable-name portion was superseded by [ADR-0024](ADR-0024-xagent-command.md); the other release-baseline decisions remain.
+
+Generic isolated browser execution belongs in the foundation; App browser presentation, tab
+sharing and OS/computer integration remain with the host. No application concept or object is
+introduced into the Harness. Provider diagnostics continue through the existing tool surface.
+
+The 1.0.0 baseline deliberately resets development numbering. The release pipeline publishes
+one tested tarball with provenance and explicitly assigns latest. Registry and unrestricted CI
+verification are mandatory; accepted design and local builds do not prove publication.

package/docs/decisions/ADR-0015-resource-browser.md

@@ -0,0 +1,28 @@
+# ADR-0015 — One terminal browser for resources and discovery
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-22).
+Related: [PROP-0013](../architecture/proposals/PROP-0013-resource-browser.md),
+[source study](../study/tui-resource-browser.md).
+
+## Context
+
+Skills, plugins, Hub items and variant additions have different entry points and misleading
+availability labels. Users need to identify what exists, what this session can use, and what changes later.
+
+## Decision
+
+Use a shared responsive browser with section shortcuts, Installed/Discover views, provenance and
+inspection before management. Join saved configuration with actual runtime resources; never infer
+loaded state from attachment settings or the latest variant head. Keep the loader, gate and service
+ownership intact. Show foundation and variant as different ownership layers.
+
+## Alternatives
+
+Separate pages retain navigation fragmentation. A single combined remote/local list confuses
+installation with availability. A full editor expands the task beyond browse/manage.
+
+## Consequences
+
+The browser adds a protected service adapter and focused navigation state. Resource reads are bounded,
+credentials stay masked, and installing does not activate resources. Existing commands remain shortcuts.
+Implementation and verification evidence belong in the terminal guide, not in this decision record.