@xingular/harness 0.1.7 → 1.0.0

package/docs/architecture/proposals/PROP-0006-run-checklist.md

@@ -0,0 +1,68 @@
+---
+id: PROP-0006
+title: A run checklist the model writes, recorded as a run event
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 10-server-protocol.md]
+---
+
+# PROP-0006: A run checklist the model writes, recorded as a run event
+
+## Problem
+
+A run has no structured record of progress. `goal` on a run is opaque text, and plan mode ends
+with a `<proposed_plan>` block that lives only in message text (`sessions/planMode.ts`). An
+application that wants to show "step 3 of 5", and a later run that wants to pick up where an
+earlier one stopped, can only read prose. Every studied peer with long work has a model-written
+list for this: deepseek-harness `todo_write` (whole-list replace, three statuses, a log-only
+session event, replay projection), OpenCode `todowrite`, and Claude Code's descendant of it.
+Gap #2 of `docs/study/feature-gap-review.md`.
+
+## Affected rules
+
+- 02 Contracts, the run-event list (`runEventTypeSchema`).
+- 07 The list of harness tools ("Harness tools: `history_search`, … `ask_user`").
+- 06 `HARNESS_PLUGINS` ("`pi`, `harness`, `subagents`, `wiki`, `history`, `ask-user`, `connected-apps`").
+- INV-PLG-5: anything the model can see is declared by a plugin.
+- INV-BND-2: no application concept — the tool is named "checklist", not "task" or "todo list
+  of tasks".
+
+## Proposal
+
+- New run event `checklist.updated`, payload `{ items: { text, status }[] }`, `status` one of
+  `pending`, `in_progress`, `completed`; at most 50 items of 1–500 characters. The latest event is
+  the whole checklist (last write wins); items have no ids.
+- New harness tool `checklist_write` (`tools/checklist.ts`), given with `ask_user` whenever
+  `harnessTools` is not `false`. It emits through the live run, so the event is validated,
+  persisted and then relayed (INV-RUN-3). It is `readOnly` for the gate: it changes only the
+  run's own record, so plan mode allows it. Its description carries the usage rules (three or
+  more steps, exactly one `in_progress`, complete immediately), following "tool interfaces are
+  where public instruction lives" (study insight 4).
+- New built-in plugin `checklist` declares the tool.
+- `checklistOf(events)` projects the latest list; the server exposes it as `runs.checklist`.
+- Terminal sessions do not get the tool yet.
+
+## Alternatives
+
+- **A side file `runs/<id>/checklist.json`.** A new writer under `runs/<id>/` (INV-RUN-6) and a
+  second source of truth beside the events. Rejected; the event log already replays.
+- **Parse `<proposed_plan>`.** Only plan mode produces it, and it carries no status.
+- **Leave it to the application as a tool provider.** Every application would rebuild the same
+  generic tool, and continuation (PROP-0007) could not read it. Do nothing was rejected for the
+  same reason.
+
+## Consequences
+
+- Applications see one more event kind; hosts that validate event types must accept it.
+- One more tool in every session's default list, after `ask_user`.
+
+## Migration
+
+None: old runs have no `checklist.updated` events and read as an empty list. Removing the tool
+later leaves old events readable.
+
+## Checks
+
+`tools/checklist.test.ts`, `sessions/sessions.test.ts` (default list, plan mode, `harnessTools:
+false`), `plugins/catalogue.test.ts`, `server/server.test.ts` (`runs.checklist`).

package/docs/architecture/proposals/PROP-0007-run-continuation.md

@@ -0,0 +1,80 @@
+---
+id: PROP-0007
+title: Continue a stopped run as a new run with the same pins
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-RUN-4, INV-RUN-10, 00-overview.md, 02-sessions-and-runs.md, 10-server-protocol.md]
+---
+
+# PROP-0007: Continue a stopped run as a new run with the same pins
+
+## Problem
+
+When the process stops mid-run, `open` marks the run `interrupted` (`markInterruptedRuns`) and
+reports only a count. An application that wants to carry on has to:
+
+- find the interrupted runs itself;
+- locate the native history and pass `resume { sessionFile, nativeSessionId }`;
+- remember the account, tree version and capability set the run had, or risk running on a
+  different one (INV-RUN-1 is per run, not per continuation);
+- and the model is told nothing: it does not know it was cut off, which tool call may have half
+  happened, or which approval was never answered.
+
+Gap #4 of `docs/study/feature-gap-review.md`. Every studied peer keeps the same rule as this
+harness — a restart never silently restarts model work — and puts continuation on a durable log
+plus an explicit request (deepseek-harness's session log and checkpoints, OpenHands' requeue in its
+automation layer).
+
+## Affected rules
+
+- **INV-RUN-4** "A restarted harness never restarts model work. On `open`, runs left active are
+  marked `interrupted` unless another live process owns them (`owner.json`). Recovery of a
+  subagent needs the same account, caller, working folder and history branch."
+- **INV-RUN-10** lists the runs that may not carry an initial Bash command.
+- 02 Contracts; 10 `runs.*`, `sessions.run`; 00 lifecycle step 2 (`Recovery`).
+
+## Proposal
+
+- INV-RUN-4 keeps its first sentence and gains: continuing is always a new run the application
+  asks for with `continueFrom`; it pins the earlier run's account, tree version and capability
+  set, and the earlier run's record is never reopened.
+- `Recovery.interruptedRunIds: string[]` beside the existing count.
+- `continuationOf(root, runId, sessionDir?)` → `Continuation` (`sessions/continuation.ts`), served
+  as `runs.continuation`. It is a projection of what is already stored: `run.json`,
+  `events.jsonl` (checklist from PROP-0006, pending decisions, last tool), `capabilities.json`,
+  `subagents.json`, and the native history in `sessionDir`. No new file is written.
+- `SessionRunInput.continueFrom` (run id): the run is refused with `continuation_unavailable` when
+  the earlier run cannot be continued, and with `continuation_mismatch` when the caller names a
+  different session, history, account or tree. Otherwise the input is filled from the earlier
+  run and a dynamic `continuation` section (order 26, budget 2000) tells the model where it
+  stopped, what its checklist was, which tool call's effect is unknown, and what to ask again.
+  It is a context update, never the stable prefix (INV-PRM-2), and is withdrawn on the next run.
+- INV-RUN-10 adds "continuing" to the runs that may not carry an initial Bash command.
+
+No application concept is named. The requeue policy — which interrupted runs to continue, when,
+and whether to ask a person — stays with the application.
+
+## Alternatives
+
+- **Restart interrupted runs on `open`.** Breaks INV-RUN-4, spends tokens nobody asked for, and
+  repeats side effects. Rejected.
+- **Record the history file path in `run.json`.** Would remove the `sessionDir` argument, but
+  changes the stored record; the caller already owns and passes `sessionDir`.
+- **Do nothing.** Each application re-derives the pins, and the model resumes blind.
+
+## Consequences
+
+- Hosts see one more `Recovery` field, one more method, one more `sessions.run` input and two new
+  error codes.
+- A continued run is an ordinary run with `resumedFromRunId` set.
+
+## Migration
+
+None. Runs interrupted before this change can be continued too: everything is derived from what
+was already stored.
+
+## Checks
+
+`sessions/sessions.test.ts` ("continuing a run that stopped"), `sessions/runStore.test.ts` (ids
+returned), `server/server.test.ts` (`runs.continuation`), `npm run prove` (startup changed).

package/docs/architecture/proposals/PROP-0008-lessons-from-runs.md

@@ -0,0 +1,80 @@
+---
+id: PROP-0008
+title: Opt-in lessons from finished runs, kept in the Wiki
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-MEM-2, 02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 08-memory-and-history.md, 12-storage.md, ADR-0010]
+---
+
+# PROP-0008: Opt-in lessons from finished runs, kept in the Wiki
+
+## Problem
+
+The harness learns from evidence only inside refinement: the experience library holds a cue and
+a lesson per adopted tree, written by a reflector that never sees an answer (page 05). Ordinary
+runs teach nothing to later ones unless an agent with `wiki_write` decides to write a note. Gap
+#5 of `docs/study/feature-gap-review.md`: OMP runs background extraction and consolidation into
+`MEMORY.md` and lessons (capped at about 100 × 2,000 characters); harness² keeps lessons with a
+strict shape (cue = shape of situation, lesson = checkable operation, `NO_ENTRY` when the record
+shows no contrast, never task facts). Nothing in the Wiki is written in the background today.
+
+## Affected rules
+
+- **INV-MEM-2** "The harness is the only writer of the Wiki and of run records. An application
+  reads them and writes notes only through harness methods (`wiki.*`)." It does not name the
+  writers inside the harness; this adds one.
+- **INV-MEM-1** (unchanged, relied on): the Wiki is reference material, not instructions.
+- **INV-TREE-1** (unchanged, relied on): only the tree shapes an agent.
+- **INV-REF-1, INV-REF-4, INV-REF-5** (unchanged, borrowed): answer-free evidence, never acting in
+  the world, file tools only on a copy of the evidence.
+- 02 triggers the harness reads; 06 first-party plugins; 12 the data layout.
+
+## Proposal
+
+- A first-party plugin `lessons`, off by default, with settings `minToolCalls` (4), `maxLessons`
+  (100) and `maxChars` (2,000). It loads no Pi code; its contribution in a run's frozen
+  capability set is what switches reflection on for that run.
+- `Lessons` (`history/lessons.ts`) listens to the harness's own run listener. A completed,
+  top-level run that is not a `probe`, `improver` or `reflection` run is queued; one reflection
+  runs at a time; the queue is in memory only.
+- The reflection is a `PiImprover` session with trigger `reflection`, read-only file tools, the
+  finished run's account and model, and medium effort. The gate refuses whatever would need a
+  person in a `reflection` run, as it does for refinement.
+- The reply is parsed with refinement's `parseExperience`. A lesson is kept as
+  `wiki/library/lessons/<slug>.md` through `notes.write` (actor `reflection`), so it is versioned
+  and announced like any other note (INV-MEM-3, INV-MEM-4). `SAME <path>` adds a source run to an
+  existing lesson instead of a duplicate. At the cap nothing is written and nothing is evicted.
+- The dynamic `wiki` pointer says how many lessons exist, so agents know to search them.
+- INV-MEM-2 gains: "Inside the harness, the Wiki is written by `wiki_write`, by `wiki.*` methods,
+  and by `Lessons` (actor `reflection`, only under `library/lessons/`, only while the `lessons`
+  plugin is on for the run's caller)."
+
+## Alternatives
+
+- **Write lessons into the refinement library.** That library is keyed by tree scope and task
+  area and stores whole trees (INV-REF-7); an ordinary run has neither a candidate tree nor an
+  area. Rejected.
+- **Write lessons into the tree's c3 memory.** Would change instructions without `adopt`
+  (INV-REF-6, INV-TREE-1). Rejected.
+- **A plugin hook (`history.run.ended`).** Hooks are told, never asked, and cannot run a model
+  (INV-PLG-7). Rejected.
+- **On by default.** Spends tokens after every run. The user chose opt-in.
+- **Do nothing.** Leaves gap #5 to each application.
+
+## Consequences
+
+- Hosts see reflection runs (trigger `reflection`) in run lists and recall, like improver runs.
+- When switched on, each qualifying run costs one extra short model session on its own account.
+- A new folder `<data root>/reflection/` holds reflection sessions' native history and replies.
+
+## Migration
+
+None. Switching the plugin off stops new reflections; kept lessons stay as ordinary notes that a
+person may edit or remove.
+
+## Checks
+
+`history/lessons.test.ts` (filters, `NO_ENTRY`, `SAME`, caps, credential and length refusals,
+queue and close), `prompt/compile.test.ts` (pointer), `plugins/catalogue.test.ts`,
+`terminal/pluginControl.test.ts`. No test makes a model request (INV-BND-6).

package/docs/architecture/proposals/PROP-0009-foundation-and-variants.md

@@ -0,0 +1,78 @@
+---
+id: PROP-0009
+title: Name the fixed half the foundation and the mutating half the variant
+status: Accepted
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-TREE-1..7 (renamed INV-VAR-1..7), INV-BND-4, 00-overview.md, 03-variants.md, 05-refinement.md, 10-server-protocol.md, 12-storage.md, ADR-0011]
+---
+
+# PROP-0009: Name the fixed half the foundation and the mutating half the variant
+
+Accepted by the user's request (2026-10-22): document the harness so that the part that is fixed
+is called the **foundation** and the part that mutates is called a **variant**, in code, storage
+and protocol as well as in prose.
+
+## Problem
+"Harness" meant two things: the package, and the editable "harness tree" that refinement
+improves. A sentence such as "refinement changes the harness" did not say whether the compiler and
+the gate could move. The answer is no, but nothing in the spec said so as a rule, and code, data
+folders and server methods all carried the ambiguous word (`harnesses/`, `harnesses.*`,
+`HarnessChoice`, `harnessScope`).
+
+## Affected rules
+- `INV-TREE-1`…`INV-TREE-7` (page 03): renamed `INV-VAR-1`…`INV-VAR-7`; meaning unchanged.
+- `INV-BND-4`: "Trees, the prompt compiler and Wiki notes are synchronous" now says variants.
+- New `INV-FND-1` and `INV-FND-2` (below).
+- The server method group `harnesses.*` (page 10) and the data layout (page 12).
+
+## Proposal
+1. **Vocabulary.** *Foundation*: the fixed half (Pi hookup, compiler, sessions and the run
+   recorder, gate, accounts, trust, the surface and validator, the refinement method, the extension
+   points, the protocol). *Variant*: one tree of eight components (c1–c8) for one scope. *Head*,
+   *version*, *lineage*, *candidate* and *adopt* keep their meaning and now qualify a variant. The
+   glossary is in the spec index.
+2. **New invariants.**
+   - `INV-FND-1` Only a variant mutates. No edit, improver session or adoption changes foundation
+     code, the surface, the validator or an invariant.
+   - `INV-FND-2` A variant changes only by committing a new validated version; refinement moves a
+     head only when a person adopts. There is no other door.
+3. **Code.** `src/tree/` becomes `src/variant/`. `Tree`→`Variant`, `HarnessChoice`→`VariantChoice`,
+   `TreeTrust`→`VariantTrust`, `readTree`/`writeTree`→`readVariant`/`writeVariant`,
+   `seedTree`→`seedVariant`, `RunRecord.harnessScope|harnessVersion`→`variantScope|variantVersion`,
+   `Materialised.tree`→`Materialised.files`, the `sessions.run` input `harness`→`variant`,
+   `ContextPack.harness`→`variant`, source kind `harness`→`variant`, the built-in plugin `harness`
+   (title Harness)→`variant` (title Variant), error code `harness_invalid`→`variant_invalid`.
+   Unchanged: `RunRecord.harness` (the engine name, `pi`), `PI_SURFACE`, `SurfaceSpec`, the `harness.*`
+   server group (status and methods of the whole harness), and the Pi session-tree UI names
+   (`SessionTreeNode`, `navigateTree`, `/tree`).
+4. **Storage.** `harnesses/<scope>/`→`variants/<scope>/`, `versions/<fp>/tree/`→`…/variant/`,
+   `tree-plugin-trust.json`→`variant-plugin-trust.json`, library `harnesses/<task>/harness/`→
+   `variants/<task>/variant/`, refinement `refine/<id>/harnesses/`→`variants/`.
+5. **Protocol.** `harnesses.*`→`variants.*`, notice `harnesses.changed`→`variants.changed`, the
+   `harness` parameter of `sessions.run`, `context.compile`, `plugins.inventory`→`variant`, the
+   `tree` parameter and field of the former `harnesses.*` methods→`variant`, `treeDir`→`variantDir`.
+6. **Deliberate exception.** The improver prompts and the evidence folder's `harness/`,
+   `base_harness/` names keep the Harness² paper's wording. They are method text; changing them
+   would change refinement and its tests (`INV-REF-3`).
+
+## Alternatives
+- *Docs only, keep the names.* Cheaper, but the ambiguity stays in every API a host reads.
+- *Rename components, not the tree.* Versions and adoption always act on a whole tree, so a
+  component-level "variant" would not match how the system works.
+- *Do nothing.*
+
+## Consequences
+Breaking for hosts: package version 5.0.0. Hosts must call `variants.*`, pass `variant` instead of
+`harness`, read `variantScope`/`variantVersion`, and use plugin id `variant`. No aliases are kept.
+Stored data moves on `open` (below); the prompt text and its stable prefix do not change.
+
+## Migration
+`open()` runs `migrateVariantLayout` (idempotent; never overwrites) and the trust file moves when
+`VariantTrust` is created. Run records written with `harnessScope`/`harnessVersion` still load
+(`upgradeRunRecord`). Finished refinement records under `harnesses/` stay readable and adoptable.
+To undo, rename the folders back and use the previous release.
+
+## Checks
+`npm run typecheck`, `npm test` (including `variant/migrate.test.ts`), `npm run prove`, the demo
+refinement, and the App's and Evaluation's checks after they adopt the new names.

package/docs/architecture/proposals/PROP-0010-session-names.md

@@ -0,0 +1,73 @@
+---
+id: PROP-0010
+title: Agent-managed native session names
+status: Implemented
+created: 2026-10-22
+updated: 2026-10-22
+affects: [02-sessions-and-runs.md, 04-prompt.md, 07-tools-and-gate.md, 11-terminal.md]
+---
+
+# PROP-0010: Agent-managed native session names
+
+## Problem
+Agents cannot currently name their sessions. Pi already stores a native session name,
+and the terminal exposes manual `/name`, but the working line does not show the name.
+
+## Affected rules
+INV-PRM-2: "Changing state never enters" the stable system prompt.
+INV-GATE-1: "Every tool call of every run passes the gate."
+INV-TUI-2: "Pi owns the execution runtime, native history and rich content components."
+The tool inventory and plan-safe metadata operations gain `session_name`.
+
+## Proposal
+Provide `session_name({ name: string })` in terminal and embedded Harness sessions,
+subject to capabilities and the normal gate. Name meaningful work early; revise when its
+overall objective changes, including a manually assigned name. Greetings need no name.
+Agent names are short imperative sentences, at most six whitespace-separated words.
+Normalize whitespace; reject blank names, non-whitespace control characters and terminal
+escapes, or more than six words. Identical names do not append another history entry.
+Plan mode permits naming as session metadata maintenance. Disabled Harness tools and host
+restrictions continue to apply. Each session, including a child, names only itself.
+Pi's native session-info entries are the sole persistence mechanism. No separate model
+request, new run-event schema, or new host RPC is introduced. The terminal renders
+` – <name>` after metrics on the active and retained completion line, outside the verb's
+shimmer, and truncates at the terminal edge. Current names never enter the stable prompt.
+
+## Alternatives
+Do nothing leaves sessions unnamed. A separate title-generation model request adds latency
+and token cost. A Harness side file duplicates Pi's existing authoritative metadata.
+
+## Consequences
+The foundation gains a tool and stable naming guidance. Manual names remain unrestricted;
+agent-submitted names follow the six-word limit. Model compliance determines whether and
+when the tool is called. An embedding host need not change its UI or protocol.
+
+## Migration
+None. Existing native histories and manual names remain valid; names survive reopen and
+continuation through Pi. Removing the tool leaves stored names readable.
+
+## Checks
+Unit and integration tests cover validation, both execution paths, policy, capability and
+plan handling, persistence, isolation and working-line rendering. Run Harness typecheck,
+tests and standalone proof, plus the App compatibility checks.
+
+## Review
+The user selected all Harness sessions, agent revisions of manual names, and early naming
+with objective-change revisions, then approved implementation of the presented plan.
+
+## Implementation and verification
+Implemented in the working tree; see
+[ADR-0012](../../decisions/ADR-0012-native-session-names.md).
+
+- Harness full suite: 825 passed, 3 skipped; subsequent affected suites passed after the
+  final prompt-availability and narrow-line corrections (151 passed, 2 skipped; then 36
+  display/application tests passed). Harness typecheck and the final bundle build passed.
+- Standalone startup proof passed. A real Pi SDK / OpenTUI PTY against a loopback provider
+  completed two naming calls at both 80 and 40 columns. Screen parsing verified the full
+  name at 80 columns and right-side name truncation with intact metrics at 40 columns.
+  Fixtures used disposable account/history folders and no external model or user credentials.
+- App typecheck, UI check, and Rust tests passed (240 passed, 1 ignored). App frontend tests
+  reported unrelated guide-link/heading failures and a streaming performance threshold.
+  The sidecar suite reported existing tree-to-variant API/import mismatches; layer checks
+  reported browser/doctor tool-name violations. These checks are not an all-clear for the
+  App workspace, and no App source was changed for this feature.

package/docs/architecture/proposals/PROP-0011-doctor.md

@@ -0,0 +1,63 @@
+---
+id: PROP-0011
+title: Readiness diagnostics and explicit live probes
+status: Accepted
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-EXT-1, INV-EXT-4, INV-GATE-1, INV-TUI-4, 01-extension-points.md, 07-tools-and-gate.md, 09-accounts-and-connectors.md, 10-server-protocol.md, 11-terminal.md]
+---
+
+# PROP-0011: Readiness diagnostics and explicit live probes
+
+## Problem
+Account status and tool registration do not establish that the selected model or backend works.
+The user approved the `/doctor` implementation plan on 2026-10-22: full readiness coverage,
+terminal plus reusable API, offline inspection by default, selected live probes, pinned account,
+and isolated browser/computer interaction only.
+
+## Affected rules
+- INV-EXT-1: “There are seven extension points.” Optional diagnostic callbacks extend tool providers, not a new surface.
+- INV-EXT-4: “Each Node extension point has a protocol equivalent”. Remote tool registration gains diagnostic metadata and a host readiness callback.
+- INV-GATE-1: “Every tool call of every run passes the gate.” Live probes use that gate and capability resolution.
+- INV-TUI-4: changes through the session socket require the terminal control key. All terminal diagnostics require it, including reads and cancellation.
+
+## Proposal
+A foundation `Doctor` owns in-memory jobs. `doctor.start`, `doctor.read`, and `doctor.cancel` expose
+structured, validated reports. `/doctor` uses these through its protected terminal controller.
+Readiness and live verification are distinguished on every finding. No automatic repair occurs.
+
+Offline account inspection uses a non-refreshing Pi runtime and read-only credential store. It
+never verifies credentials remotely. Live model probes make one bounded synthetic request using
+the selected account/model and write normal usage events on a separate diagnostic run.
+
+Tool providers may attach `diagnostics(context)` to their existing callable function. Each check
+supplies readiness inspection and optionally a declared live probe. `WorldPart` forwards the same
+metadata through the existing provider. Remote registrations declare checks and optional single-tool
+probe recipes; `tools.diagnose` returns readiness data, and probe recipes invoke registered tools
+through the normal gate. Providers without diagnostics remain unverified.
+
+Live tool probes intersect requested and current capabilities, pass the existing scope/authorization
+gate, and never satisfy a required separate per-call approval through batch confirmation. Such calls
+report blocked. MCP diagnostics connect/list only. Browser diagnostics use a disposable launch and
+offline synthetic page; configured CDP attachment is blocked. Computer interaction remains blocked
+when a host cannot provide a disposable test surface.
+
+## Alternatives
+Keep separate status screens (no unified evidence); make every check live (costs and side effects by
+default); add an eighth host surface (unnecessary alongside tool providers); infer health from
+registration (insufficient evidence).
+
+## Consequences
+Public API and protocol gain job methods and report schemas; provider callbacks remain optional.
+Jobs retain partial findings, support cancellation, and are cleared at shutdown. Existing runs and
+stored settings need no migration. Live diagnostics retain real run records and usage; reports
+contain redacted summaries and no raw tool payloads.
+
+## Migration
+None. Existing provider functions remain valid. This change does not relocate tool backends.
+The in-progress World/browser implementation's documentation mismatch is recorded as known drift.
+
+## Checks
+Focused service, browser, terminal-page, scope/gate, protocol and host-adapter tests; Harness
+`typecheck`, `test`, `prove`; App `typecheck`, `test`, `check:layers`, `check:ui`, and Rust tests.
+Real provider or interaction probes require explicit consent and are not part of automated tests.

package/docs/architecture/proposals/PROP-0012-release-baseline.md

@@ -0,0 +1,56 @@
+---
+id: PROP-0012
+title: Public 1.0.0 distribution and generic browser ownership
+status: Accepted
+created: 2026-10-22
+updated: 2026-10-22
+affects: [INV-BND-2, 00-overview.md, 07-tools-and-gate.md, 11-terminal.md]
+---
+
+# PROP-0012: Public 1.0.0 distribution and generic browser ownership
+
+## Problem
+The approved release plan requests @xingular/harness@1.0.0 as a new stable baseline, including
+completed capabilities. Development manifests used 5.0.0 and existing tags use several higher
+versions. Source-only exports fail in ordinary Node consumers. The implemented generic browser
+also disagrees with the earlier categorical ownership rule (known drift D-9).
+
+## Affected rules
+INV-BND-2 currently forbids naming “browser, computer use” as application concepts. A generic
+isolated browser is usable unchanged by other hosts. The App's shared WebKit workspace, tab
+sharing, downloads/uploads, window management and computer bridge remain application behavior.
+
+## Proposal
+Keep the seven extension points. The foundation may provide generic web/browser capabilities,
+with one isolated browser per session, the normal tool gate and no application state. The App
+owns browser UI, user tab-sharing policy, OS integration and computer tools. The layer check
+allows only the generic backend's declared tool catalog; App-only tools remain prohibited.
+
+Publish compiled ESM modules and declarations under the current SDK and subpath interfaces,
+retaining the xharness executable and Bun frontend. Include required resources, licenses and
+notices; exclude tests, source-only build tools and scratch/reference folders. Use Apache-2.0
+for original code, preserving upstream notices. Package version 1.0.0 is an intentional reset,
+not a claim that it sorts above old versions. Preserve old tags and registry versions; set latest
+explicitly after approval and never reuse an existing published version.
+
+## Alternatives
+Keep source-only distribution; postpone the stable baseline; move the reusable browser into
+one host; invent an eighth extension point. These fail the approved release requirements or
+reduce reuse unnecessarily.
+
+## Consequences and migration
+Node consumers can import the package without a TypeScript loader. Current source hosts keep
+their sibling-source integration. Hosts migrate harnesses.* to variants.*, and harness/tree wire
+fields to variant/files as specified in PROP-0009. Existing stored data continues through the
+existing non-overwriting migration. Users on higher historic versions must request 1.0.0
+explicitly or install the latest tag; numeric ranges for higher majors will not select it.
+
+## Checks
+Validate the actual tarball as a Node/TypeScript consumer, server and isolated terminal. Run both
+OS CI jobs, Harness proof, App compatibility checks and license/content checks before publication.
+Registry availability and trusted-publisher settings must be verified; unavailable network is a
+release blocker. Tag pushing and publication require approval of the concrete release candidate.
+
+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/proposals/README.md

@@ -0,0 +1,76 @@
+# Architecture proposals
+
+A proposal is required before any change that alters a contract, an invariant, a layer
+boundary, an extension point, or the storage layout described in [the specification](../README.md).
+The author writes it and stops; the user reviews it. Code and spec pages change only after the
+proposal is `Accepted`.
+
+## Status
+
+| Status | Meaning |
+|---|---|
+| `Proposed` | Written, waiting for the user. Nothing has changed. |
+| `Accepted` | The user approved it. Implement it and update the spec pages in the same change. |
+| `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 |
+
+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-0002-native-subagent-lifecycle.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0002
+title: Native subagent lifecycle in Harness sessions
+status: superseded
+superseded_by: ADR-0003
+created: 2026-10-18
+updated: 2026-10-18
+---
+# ADR-0002 — Native subagent lifecycle in Harness sessions
+
+Superseded by [ADR-0003](ADR-0003-shared-asynchronous-subagents.md), which expands the native
+service to asynchronous execution, reliable delivery, and terminal parity. The earlier decision
+and its rationale are retained below.
+
+## Context
+
+Subagents already used Harness sessions, capability snapshots and run lineage, but their tool
+owned launching and polled run files for completion. A host inferred ownership from session
+names, coupling it to an internal identifier format.
+
+## Decision
+
+`Sessions.spawnSubagent` owns child creation. A live parent's captured launch supplies caller,
+account, model selection, folder, policy context, prompt and capability ceiling. The host or
+model supplies only a complete brief and an optional tool subset. Current capability availability
+and the captured nesting limit further restrict each child. Empty tool subsets stay empty;
+spawning permission is never added back after narrowing. Children start with fresh history,
+without inherited image attachments or request preamble. Existing tool gating applies.
+
+The model tool is an adapter to the same native API exposed over RPC. `RunRegistry.wait` resolves
+on settlement, including failed startup and interruption, without polling or per-call listeners.
+The Harness Subagents plugin attributes the model-visible tool. Opt-in remains a session option;
+`{}` selects the Harness default depth of one. Application organization delegation remains a host
+concern. Consumers resolve ownership from run lineage rather than parsing session IDs.
+
+## Alternatives and consequences
+
+Keeping orchestration in the tool would leave hosts without the same lifecycle contract.
+Moving application organizations into Harness would violate the embedding boundary. A new
+background job manager would duplicate existing run tracking, approvals and interruption.
+The selected change reuses these layers and preserves the synchronous model tool behavior.
+The native API starts children only for live parents in the same Harness instance; it does not
+resume a stopped parent's launch or implement cross-process child management.
+
+## Evidence
+
+Regression coverage is in `src/sessions/sessions.test.ts` and `src/server/server.test.ts`.
+Application host and run-family tests cover nested lineage with opaque session IDs. Verification
+results belong to the implementation handoff; no release or live-provider behavior is claimed.