@xingular/harness 0.1.7 → 1.0.0

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.

package/docs/doctor.md

@@ -0,0 +1,74 @@
+# Doctor
+
+Run `/doctor` in the Harness terminal. It opens a readiness report for the selected account/model,
+enabled tools, MCP connections, plugins and skills, pinned variant, runtime and storage.
+
+**Local is the default.** It inspects configuration, saved state and resource readability without
+provider requests, token refreshes, browser launch, permission prompts or computer input. A local
+pass does not establish live connectivity. Other accounts show their saved status and timestamp.
+Providers without diagnostics report unverified. Disabled capabilities are not failures.
+
+Press `l` to choose live checks, then review the account/model, destinations, possible charges and
+isolation notice. The model check makes one synthetic request with at most 64 output tokens;
+usage appears on a separate diagnostic run. Web checks fetch example.com and search for “example
+domain”. MCP checks connect/list only. Browser checks use a disposable headless profile and an
+offline synthetic page; configured CDP attachment is blocked. Computer input is blocked unless the
+host supplies a disposable diagnostic surface; the current desktop host supplies readiness only.
+
+`r` refreshes local readiness, `t` retries a selected local check, `c` cancels, and Escape closes
+and cancels pending work. Completed findings survive cancellation. Every finding includes evidence
+and, where useful, a next step. Doctor never signs in, switches accounts, installs, grants access,
+or repairs settings. Findings and jobs are retained in memory until shutdown; live run records
+and usage remain in normal Harness storage.
+
+## Embedding
+
+```ts
+const job = harness.doctor.start({
+  context: { caller: {}, cwd, accountId, model: 'provider/model', tools: ['web_fetch'] }
+})
+const report = harness.doctor.read(job.id)
+harness.doctor.cancel(job.id)
+```
+
+Server hosts use `doctor.start`, `doctor.read`, and `doctor.cancel`. A host must obtain consent
+before setting `mode: 'live'`, `checks`, and `confirmed: true`. Supply an exact variant version and
+capability snapshot when reproducing a pinned run. Exported schemas validate reports.
+
+Tool providers may attach `diagnostics(context)` returning `DoctorCheck[]`. Local callbacks must
+be passive and network-free. Optional live callbacks declare a notice and receive an AbortSignal,
+a separate real run, and a gated `call(tool, input)` helper. Honor cancellation; release owned
+resources. Route all live tool execution through `call`. Each check has a stable unique ID and
+lists the tools it covers. Existing providers need no changes and appear as unverified.
+
+## Working-tree verification — 2026-10-22
+
+| Check | Result |
+|---|---|
+| Focused Harness service, protocol, control-key, gate, offline-account, browser-isolation and terminal tests | 69 passed across 7 files |
+| App computer diagnostics and diagnostic report contract | 7 passed |
+| Harness typecheck and build/standalone proof | Passed |
+| App renderer typecheck and UI consistency | Passed; existing UI baseline remains |
+| App Rust tests | 240 passed, 1 ignored |
+| Full Harness suite | Could not complete successfully in this sandbox: terminal socket creation returns EPERM; other platform-dependent failures were also reported. The stalled full run was stopped after failures. |
+| Full App renderer tests | 590 passed, 2 failed on existing Guide links/headings |
+| Full App sidecar tests/typecheck | Blocked by older tree/HarnessChoice imports and contract expectations against the current variant API; diagnostic tests pass |
+| App layer check | Rejects the in-progress Harness browser implementation, including backend diagnostic callbacks; ownership/specification drift is recorded as D-9 |
+
+No live provider diagnostic or user browser/computer interaction was performed. Browser regression
+tests use injected launchers. The proof uses isolated scripted fixtures. Changes remain uncommitted
+alongside concurrent work; these results do not establish release readiness for the whole workspace.
+
+## Later 1.0.0 candidate preparation — 2026-10-22
+
+The release preparation resolved the earlier App migration, Guide-link and browser-layer blockers:
+the App's 592 renderer tests, 40 sidecar tests, typechecks and layer/UI checks pass. Rust has
+240 passing tests and one ignored test. A focused Harness run covering Doctor, browser diagnostics,
+world tools, terminal command/page behavior and Hub has 100 passing tests. The compiled package's
+SDK, TypeScript consumer, server and local Doctor smoke checks also pass using existing locked
+dependencies. These later results supersede the earlier blocker descriptions for those checks.
+
+Full Harness acceptance remains blocked locally by sandbox socket denial and HEIC encoder system
+query denial; the complete suite is retained as a mandatory two-OS CI gate. Fresh network install,
+registry availability and npm trusted-publisher configuration remain unverified. No tag or package
+has been published during preparation. See the release procedure and external candidate report.

package/docs/experiments/EXP-0001-terminal-input-latency/plan.md

@@ -0,0 +1,81 @@
+---
+id: EXP-0001
+title: Harness terminal input latency
+status: completed
+created: 2026-10-20
+updated: 2026-10-20
+related: [ADR-0001]
+---
+
+# EXP-0001 — Harness terminal input latency
+
+## Question and falsifiable hypothesis
+
+Does replacing the serialized per-change draft queue with a single-flight latest-state publisher
+reduce draft synchronization backlog while preserving the final dirty state, submit ordering, and
+editor behavior?
+
+The hypothesis is that, when draft replies are slower than incoming keys, the treatment will send
+fewer than one control request per key and reduce queue drain time. Full TUI frame p95 should not
+increase materially. The real local control socket is measured separately from the delayed stress
+workload.
+
+## Baseline, treatment and controls
+
+- **Baseline:** `TerminalApplication.syncDraft()` appends one socket request to a promise chain for
+  every editor change.
+- **Treatment:** one in-flight request plus the latest pending dirty boolean. A pending value is
+  always sent after the in-flight request, including when it has the same boolean, because raw
+  terminal input can change controller state independently.
+- **Fixed controls:** same working tree, Node/Vitest versions, 520-character input sequence, 4 ms
+  inter-key timer, synthetic 8 ms draft reply, 120 by 40 terminal dimensions, and test runtime.
+  The full-frame test calls `renderNow()` for each key and intercepts terminal writes.
+- **Behavior controls:** focused application tests cover submit waiting for the empty-draft reply,
+  coalescing to the latest state, and existing editor callbacks; the controller test covers a
+  multiline raw-input/Ctrl+U correction and the send guard.
+
+## Data, sampling and protocol
+
+Run `npm run profile:terminal-input`. It emits nearest-rank p50/p95 samples for editor input/render,
+full TUI layout frames, and 120 real local draft-socket requests. Its application workload types
+`abcdefghijklmnopqrstuvwxyz` 20 times, waits 4 ms between keys, and injects an 8 ms mock reply for
+each draft update. `XINGULAR_PROFILE_TERMINAL_INPUT_RPC_DELAY_MS` changes that injected delay.
+No model or provider request runs.
+
+The full-frame profile measures Harness layout and diff computation up to `ProcessTerminal.write`;
+the write itself is intercepted, and direct `renderNow()` bypasses the TUI's scheduled frame
+throttle. It does not measure terminal-emulator paint or the user's slower computer.
+
+## Versions and environment
+
+- Harness package: 3.0.0; Pi dependency: 1.2.0.
+- Base commit: `24a9390` on `harness2`; profile and product changes were uncommitted in the shared
+  worktree during the runs.
+- Runtime: Node v26.8.2, Vitest 4.1.11, macOS arm64, Apple M2, 8 CPU cores.
+- No random seed is used; the input string and timing controls are fixed.
+- Profile script SHA-256: `fdcc0d901aae87bbd3e72481471b22dd3d55d1d0d7685ffab4b0d5df0486b509`.
+
+## Metrics and success criteria
+
+Primary metric: draft queue drain after the 520-key sequence. Secondary metrics: draft request
+count, full-frame and combined input/frame p50/p95, and real local socket p50/p95. The change is
+useful if it materially lowers queue drain and request count while keeping the final dirty state,
+submit order and focused behavior tests passing. Frame p95 is checked for regressions, but one run
+per variant is not enough to establish a statistically stable p95 difference.
+
+## Risks and stopping criteria
+
+The injected reply delay is intentionally much slower than the measured local socket. The test can
+show backlog behavior under slow replies, but it cannot establish that socket latency causes the
+reported lag on a different computer. Stop optimization if the exact draft or send guard changes,
+or if repeated slow-machine measurements show no meaningful queue or frame improvement.
+
+## Reproduction
+
+From `Harness/`, run `npm run profile:terminal-input`. For the same synthetic stress profile on
+another computer, use the same Node and dependency versions and leave the default delay unchanged.
+Run the focused suite to verify behavior:
+
+```sh
+npm test -- src/terminal/tui/application.test.ts src/terminal/tui/editor.test.ts src/terminal/terminal.test.ts
+```