@xingular/harness 0.1.6 → 1.0.0

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

@@ -0,0 +1,87 @@
+---
+id: ADR-0001
+title: Own the terminal frontend and keep Pi as the session runtime
+status: accepted
+created: 2026-10-17
+updated: 2026-10-17
+related: []
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0001 — Own the terminal frontend and keep Pi as the session runtime
+
+## Context and decision drivers
+
+The requested terminal must reproduce the supported Oh My Pi presentation using capabilities
+Harness already has. An extension can replace a header, footer or editor, but Pi's
+`InteractiveMode` still owns transcript layout, command routing, focus and screen lifecycle.
+That arrangement cannot give Harness full control over those surfaces.
+
+The existing terminal boundary already provides isolated accounts, a compiled prompt, trusted
+resource selection, a session socket and controller, a final tool gate and one writer for run
+records. Retaining that boundary avoids a second authority for authentication or run state.
+
+## Decision
+
+Own the terminal application in `src/terminal/tui/` and run a persistent Pi SDK
+`AgentSessionRuntime` inside the prepared terminal child. Harness owns composition, editor and
+input routing, dialogs, overlays and built-in command dispatch. Pi owns model/tool execution
+and native history. The frontend binds the public extension UI contract in `tui` mode and may
+reuse public rich content components.
+
+Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatible. Preserve the
+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.
+
+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
+verification limits. [NOTICE.md](../../NOTICE.md) preserves the upstream MIT license.
+
+## Alternatives and rejection reasons
+
+- **Only install a presentation extension:** leaves the default interactive frontend in control
+  of transcript geometry, built-in commands and terminal lifecycle, contrary to the requested ownership.
+- **Call `sessions.run` for each prompt:** recreates and disposes the runtime per turn, losing
+  persistent plugin UI/queue state and overlapping terminal controller run accounting.
+- **Replace the execution stack with OMP:** changes tools, model/provider behavior and product
+  capabilities beyond the requested presentation migration.
+- **Fork Pi's complete interactive mode:** introduces a large second implementation of session
+  and terminal behavior, making upgrades and account/governance boundaries harder to review.
+
+## Consequences and risks
+
+Harness must maintain its own command routing, focus, keybindings and extension UI lifecycle.
+The small internal adapter is an explicit upgrade constraint. Native session format and
+account storage stay compatible; cross-folder navigation requires a freshly prepared scope.
+Changes to trusted plugin code require review and reopening the terminal.
+
+This record accepts the architectural choice. Implementation exists in the working tree;
+publication and exhaustive visual/provider/platform parity are not implied. The living page
+records passed focused tests and the pending controlled PTY verification result.
+
+## Implementation and evidence
+
+- [`TerminalApplication`](../../src/terminal/tui/application.ts) owns the screen and input lifecycle.
+- [`runtime.ts`](../../src/terminal/tui/runtime.ts) owns the persistent SDK adapter and scoped navigation.
+- [`piAdapter.ts`](../../src/terminal/tui/piAdapter.ts) contains pinned compatibility imports.
+- [`piExtension.ts`](../../src/terminal/piExtension.ts) retains gate/telemetry integration.
+- [`runtime.socket.test.ts`](../../src/terminal/tui/runtime.socket.test.ts) checks the real isolated SDK/socket boundary without a provider request.
+- [Reference identities, retained REA evidence and verification limits](../terminal-tui.md#verification-and-remaining-limits).
+
+## Verification follow-up — 2026-10-17
+
+The earlier pending-PTY statement above records the state when this decision was written.
+The [living reference](../terminal-tui.md#verification-and-remaining-limits) now records passed
+production PTY scenarios at all three planned sizes, 419 Harness tests, a standalone proof and
+portable OMP/Harness comparison records. The implementation also scopes retained plugin UI
+callbacks and transcript components to a native resource generation, provides frozen runtime
+state, and submits grouped question answers through the existing registry atomically.
+
+The personal Codex live attempt reached the provider but was rejected because its usage limit
+had been reached. The isolated credentials were deleted, the source sign-in remained unchanged,
+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.

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.

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

@@ -0,0 +1,70 @@
+---
+id: ADR-0003
+title: Shared asynchronous subagents with native-history delivery receipts
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: ADR-0002
+---
+# ADR-0003 — Shared asynchronous subagents with native-history delivery receipts
+
+## Context and decision
+
+The owner selected reliable delivery, asynchronous spawn/wait, and one SDK/terminal/App API after
+studying OMP. They chose attached children joined before the parent finishes, async spawning by
+default, availability for every interactive caller within its capability ceiling, and recovery
+only when the user explicitly resumes. This supersedes the blocking tool contract in ADR-0002.
+
+`harness.subagents` owns spawning, selective waits and results. SDK and terminal adapters register
+live, frozen parent context with it; no model argument supplies caller, account or replacement
+launch metadata. The terminal adapter uses its private control key. Children use normal Harness
+sessions, isolated accounts, fresh history, existing gates and capability intersection. The old
+`sessions.spawnSubagent` entry point forwards to the service for compatibility.
+
+A parent reserves each child in `runs/<parent>/subagents.json` through the run store before startup.
+A native branch owner marker is persisted before a real parent accepts spawns. Results are delivered
+at turn boundaries or through explicit blocking tools. Native messages and tool results carry typed
+receipts; only receipts on the selected branch acknowledge delivery. Constructing a delivery draft
+never acknowledges it. Large batches acknowledge only the included children. The final settlement
+hook joins children and injects remaining results; an adapter verification guard refuses successful
+completion if persisted native history still lacks a result. The stable system prefix is unchanged.
+
+On explicit resume, matching owner markers, caller/account/folder/native identity and run lineage
+restore undelivered results. A startup reservation that never opened becomes an interrupted run.
+Existing startup recovery interrupts orphaned active runs. Neither recovery path restarts model
+work. Cancellation settles approvals and questions before waiting for SDK abort, preventing blocked
+child interactions from deadlocking parent shutdown.
+
+Interactive sessions enable the tools by default, `null` disables them, and explicit capability
+sets can exclude them. Unattended callers remain off unless the host explicitly enables them.
+Default nesting remains one, with a maximum of three. There is no new scheduler, reusable-worker
+lifecycle, model routing, workspace isolation system, concurrency cap or family budget here.
+
+## Alternatives and consequences
+
+A tool-owned launcher leaves terminal and SDK behavior divergent. An in-memory delivery flag loses
+results across restart; searching prose for run IDs confuses mentions with delivery. Native-history
+receipts identify persisted context without adding a second acknowledgement store. Run records
+remain the outcome source of truth, while the parent file preserves startup reservations.
+
+The App owns organization delegation and resolves native ancestry for thread routing, tools,
+isolation and connections. Its existing work-budget accounting includes native descendants. Harness
+learns no organizational role or application concept. Native completion records execution outcome;
+it does not certify the child's findings or artifacts.
+
+## Evidence and limits
+
+`subagentService.test.ts` covers selective waits, foreign handles, cancellation, bounded batches and
+recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async delivery, inline
+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 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

@@ -0,0 +1,50 @@
+---
+id: ADR-0004
+title: Fullscreen terminal layout with a fixed dock
+status: superseded
+created: 2026-10-18
+updated: 2026-10-21
+supersedes: none
+superseded_by: ADR-0006
+---
+# ADR-0004 — Fullscreen terminal layout with a fixed dock
+
+## Context and decision
+
+The owned terminal drew its transcript and composer as one flowing list on the main screen. With a
+short transcript the composer sat under the last line and moved down as the transcript grew. Harness
+also kept its own scroll offset, mouse regions and paging, which duplicated the viewport Pi already
+provides in fullscreen.
+
+Harness now uses Pi's fullscreen renderer by default. The welcome and transcript form a scroll view
+that fills the terminal; the dock (working line, queue and notices, widgets, editor and status band,
+footer) sits fixed below it. Pi's `tuiMode`, `fullscreenScrollbar`, `fullscreenWheelScrollLines`,
+`fullscreenCopyOnSelect` and `fullscreenExitOutput` settings are read from the account and honoured.
+`tuiMode: "regular"` keeps the flowing layout on the main screen. When fullscreen ends with
+`fullscreenExitOutput: "transcript"`, the rendered conversation is copied into the normal scrollback.
+
+## Consequences
+
+- While fullscreen is running, the transcript is not in the terminal's scrollback. Mouse capture is
+  on, so terminal drag-selection gives way to the application's selection, which copies on release.
+  These are Pi's defaults and remain changeable in settings.
+- Harness no longer owns scroll state, wheel handling or paging. Those come from Pi's viewport and its
+  `tui.altScreen.*` bindings, and the keyboard list shows the scroll keys only in fullscreen.
+- Regular mode has no Harness-managed scroll position; scrolling there belongs to the terminal.
+- When the screen is short, a long notice shows its first rows and scrolls for the rest. The prompt
+  and status are never clipped; the head of a notice stays readable, so the newest line of a long
+  list may need a scroll.
+- Only `transcript` exit output is implemented. Other values write nothing on exit.
+
+## Alternatives considered
+
+Padding the main-screen output to the terminal height also keeps the composer on the last rows for a
+short transcript. It keeps native scrollback, but Harness would still own its scrolling and mouse
+handling, and the composer would scroll away with the terminal's scrollback once the transcript
+overflowed. That was rejected because it keeps the duplicated code this change removes.
+
+## Evidence
+
+The layout is covered by `src/terminal/tui/screen.test.ts`: the dock stays on the last rows as the
+transcript grows and scrolls, regular mode flows in order, and the exit copy is written with its styles
+reset. The PTY verification of the built CLI is recorded in [the terminal reference](../terminal-tui.md).

package/docs/decisions/ADR-0005-app-provided-oauth-clients.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0005
+title: Application-provided OAuth clients for connected apps
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0005 — Application-provided OAuth clients for connected apps
+
+## Context and decision
+
+Every remote connected app so far authenticated one of two ways: the server registers this app
+dynamically (RFC 7591), or the person registers a client with the provider and pastes its ID and
+secret into Connections. Google's Workspace MCP servers support neither in practice: they have no
+dynamic registration, and requiring every person to create a Google Cloud project before connecting
+Gmail is not a product.
+
+A connection's `oauthClient` now has a third value, `app`: **the application supplies the client**.
+The host does so through one extension point on the harness:
+
+```ts
+export interface AppOAuthClients {
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+```
+
+`HarnessOptions.oauthClients` carries it. Only a connection whose `catalogId` appears in `ids()` can
+use it — a hand-typed connection, a Hub connector recipe, and a plugin template cannot, because none
+of them can name a client the application actually holds. `connections.appClients` reports the ids so
+an application can offer only the connectors it can actually sign in for.
+
+The client is resolved inside `Connections.oauthLoad` and placed in the OAuth state as
+`staticClient`, exactly where a user-registered client goes. `oauthSave` already strips
+`staticClient`, so the client is never written to `connections.json` or the secret store; it is
+re-resolved on each load. Refresh tokens continue to be stored per connection.
+
+## Consequences
+
+- The harness learns no product concept: it knows a catalog entry id, a client, and a sign-in. Which
+  entries an application can serve is entirely the host's answer.
+- A build without a client is a first-class state, not an error: `ids()` is empty, `signIn` refuses
+  with "This connector has no app sign-in in this build", and the application hides those catalog
+  entries instead of offering a dead end.
+- A client secret in a distributed desktop build is extractable, so it is treated as public. The real
+  controls stay Google's consent screen, the requested scopes, and the tool approval gate.
+- One client can serve several catalog entries (five Google servers, one client). Each entry is still
+  its own connection with its own tokens, so signing in to one does not authorize another.
+- The per-user path is untouched: `oauthClient: 'user'` still stores a person's own client in
+  Keychain, and it remains the only route for providers or accounts an application cannot pre-register
+  for.
+- Google's Developer Preview terms, app verification and CASA assessment for restricted scopes are
+  outside this decision; they decide who can use the shipped client, not how it is delivered.

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,38 @@
+---
+id: ADR-0008
+title: Flexible reporting guidance with optional human inspection
+status: accepted
+created: 2026-10-21
+updated: 2026-10-21
+supersedes: ADR-0007
+---
+# ADR-0008 — Flexible reporting guidance with optional human inspection
+
+## 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,38 @@
+---
+id: ADR-0009
+title: Publish the Harness CLI as xharness
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+related: [PROP-0005]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0009 — Publish the Harness CLI as xharness
+
+## 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).

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,21 @@
+---
+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 xharness, use Apache-2.0 for original
+code, publish compiled ESM/declarations, and preserve upstream notices and historical releases.
+
+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.