@xingular/harness 0.1.7 → 1.1.1

package/docs/decisions/ADR-0020-page-annotations.md

@@ -0,0 +1,37 @@
+# ADR-0020 — Page annotations and delivery are Harness-owned
+
+Status: Accepted (owner approved the parity plan and capture workflow, 2026-10-23).
+Related: [PROP-0017](../architecture/proposals/PROP-0017-page-annotations.md),
+[PROP-0018](../architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md),
+[07 Tools and the gate](../architecture/07-tools-and-the-gate.md),
+[13 World tools](../architecture/13-world-tools.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Page annotations and the agent's ability to read or act on them must work in both the standalone
+terminal and embedding hosts. Keeping the note store and tools inside one host would split state and
+behavior; trusting arbitrary page-script output could let a page initiate unintended work.
+
+## Decision
+
+The Harness owns the canonical note store, sharing grants, page-note tools, queue and delivery
+lifecycle, and generic capture contract. The terminal captures in its visible isolated browser; a
+host supplies its own web-view or application-window adapter through the same contract. Capture
+results are trusted only when they come from an isolated script world or the host's own UI; otherwise
+sending requires person confirmation. Page-derived content remains untrusted in the delivered
+instruction. A person controls sharing, queueing, confirmation, and resolution; the agent may mark a
+shared note fixed but cannot resolve it or change grants.
+
+## Alternatives
+
+A terminal-only capture path would not support host web views. Host-owned stores and tools would
+create different behavior and duplicated data. Trusting page content or automatically sending
+unisolated results would grant a page authority it must not have.
+
+## Consequences
+
+Notes and grants have one Harness-owned representation and work through the terminal or a host.
+Hosts retain ownership of native windows and browser UI while using Harness methods for notes,
+sharing, and delivery. The server contract can represent capture targets without naming an
+application.

package/docs/decisions/ADR-0021-required-command-namespaces.md

@@ -0,0 +1,40 @@
+# ADR-0021 — Required built-in commands use the bare namespace
+
+Status: Accepted (owner requested implementation of PROP-0021, 2026-10-24).
+Supersedes: The command-namespace portion of [ADR-0018](ADR-0018-builtin-feature-plugins.md).
+Related: [PROP-0021](../architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+The terminal has a set of required built-in features whose pages are part of normal Harness use.
+Putting their commands behind `/plugin:` made them less direct to use. Separately, built-in and
+loaded extension commands could both appear when their names matched a core command, alias or
+prompt. Duplicate bridge registrations also exposed `/plugin:accounts`, `/plugin:hub`, and
+`/plugin:plugins` beside their existing core commands.
+
+## Decision
+
+Commands owned by a required built-in plugin use the bare terminal namespace: `/subagents`,
+`/trajectory`, `/doctor`, and `/worktree`. Optional built-in plugin commands, currently
+`/plugin:notes` and `/plugin:annotate`, and Pi extension commands remain under `/plugin:<command>`.
+Core commands `/accounts`, `/hub`, `/plugins`, and `/mcp` remain unprefixed.
+
+An existing bare core command, alias, required built-in command, or loaded prompt reserves its
+name. A colliding `/plugin:<name>` is absent from completion/help and direct invocation explains
+which bare command to use. Duplicate extension registrations retain owner-path diagnostics. Remove
+the bridge registrations that duplicate `/accounts`, `/hub`, and `/plugins`.
+
+## Alternatives
+
+Keeping all built-in commands namespaced preserves duplicate entries and makes required features
+less direct to invoke. Unprefixing every built-in plugin command would also change the optional,
+switchable Annotations commands. Suppressing only a fixed list of observed duplicate names would
+allow the same problem to recur as plugins or prompts are added.
+
+## Consequences
+
+Required built-in command metadata determines the namespace used by terminal completion, help and
+dispatch. A third-party extension whose command collides with a bare command or prompt must use a
+different command name to expose both. There is no protocol or storage change.

package/docs/decisions/ADR-0022-plan-only-question-tools.md

@@ -0,0 +1,34 @@
+# ADR-0022 — Question tools are available only in attended plan runs
+
+Status: Accepted (owner requested implementation of PROP-0022, 2026-10-24).
+Related: [PROP-0022](../architecture/proposals/PROP-0022-plan-only-questions.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Ordinary chat exposed the Harness-owned `ask_user` tool, while the terminal also activated its
+single-question `ask_user_question` tool in normal mode. Hiding the required `ask-user` plugin would
+also remove it from plan mode and contradict its required-plugin contract. The callable tool set
+must instead be resolved by run mode.
+
+## Decision
+
+Newly resolved normal runs omit `ask_user` before their capability set is frozen, regardless of a
+wider requested tool list. An attended plan run may receive it, subject to the caller's narrower
+capabilities. Automatic, probe, improver and reflection runs do not receive it. In the terminal,
+normal mode deactivates both question tools; a plan request temporarily enables the registered
+question tools and restores the previous active set on success, error or interruption.
+
+The required `ask-user` built-in remains attached and has no user-facing switch. Approval prompts
+and ordinary assistant text are unaffected. A continuation preserves the earlier frozen capability
+set; if that snapshot includes `ask_user`, an automatic or refinement-triggered continuation is
+rejected with `continuation_mismatch` rather than silently narrowing the snapshot or allowing an
+unattended question.
+
+## Consequences
+
+Normal and plan requests can have different provider tool schemas, so no cache-preservation claim is
+made; measure any provider-cache effect only under `INV-PRM-8`. Existing records and attachments need
+no migration. The App relies on the Harness-resolved tool set and adds no separate preference.

package/docs/decisions/ADR-0023-contextual-side-question-runs.md

@@ -0,0 +1,35 @@
+# ADR-0023: Contextual side questions are Harness runs
+
+**Status:** Accepted  
+**Date:** 2026-10-24  
+**Proposal:** [PROP-0019](../architecture/proposals/PROP-0019-contextual-side-questions.md)
+
+## Context
+
+The terminal and App had separate `/btw` implementations. The terminal used a short, in-memory
+Pi session; the App used a bounded, tracked run. Their answers could not consistently use the main
+run's instructions or public tool evidence, and they had different lifecycle and observability.
+
+## Decision
+
+The Harness owns one side-question service. It creates an independent run with no variant and an
+empty frozen capability set. The service uses a redacted projection of the main run's effective
+prompt, visible transcript, and persisted public events, including tool inputs and results. It
+excludes hidden reasoning and attachment bytes. Context is bounded, credential-like material is
+redacted, and transcript/tool content cannot add permissions. Terminal and host surfaces use the
+same service and ordinary run-event contract.
+
+## Consequences
+
+Side answers are separately recorded and can be inspected with ordinary run history and usage.
+They never enter or steer the parent conversation. No persistent side-thread store or migration is
+needed. The terminal presents a temporary scrollable dock; a host keeps its own presentation. The
+App's read-only native file tools use the operating system's read boundary across absolute and home
+paths; the App's host gate continues to protect edits, writes and shell commands.
+
+## Rejected options
+
+- Keeping a separate in-memory terminal session would preserve different answers and observability.
+- Sending hidden reasoning, images or the main run's tools would expose more than a side answer
+  needs and could let it act independently.
+- Persisting side threads would require retention, deletion and synchronization rules.

package/docs/decisions/ADR-0024-xagent-command.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0024
+title: Publish the Harness CLI as xagent
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0023]
+supersedes: ADR-0009
+---
+
+# ADR-0024 — Publish the Harness CLI as xagent
+
+## Context and decision drivers
+
+The Harness CLI's no-subcommand path starts the standalone OpenTUI terminal. The current executable
+name, `xharness`, is being replaced by the requested shorter product command, `xagent`. The
+published command is part of the package's public interface.
+
+## Decision
+
+Publish `@xingular/harness` with one executable, `xagent`, mapped to `dist/cli.js`. Invoking
+`xagent` without arguments starts the existing OpenTUI terminal. Do not retain `xharness` as a
+compatibility alias. Keep the package name, `terminal` alias, host subcommands, data/state directory
+names, and `XINGULAR_HARNESS_*` environment variables unchanged.
+
+This supersedes ADR-0009's executable-name decision and the `xharness` command-name portion of
+ADR-0014. Other release-baseline decisions remain unchanged.
+
+## Consequences
+
+- Users and scripts that invoke `xharness` must migrate to `xagent`.
+- No account, data, or state migration is required.
+- If `xharness` has already been released, replacing it requires a new major version; this change is
+  intended for the unpublished 4.0.0 candidate.
+
+## Implementation and verification
+
+- The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
+- The implementation and migration notes are tracked in
+  [PROP-0023](../architecture/proposals/PROP-0023-xagent-cli-name.md).

package/docs/decisions/ADR-0025-question-choice-sketches.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0025
+title: Store bounded ASCII sketches with question requests
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0024, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0025 — Store bounded ASCII sketches with question requests
+
+**Accepted by the product owner on 2026-10-24.**
+
+## Context
+
+Choice labels and descriptions do not always communicate a layout or other compact visual
+comparison. Both question surfaces need the same safely bounded representation, and the validated
+`question.requested` event is the existing shared contract through which they receive choice data.
+
+## Decision
+
+- A question may set `uiSketch: true` to enable sketch previews. Each offered choice must then
+  provide its own `sketch`; without the flag, a choice must not provide a sketch.
+- Sketches are literal text of 1–8 LF-separated lines, at most 32 printable ASCII characters per
+  line, with at least one visible character. The complete value is at most 263 bytes. Tabs, CR,
+  control characters, escape sequences and non-ASCII text are invalid. Valid text, including
+  interior blank lines and trailing spaces, is preserved exactly.
+- Harness validates the flag/choice relationship and text bounds before emitting a request. The
+  persisted `question.requested` event may carry the metadata; `question.answered` and
+  `QuestionAnswer` remain unchanged. Older request events remain valid.
+- The terminal and hosts render one shared monospace preview below the choices, following the
+  hovered or focused choice. They render the sketch as text, not Markdown, ANSI or executable rich
+  output.
+
+## Consequences
+
+- The existing event schema and persistence path carry the preview; no event kind, image type,
+  storage file or protocol version is added. No data migration is needed.
+- Hosts mirror the optional schema fields. Surface parity requires the terminal and each host to
+  present the same choice sketches without changing answer semantics.
+- The strict ASCII and dimension limits keep the diagram readable in a 40-column terminal and
+  prevent markup, terminal controls and unbounded content from entering the question surface.
+
+## Implementation and verification
+
+Implemented under [PROP-0024](../architecture/proposals/PROP-0024-question-sketch-previews.md).
+Verification evidence is recorded with that proposal and in the App's implementation-stage log.

package/docs/decisions/ADR-0026-contextual-question-wireframes.md

@@ -0,0 +1,58 @@
+---
+id: ADR-0026
+title: Align question columns and preserve contextual ASCII wireframes
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0025, ADR-0025, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0026 — Align question columns and preserve contextual ASCII wireframes
+
+**Accepted by the product owner on 2026-10-24** through the plan “Fix TUI question columns and sketch previews”. This is foundation work.
+
+## Context
+
+Content-dependent choice rows do not align label and description boundaries. The original 32×8
+sketch limit cannot express contextual UI panels, and a caption plus left rule adds redundant
+preview chrome. ADR-0025 records the original sketch contract and its historical evidence; this
+decision amends its bounds and presentation without replacing the optional sketch/answer model.
+
+## Decision
+
+- Use one measured layout across every choice: marker gutter, one-third label cell, two-cell gap,
+  remaining description cell. Wrap within cells, retain empty description cells, and never stack
+  columns at compact widths. Use `(Rec.)` when the label column is fewer than 14 cells and a compact
+  dock hint below 60 terminal columns.
+- Accept 1–24 LF-separated lines of at most 80 printable ASCII characters each (1,943 bytes
+  maximum), with at least one visible character. Reject tabs, CR, controls, escapes and Unicode;
+  preserve whitespace literally. Both question tools and validated request events use these bounds.
+- Ask models for contextual UI wireframes containing actual panel/table structure and neighboring
+  elements, consistent across alternatives. This is generation guidance, not schema enforcement.
+- Render one shared border-only literal preview without a visible caption or extra left rule.
+  Preserve content without wrapping, reflow or truncation; bounded two-axis scrolling exposes
+  overflow. Hover/focus chooses the preview without changing the staged answer.
+- Bound and vertically scroll the dock body, keeping tabs and answer/action controls outside it.
+  PageUp/PageDown and Ctrl+Home/End scroll that body while the dock is active. Shift+arrows pan the
+  sketch; ordinary arrows keep question/choice navigation. Bring focused choices and notes into view.
+- Terminal and hosts accept the same metadata and preserve literal content. Host presentation may
+  differ, but the expanded contract requires acceptance on both surfaces under INV-PAR-1/2.
+
+## Consequences
+
+Existing sketches and events remain valid without a data rewrite. Readers enforcing the old limits
+must update before accepting larger events; rolling readers back requires avoiding sketches above
+those limits. `uiSketch` still requires a sketch on every choice and forbids sketches when disabled.
+`question.answered`, `QuestionAnswer`, the gate, prompt compilation and storage ownership do not
+change. No image format, event kind or executable rich-output contract is introduced.
+
+## Implementation and verification
+
+The accepted design is [PROP-0025](../architecture/proposals/PROP-0025-contextual-question-wireframes.md).
+Implementation and isolated terminal/host acceptance are recorded in the
+[retained verification](../evidence/terminal-question-wireframes/README.md), including four terminal
+sizes, live resizing, sketch panning, literal persistence and the host's expanded-boundary fixture.
+Earlier PROP-0024/ADR-0025 evidence remains historical; the new evidence does not claim live-model
+diagram quality, every emulator's behavior or native Tauri presentation.

package/docs/decisions/ADR-0027-connected-sketch-display.md

@@ -0,0 +1,60 @@
+---
+id: ADR-0027
+title: Project structural ASCII sketch lines into connected terminal borders
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0026, ADR-0026, ADR-0029, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0027 — Project structural ASCII sketch lines into connected terminal borders
+
+**Design accepted by the product owner on 2026-10-24** with “yes, fix it” after screenshot review.
+This foundation presentation change is implemented and verified in isolated production fixtures;
+see [retained evidence](../evidence/terminal-connected-sketches/README.md).
+
+## Context
+
+ASCII `+|-` table frames appear disconnected in the terminal, and bare hyphen dividers do not
+reach the preview frame. ADR-0026's absolute literal-render promise prevents correcting those
+structural lines without a documented exception. Raw ASCII persistence and shared host metadata
+remain appropriate; the problem is terminal typography, not the question contract.
+
+## Decision
+
+Adopt [PROP-0026](../architecture/proposals/PROP-0026-connected-sketch-display.md). The terminal
+preview in `src/terminal/opentui/sketchPanel.ts` uses a bounded structural display projection:
+
+- Recognized ASCII table-border rows and enclosed vertical table edges become connected
+  box-drawing glyphs. Internal framed tables retain their original widths and positions.
+- Bare standalone hyphen divider rows expand to the larger of the panel viewport width and the
+  original sketch's widest line, joining the outer single-line preview frame with `├` and `┤`.
+- No global substitution: prose, content operators and ordinary pipes remain literal. Unrecognized
+  rows remain literal. Whitespace and geometry remain unchanged except for recognized structural
+  border glyphs and standalone-divider expansion, subject to the high-confidence boundary-cell
+  repair separately specified by [ADR-0029](ADR-0029-normalized-question-wireframe-borders.md).
+- Keep bounded two-axis panning, with no wrapping, reflow, truncation or markup interpretation.
+  Focus, selection, navigation and answers do not change.
+
+The validated source remains at most 80 printable ASCII columns by 24 lines. Persist that source
+literally, including whitespace; never save projected Unicode or divider expansion. No wire/schema
+or answer change is introduced. Hosts may retain literal previews of the same source. INV-PAR-1/2
+require equivalent capability and accepted metadata, not identical structural typography.
+
+## Consequences
+
+This amends only ADR-0026's terminal literal-render requirement and cross-surface typography
+promise; its bounds, raw persistence, layout and answer decisions remain in force. No migration or
+host code change is needed. Reverting the display projection does not affect saved events.
+Historical decisions and verification evidence remain unchanged.
+
+## Verification status
+
+The [PROP-0026 verification](../evidence/terminal-connected-sketches/README.md) covers structural
+recognition, content preservation, four terminal sizes, resizing/panning, original ASCII persistence
+and unchanged answers, alongside Harness and host checks. The later [ADR-0029 verification](../evidence/terminal-wireframe-normalization/README.md)
+covers title-bearing rules and bounded repair of missing or displaced frame edges. Prior PROP-0025
+evidence remains a record of the old presentation. Fixture verification is not owner visual
+acceptance, an every-font guarantee or evidence of live-model diagram quality.

package/docs/decisions/ADR-0028-xingular-agent-product-identity.md

@@ -0,0 +1,56 @@
+---
+id: ADR-0028
+title: Use Xingular Agent as the default Harness product identity
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0027, INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0028 — Use Xingular Agent as the default Harness product identity
+
+The product owner accepted [PROP-0027](../architecture/proposals/PROP-0027-xingular-agent-product-identity.md)
+on 2026-10-24.
+
+## Context
+
+The standalone terminal is Harness-owned, but its welcome and Harness-authored prompt identity used
+the default product name `Xingular Harness`. The requested product identity is `Xingular Agent`,
+with a terminal welcome that presents an orange `X` mark and blue `A G E N T` label. Changing the
+default affects product identity text beyond the welcome, including compiled prompts and Wiki text;
+embedding hosts may need their own name.
+
+## Decision
+
+Adopt PROP-0027:
+
+- Set `DEFAULT_PRODUCT_NAME` to `Xingular Agent`; continue honoring an explicit `productName` from
+  an embedding host.
+- Revise `INV-BND-2` to permit the exact canonical product identity `Xingular Agent` as the
+  default. Continue to prohibit application concepts, application-specific behavior and other
+  application names in Harness code and person/model-visible text.
+- Format a multiword product name in the empty welcome as the first letter of its first word in the
+  orange block mark and the remaining word(s), letter-spaced, in blue. Thus the default shows `X`
+  and `A G E N T`. A single-word name remains the mark without a subline.
+- Keep the centered greeting, tagline, `/help` hint, model/thinking status, composer and status bar;
+  use the existing orange and blue theme accents without adding tokens or changing other surfaces.
+
+## Consequences
+
+- Consumers that omit `productName` see `Xingular Agent` in Harness-authored product identity
+  text. Consumers that supply their own name are unchanged.
+- Existing prompt packs, runs and Wiki notes are not rewritten; newly compiled prompt identity and
+  new Wiki text use the default in effect at creation time.
+- No capability, API, storage layout or wire schema changes.
+
+## Verification status
+
+Implemented and verified on 2026-10-24.
+
+- Harness: `npm run typecheck`, `npm test` (143 files passed; 3 skipped), `npm run build`, and
+  `npm run prove` passed. Focused PTY verification passed at 40x20, 80x24 and 120x40, including
+  the `/help` transition.
+- Xingular Agent: `npm run typecheck`, `npm test` (566 renderer and 67 sidecar tests passed),
+  `npm run check:layers`, and `cd src-tauri && cargo test` passed.

package/docs/decisions/ADR-0029-normalized-question-wireframe-borders.md

@@ -0,0 +1,33 @@
+---
+id: ADR-0029
+title: Normalize high-confidence question wireframe borders in the terminal preview
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0028, ADR-0026, ADR-0027, INV-PAR-1, INV-PAR-2]
+---
+
+# ADR-0029 — Normalize high-confidence question wireframe borders in the terminal preview
+
+## Context
+
+The terminal displays bounded, model-authored ASCII sketches. The existing connected-glyph projection misses text-bearing top rules and rows with missing or misaligned side edges. The raw source remains the right shared contract, but its terminal display needs a narrowly constrained frame-repair rule.
+
+## Decision
+
+Adopt [PROP-0028](../architecture/proposals/PROP-0028-normalize-question-wireframes.md). The terminal may normalize only high-confidence, explicitly framed sketch boundaries:
+
+- Recognize title-bearing border rows and establish outer columns from matched frame rules.
+- Align a boundary character only across whitespace, or fill a missing boundary cell only where it is whitespace.
+- Preserve interior text, nested frame geometry, ambiguous rows, and ordinary content literally; no global symbol replacement.
+- Keep the source ASCII byte-for-byte in persistence and retain the existing question schema, answer payload, viewport and panning behavior.
+
+Hosts may continue rendering the same source literally. This decision changes terminal typography only; it adds no capability or host contract.
+
+## Consequences
+
+A valid framed sketch can display connected corners and continuous vertical edges even when its source omitted or misplaced a boundary glyph. Repairs are projection-only and deliberately conservative; ambiguous or content-conflicting rows remain untouched. No migration is required.
+
+## Verification
+
+Use structural unit fixtures and isolated production PTY runs at compact and wide terminal sizes. Verify the displayed topology, panning/resizing, and byte-for-byte source and answer preservation. This does not claim that every emulator/font renders box glyphs identically or that live-model sketches always describe the intended design.

package/docs/decisions/ADR-0030-agent-profiles.md

@@ -0,0 +1,43 @@
+---
+id: ADR-0030
+title: Agent profiles, one checklist per agent, and the subagent roster under the status line
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0029, PROP-0006, ADR-0003, INV-RUN-2, INV-CAP-1, INV-PAR-1]
+---
+
+# ADR-0030 — Agent profiles, one checklist per agent, and the subagent roster under the status line
+
+## Context
+
+People want to start subagents of a known kind, such as a worker that edits and an explorer that
+only reads, and to follow their progress from the terminal. Subagents were copies of the parent
+or instruction-only c5 definitions, the terminal did not register the checklist tool, and the
+roster sat above the composer with a heading and no indication of each child's kind or progress.
+
+## Decision
+
+- Adopt [PROP-0029](../architecture/proposals/PROP-0029-agent-profiles.md): agent profiles are
+  Markdown files (built-in, `<data root>/agents/`, `<project>/.xingular/agents/`, then c5 names)
+  that a spawn resolves by name. A profile narrows tools and plugins and may choose a variant,
+  model and effort. It never widens the parent's capabilities.
+- Progress stays **one checklist per run** (PROP-0006). The parent's list is the plan the person
+  watches. Each child keeps its own list, and the roster shows its `n of m tasks`. There is no
+  shared, claimable task pool.
+- The terminal registers `checklist_write`, shows each write as a checklist block, and the prompt's
+  Progress group asks the model to keep it current because the person follows work from it.
+- The roster sits under the status line after one blank line, with no heading. Each row reads: status
+  mark, profile name in its colour, session name, tasks.
+
+## Consequences
+
+Profiles are a foundation feature, not variant data: refinement does not change them. A project
+can carry profiles in its repository. The App gets the same capability through `agents.*` and
+`RunRecord.profile`; it has no Agents screen yet (parity `planned`).
+
+## Verification
+
+Unit tests for profiles, narrowing, spawn, the monitor, the roster and the Agents page;
+`npm run prove`; and a loopback PTY run that checks the blank row under the status line, the row
+order, and the profile colours.

package/docs/doctor.md

@@ -0,0 +1,80 @@
+# 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.
+
+The report keeps mode, progress, account/model and status counts visible above the findings. Wide
+layouts use aligned Status, Check, Category and Verification columns; evidence and any next step
+appear beneath each finding. Narrow layouts stack those fields. Status colors follow the active
+theme: pass is green, warning/blocked amber, fail red, disabled dim and unverified muted.
+
+`r` refreshes local readiness, `t` retries a selected local check, `c` cancels, and Escape closes
+and cancels pending work. Use Up/Down to scroll by line, PgUp/PgDn or the mouse wheel to scroll by
+page, and Home/End to jump to the first/last finding. 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.