@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/decisions/ADR-0079-phase-led-reporting-guidance.md

@@ -0,0 +1,72 @@
+---
+id: ADR-0079
+title: Phase-led flexible reporting guidance
+status: accepted
+created: 2026-11-02
+updated: 2026-11-02
+amends: ADR-0076 (report phases, reader context, verification honesty, subagent reports and headings)
+related:
+  - ADR-0076
+  - STUDY-0009
+---
+# ADR-0079 — Phase-led flexible reporting guidance
+
+> Amends [ADR-0076](ADR-0076-codex-final-answer-verbatim.md): keep its self-contained, outcome-first
+> report and flexible structure, while strengthening the reader, evidence, heading and subagent
+> guidance based on [STUDY-0009](../study/STUDY-0009-claude-code-reporting.md).
+
+## Context
+
+The study compared Claude Code's external and internal prompt phases with the Harness reporting
+section. It found three useful gaps: the Harness did not explicitly help a reader who has lost the
+thread, did not say directly how to report checks that were not run or failed, and gave subagents no
+caller-facing report contract. The in-flight progress sentence also appeared in both `writing` and
+`reporting`, although `reporting` shapes the final answer.
+
+The user asked for phase-led final-report guidance and frequent Markdown `#` / `##` headings such as
+"What changed", "Checks" and "Things to know", while explicitly rejecting a fixed heading vocabulary.
+
+## Decision
+
+- Keep the final reply self-contained, outcome-first, evidence-led and scaled to the work. Organize
+  the guidance in final-report order: reader and purpose, opening, body, evidence and honesty,
+  person-owned next step when one exists, headings, lists and tables, length, references and
+  formatting, then examples and pre-send review. Follow citation and file-link rules already
+  supplied by the active session or host. Pre-tool narration and in-flight updates remain in their existing prompt section;
+  remove only the duplicate progress-update sentence from `reporting`. Do not add an away-recap
+  surface or numeric word caps.
+- Add the cold-reader test: assume the person may have stepped away and lost the thread; give enough
+  context to pick the work back up and match the explanation to cues about their experience.
+- State verification honestly. Say when a check was not run, never imply that it passed, report
+  failures with relevant output, and state passes plainly.
+- When writing as a subagent, give the caller a concise account of work done and key findings. The
+  caller integrates and relays it. Include absolute paths and useful evidence, snippets only when
+  exact text is load-bearing, and no recap of code merely read.
+- For substantive replies with distinct parts, often use Markdown headings: a `#` title when useful
+  and `##` headings for meaningful sections. Choose labels from the reply's actual content. Examples
+  such as "What changed", "Checks" and "Things to know" are optional wording, not a fixed list or
+  template. Short replies may stay in prose; headings are never forced and empty sections are not
+  added.
+- Revise one worked example to demonstrate a content-specific `#` / `##` structure and retain a
+  short heading-free example. Keep the 12,000-character reporting budget.
+
+## Consequences
+
+- Reporting behavior changes the stable prompt prefix. Existing live terminal sessions retain the
+  pack they started with; new sessions receive the updated text. Cache reuse after the prefix change
+  must be measured only with real application requests and the account owner's permission
+  (INV-PRM-8).
+- No storage, server protocol or tool capability changes.
+- The guidance favors headings for substantial multi-part reports without prescribing section names
+  or forcing headings on simple replies.
+
+## Alternatives
+
+- **Require a fixed set of report headings.** Rejected: the user wants headings chosen for the
+  content, and fixed labels become a template.
+- **Keep reports prose-only unless a heading is requested.** Rejected: substantial reports should
+  use headings often enough to make their parts easy to find.
+- **Move progress updates or add an away recap to reporting.** Rejected: in-flight updates already
+  belong in `writing`, and this harness has no away-recap surface.
+- **Adopt Claude Code's numeric word limits.** Rejected: the study did not establish their quality
+  effect for this Harness.

package/docs/decisions/ADR-0080-fixed-width-question-sketch-canvas.md

@@ -0,0 +1,50 @@
+---
+id: ADR-0080
+title: Use a fixed 80-column canvas for question sketches
+status: accepted
+created: 2026-11-28
+updated: 2026-11-28
+related: [PROP-0026, ADR-0027, ADR-0029, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0080 — Use a fixed 80-column canvas for question sketches
+
+## Context
+
+The shared question-sketch contract permits up to 80 printable ASCII columns, but neither validation
+nor the tool guidance required the model to use that full width. The terminal's display width also
+followed the viewport, so the same sketch could appear at different widths on different terminals.
+A fixed design canvas gives the model room for contextual UI detail and makes terminal previews
+consistent without breaking callers that provide shorter sketches.
+
+## Decision
+
+Ask the model to design detailed `uiSketch` wireframes on a fixed 80-column canvas. This remains
+guidance: preserve the existing validator, which allows sketches shorter than 80 columns and does
+not require trailing spaces.
+
+The terminal projects every valid source sketch to 80 content columns, padding shorter rows and
+extending standalone divider rows to the same width. Keep the outer preview frame no wider than the
+available dock; the content remains horizontally pannable when the canvas does not fit. Keep the
+existing structural-border projection within the canvas. Padding and projected glyphs are display-only;
+source events and answer payloads remain unchanged.
+
+The App may keep its literal ASCII preview and overflow behavior. Both surfaces use the same source
+contract and model guidance; identical preview typography is not required. This amends only the
+viewport-relative canvas and divider sizing in [ADR-0027](ADR-0027-connected-sketch-display.md) /
+[PROP-0026](../architecture/proposals/PROP-0026-connected-sketch-display.md). Their structural
+recognition and persistence rules remain in force.
+
+## Consequences
+
+Short source rows appear padded in the terminal but remain unchanged in history. A model may still
+return a narrower drawing because canvas usage is not schema-enforced. There is no data migration,
+wire-contract change, or answer-payload change.
+
+## Verification
+
+Cover fixed width and padding in unit tests; verify the viewport-bounded frame and horizontal panning
+at compact, standard, and wide PTY sizes. Confirm persisted sketch text and submitted answers remain
+unchanged. Fixture verification does not guarantee every live-model sketch uses the full canvas.

package/docs/decisions/ADR-0081-no-work-slice-budget-by-default.md

@@ -0,0 +1,36 @@
+---
+id: ADR-0081
+title: No work-slice budget by default
+status: accepted
+created: 2026-11-02
+updated: 2026-11-02
+related: [PROP-0041, PROP-0044, ADR-0070, ADR-0075, INV-RUN-13]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0081 — No work-slice budget by default
+
+## Context
+
+PROP-0041 bounded a reply at a number of tool calls and minutes, then handed off, and ADR-0070 and
+PROP-0044 tuned that to 320 calls and 60 minutes with up to eight continued slices. In practice a
+reply that was plainly still working was cut mid-task, told to "stop using tools and write a short
+report", and showed as unfinished while a child worker kept the run alive.
+
+## Decision
+
+The foundation default has no tool-call, time or token limit. `DEFAULT_SLICE_POLICY` sets
+`maxToolCalls`, `maxMinutes` and `maxNewTokens` to 0, so `sliceLimitReached` never fires and no reply
+ends or continues at a budget. The guard, `workSlice` on `sessions.run` and `XINGULAR_WORK_SLICE`
+stay for a caller that wants a limit, and the three-compaction guard is unchanged. The model is no
+longer told a budget exists, and the standard prompt asks it to keep working until the request is
+done or the person interrupts.
+
+## Consequences
+
+- The stable prompt prefix changes once, so the first reply after upgrading is uncached.
+- Runaway work is bounded only by the stall watch (ADR-0054), the compaction guard, approvals and
+  the person's Esc; a host that wants a ceiling sets `workSlice`.
+- The budget code, its protocol field and its heartbeat fields remain, so a later decision can
+  delete them without a migration. `heartbeat.maxToolCalls` is 0.

package/docs/decisions/ADR-0082-connected-brave-browser.md

@@ -0,0 +1,72 @@
+---
+id: ADR-0082
+title: Connected Brave browser backend
+status: accepted
+created: 2026-11-20
+updated: 2026-11-20
+related: [STUDY-0008, PROP-0040, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0082 — Connected Brave browser backend
+
+## Context
+
+The isolated Chromium browser cannot use the person's existing sign-in. The App's WebKit tabs are
+host-owned, have a different profile lifecycle, and do not implement snapshot-scoped ref actions.
+The person asked to choose between an isolated browser and their existing signed-in Brave profile,
+with no automatic switch if the chosen backend disconnects.
+
+## Decision
+
+Add an opt-in Brave backend through an unpacked Manifest V3 extension. The extension uses
+`chrome.debugger` to adopt existing normal tabs, and the Harness adapts the extension to the shared
+`BrowserToolSession` and `browser_*` schemas. The extension is loaded manually and pairs with the
+Harness over an authenticated loopback bridge. Do not enable remote debugging on the person's
+profile and do not require Native Messaging. Pairing validates the extension origin; subsequent
+service-worker calls require the bearer token because the browser may omit Origin on those requests,
+and any supplied mismatched Origin is rejected.
+
+Browser backend selection is device-local. A project, variant or page cannot enable Brave. A person
+must explicitly choose Brave, pair the extension with a short-lived code, and allow each exact
+origin from the extension popup. Chrome host grants can cover every port on a host, so the extension
+also records the exact scheme, host and port and checks that allow list before exposing a tab.
+Incognito is disabled. The extension does
+not request history or cookie permissions and does not export cookies; a signed-in page remains
+signed in because it uses the existing profile. The extension's `debugger` permission is broad and
+must be disclosed before the person selects Brave.
+
+While connected and permitted, the page shows **“Xingular Agent is on this site”**, with Pause and
+Stop controls and a brief pulse at the most recent click. Pause refuses new calls but lets an action
+already in flight finish. Stop revokes the pairing, rejects pending calls, clears the badge and closes
+the bridge. Normal Harness shutdown closes the bridge but keeps the pairing so the extension can
+reconnect. A lost or paused connection refuses calls; it never selects another browser. A timed-out
+call reports that its outcome is unknown and requires a fresh snapshot before retry.
+
+The shared browser gate remains authoritative: snapshot refs are invalidated when page state or the
+debugger attachment changes; sensitive fields are refused; consequential actions require fresh
+human approval and are revalidated; actions require an attended run; page content remains untrusted.
+The Brave tool list does not include the App-specific `browser_upload`. WebKit remains an independent
+backend with its existing narrower capabilities.
+
+## Consequences
+
+- Harness and terminal settings can select isolated or Brave, pair, inspect status and stop the
+  connection. Hosts may disable the generic browser provider with `browser: false` and retain the
+  Harness bridge through `HarnessOptions.browserExtension`.
+- The App keeps WebKit as its native backend and obtains shared Harness browser tools only when
+  Brave is selected. The App's connected-apps broker does not expose duplicate browser tools in
+  Brave mode.
+- Pairing state lives in owner-only `<state dir>/browser/extension-bridge.json`; backend and
+  network settings remain in `<state dir>/browser.json`.
+- The extension requires manual loading and site permissions. It does not provide a remote browser
+  service, history, cookie export, file uploads or general DevTools console/network access.
+- D-25 remains open for selector-based operations in the App's WebKit Rust implementation and its
+  App-only upload contract. D-26 is partly resolved: Brave implements the shared ref tools, but the
+  App's Rust capability response is not yet backend-aware.
+- The opt-in live acceptance in `src/browser/extension/brave-live.acceptance.test.ts` passed with a
+disposable Brave profile and a loopback fixture. It covers pairing, exact-origin gating, snapshots,
+actions, pause/stop and disconnect refusal; it does not exercise Chrome's optional-host grant
+prompt for a non-loopback site. Use only disposable profiles for runtime verification; never use the
+everyday profile.

package/docs/decisions/ADR-0083-one-live-session-runtime.md

@@ -0,0 +1,256 @@
+---
+id: ADR-0083
+title: One live session runtime in the harness
+status: accepted
+created: 2026-11-03
+updated: 2026-11-03
+related: [ADR-0001, ADR-0035, ADR-0056, INV-RUN-1, INV-SRV-1, INV-SRV-4, INV-TUI-2, INV-RC-5, INV-PAR-1, INV-PAR-2, PAR-008, PAR-018]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0083 — One live session runtime in the harness
+
+## Context
+
+The harness runs a conversation in two different runtimes:
+
+- **Structured sessions** (`xagent serve`, the App sidecar): `Sessions.run` opens a Pi session for
+  one run and disposes it when the run settles (`sessions/runner.ts`, `piSessionFactory` and the
+  `finally` of `runTurn`).
+- **The terminal**: a Bun child keeps one Pi `AgentSessionRuntime` alive across turns
+  (`terminal/tui/runtime.ts`). Its gate, telemetry and run accounting go through
+  `terminal/piExtension.ts`, the session socket and `TerminalController`.
+
+ADR-0001 chose the second runtime because calling `sessions.run` per prompt "recreates and disposes
+the runtime per turn, losing persistent plugin UI/queue state". That reason still holds for the
+structured path as it is built today.
+
+Two runtimes mean many lifecycle features are built twice and drift: plan-outcome repair (D-22),
+the queued-message rules, work slices (a headless run continues as a new run, a terminal reply in
+place), stall guards (`terminal/stallWatch.ts`, now `sessions/stallWatch.ts`), `get_capabilities`, and about fifteen private
+`terminal.*` routes that mirror public methods. A terminal session cannot be reached from the App
+(PAR-018) and the two keep separate session catalogs (PAR-008). A run ends when its window closes.
+
+Codex keeps the agent loop in one server process (`codex app-server`) and makes every front end a
+client of it: threads, turns and items over JSON-RPC, approvals as server-to-client requests.
+Claude Code keeps the loop inside the CLI process and lets other front ends spawn that process.
+The harness's server protocol (page 10) and run events (page 02) already have Codex's shape
+(session ≈ thread, run ≈ turn, run events ≈ items). The missing part is a live session the server
+owns across runs.
+
+## Decision
+
+The harness owns one session runtime. A *live session* is a Pi session the harness keeps open
+across runs of the same native conversation. Every front end, including the terminal, reaches it
+through server methods. The terminal keeps its owned OpenTUI presentation (the screen half of
+ADR-0001); only its private runtime goes away.
+
+Work proceeds in phases; each lands with its spec pages and checks.
+
+1. **Live sessions.** A `LiveSessions` service in `src/sessions/` keeps a Pi session open between
+   runs. `Sessions.run` reuses it when the new run's pins match the open session, and opens a fresh
+   one otherwise. Unattended triggers (`probe`, `improver`, `reflection`) and refinement keep the
+   per-run open and dispose. A caller opts in with `sessions.run { live: true }`; the first such run
+   opens the live session. Additive methods: `sessions.live`, `sessions.close`, `sessions.followUp`,
+   `sessions.followUp.clear`. Steering stays `runs.steer`, and replay stays `runs.since`, which
+   already exist. The App adopts this first.
+2. **The terminal as a client.** The OpenTUI child talks to the harness over the protocol on a
+   local socket and renders from run events. The private `terminal.*` mirrors give way to the
+   public methods, scoped by the caller identity the control key proves. The old path stays behind
+   a flag until production PTY acceptance at 40x20, 80x24 and 100x30, then is removed.
+3. **Optional daemon.** Decided after phase 2: a long-lived `xagent serve --daemon` on a Unix
+   socket under the state directory, with one writer per data root, so a run outlives its window,
+   and remote control belongs to a live session rather than a terminal (PAR-018).
+
+### Phase 1 design: what a run binds
+
+A run pins its account, variant version and capability set (INV-RUN-1), so a live session may only
+serve a run whose pins equal the session's. The reuse key is: account, variant version, frozen
+capability fingerprint, working folder and workspace root, plan flag, allowed tool names, the
+stable system prompt, and the loaded plugin set. Model and effort changes go through Pi's own
+setters. Any other difference closes the live session at the turn boundary and opens a new one on
+the same native history, as `/variant` already does (ADR-0065).
+
+Today these are created per run and baked into the Pi session when it opens
+(`sessions/sessions.ts`, the `params` and `factory` call; `sessions/runner.ts`,
+`piSessionFactory`). Each must read a *current run binding* that `LiveSessions` swaps at the start
+of every run:
+
+| Bound per run today | Where | Becomes |
+|---|---|---|
+| The gate (`checkDetailed`, workspace scope requests, plan refusals) | `gatedExtension` in `piSessionFactory` | A session-level `tool_call` handler that asks the current binding's gate |
+| Custom tool specs bound to the run (`spec.execute`) | `customTools` in `piSessionFactory` | Session-level tool definitions that call the current binding's spec of the same name |
+| The extension host (`ask`, `notice`) | `bindExtensions` in `piSessionFactory` | A host that forwards to the current run, and refuses between runs |
+| `runLineageJoin(root, runId)`, `subagents.extension(runId)` | `params.inline` | Extensions that read the current run id |
+| Compaction checkpoint (`initialTodo`, plan instructions) | `params.inline` | Reads the current run's todo and plan flag |
+| Work-slice guard and goal loop (their state and controller) | `params.inline` | Installed once, enabled and fed by the current binding |
+| `onRefusal`, `activatedPlugins`, the heartbeat and `settle` | `params`, `runTurn` | Already per run in `runTurn`; unchanged |
+
+`runTurn` stops disposing the session; `LiveSessions` disposes it on `sessions.close`, on a pin
+change, after an idle timeout, and at harness shutdown. A live session runs one run at a time; a
+second `sessions.run` while one is active is refused, or delivered as a steer or follow-up when the
+caller asks for that.
+
+## Alternatives and rejection reasons
+
+- **Keep two runtimes.** Every lifecycle feature keeps its second copy, and the drift and parity
+  lists keep growing.
+- **Claude Code's model** (the terminal process is the engine, hosts spawn it). Simple for one front
+  end, but the App, the phone surface and evaluation would each drive a terminal process, and the
+  structured path would remain a second runtime.
+- **Make the terminal call today's `sessions.run`.** Rejected by ADR-0001 for the same reason it
+  gives: a per-run runtime loses queues and persistent plugin UI. Phase 1 removes that reason first.
+- **A rewrite in one release.** Too large to verify; each phase must pass the full checks and, for
+  phase 2, production PTY acceptance.
+
+## Consequences and risks
+
+- This is a 2.0-level change: it adds methods and a socket transport (INV-SRV-1, INV-SRV-4),
+  changes who owns execution in the terminal (INV-TUI-2), and moves remote control's lifetime
+  (INV-RC-5). Pages 02, 10, 11, 14 and 15 change as each phase lands.
+- Every inline extension must be safe to keep across runs. A missed per-run closure would leak one
+  run's state into the next; phase 1 tests run two turns on one live session and check each run's
+  events, refusals and records belong to that run only.
+- Streaming over IPC adds latency to the terminal; phase 2 measures first-delta latency before and
+  after.
+- Live checks may use real model requests only with the owner's permission (granted for this work
+  with a Codex account on Luna 6, or the OpenCode account on DeepSeek V4.1 Flash), never against
+  `~/.codex`, `~/.claude` or `~/.pi`.
+
+## Evidence — phase 1, 2026-11-03
+
+Implemented in `src/sessions/live.ts`, `src/sessions/runner.ts` (`rebind`, `release`, run slots),
+`src/sessions/sessions.ts` (`live`, follow-ups) and `src/server/methods.ts`. `src/sessions/live.test.ts`
+covers reuse across runs, a pin change, the per-run default, busy refusal, queued, idle and parked
+follow-ups, close and shutdown, refusal for unattended runs, and a rebind of a real Pi session (an
+`input` handler and a bound tool replaced by the next run's) with no model request. Harness:
+1,803 tests passed, `npm run prove` passed. App sidecar typecheck and 89 tests passed against this
+tree.
+
+Live check with owner permission, account OpenCode, model `opencode-go/deepseek-v4.1-flash`, a
+throwaway data root and the installed sign-in:
+
+| Run | Live | Status | Native session | Session ready (ms) | Input tokens | Cache read |
+|---|---|---|---|---|---|---|
+| b1 | no | completed | `01a19f83-2ef3…` | 1002 (cold start) | 4796 | 0 |
+| b2 | no | completed | same | 73 | 73 | 4736 |
+| l1 | yes | completed | `01a19f83-408c…` | 75 | 4796 | 0 |
+| l2 | yes | completed | same, reused | 52 | 73 | 4736 |
+| l3 | yes, steered | completed | same, reused | 59 | 326 | 9472 |
+
+The live session served three runs (`runs: 3`). Reuse keeps the provider cache exactly as the
+per-run path does. A steer sent after the first delta was recorded as `message.steered` and the
+model answered it in the same run. A reused session is ready slightly sooner (52–59 ms against 73 ms
+warm); the larger gains are steering, follow-ups and plugin state that survive between runs.
+
+## Evidence — phases 2 and 3, 2026-11-03
+
+**Phase 2, the terminal as a client.** `XINGULAR_TERMINAL_RUNTIME=harness` selects
+`terminal/tui/harnessRuntime.ts`; the parent side is `terminal/liveTerminal.ts`. The in-process
+runtime stays the default. Decision recorded with the owner: plugin presentation that needs an
+in-process terminal is unavailable in client mode (INV-TUI-8), as it is in a host.
+
+- Tests with real Pi and a scripted model: `terminal/liveTerminal.test.ts` (two turns on one live
+  session, the native event journal, a plan-mode `ask_user` answered through the decision routes,
+  busy refusal) and `terminal/tui/harnessRuntime.socket.test.ts` over the real session socket (the
+  mirrored transcript, one native session, the in-process tool set, `/todo` and `/trajectory`
+  lookup, the system prompt, a plan question, `/new` on a new file).
+- Live, OpenCode account, `opencode-go/deepseek-v4.1-flash`, real OpenTUI frontend in a PTY at
+  100x30, 80x24 and 40x20: five turns and a queued follow-up each, all completed on one native
+  session. Mean time from Enter to the reply on screen for turns 2–5: client 1.60 s, 1.79 s and
+  1.37 s against in-process 1.59 s at 100x30, within the model's own variation. The fixed overhead
+  from Enter to the harness run starting is about 30 ms against about 5 ms in process. Startup to
+  ready: 2.2–2.9 s client, 2.6–2.8 s in process.
+- Found and fixed on the way: the client first lacked the world tools and had `grep`, `find` and
+  `ls`, which the in-process terminal does not activate; a new conversation re-adopted the old file
+  from stale state; a mode with no saved model sent none; child runs inherited `live: true` (caught
+  by the App's sidecar test).
+- Not passing yet: the production PTY suite stops early in client mode on a record-contract
+  difference (Known drift D-28).
+
+**Phase 3, the long-lived harness.** `server/socket.ts`, `terminal/daemon.ts`, `Terminals.detach`
+and `prepare { attach }`, CLI `xagent daemon start|stop|status`, `xagent --daemon`, `xagent attach`.
+
+- Tests: `terminal/daemon.test.ts` (one lock per state folder and a stale lock replaced, the
+  protocol on an owner-only socket to several connections, a full daemon run that prepares over its
+  socket, reports and stops); `harnessRuntime.socket.test.ts` (a reply keeps running when its
+  window closes and a new window reattaches and sees it finish; a detached session ends when its
+  reply settles).
+- Live, same account and model: `xagent daemon start`, a `--daemon` window asked for 600 numbers,
+  the window was hung up (SIGHUP) mid-reply; it printed the `xagent attach <id>` line, `daemon
+  status` reported one live session and one reply without a window, `xagent attach` showed the
+  reply finish 3.6 s later, and the run recorded `completed`. Afterwards no live or detached
+  session remained and `daemon stop` removed the lock and socket.
+- Found and fixed: the daemon took its lock before the state folder existed.
+
+Checks at the end: harness typecheck clean, 1,820 tests pass, `npm run prove` passes; App sidecar
+typecheck and 89 tests pass against this tree, `check:layers` flags none of the new files. Open
+and unrelated to this change: the App's `soloCommands.test.ts` expects Solo to handle `/goal`
+(PAR-017), and the App's root typecheck reports button-prop errors in its UI.
+
+## The client terminal is the default — 2026-11-03
+
+The owner asked to finish the client terminal and make it the default once it works. `xagent` now
+runs the client terminal unless `XINGULAR_TERMINAL_RUNTIME=inprocess` is set. The in-process
+runtime stays for plugins that need their own terminal components.
+
+What finishing it took, each with a test:
+
+- Parity of what a person sees: plugin notices, status lines, widgets and titles (`harness_notice`);
+  a failed reply's message; a settle marker when Pi's loop never started; plugin `select`,
+  `confirm`, `input` and `editor` shown with the window's own dialogs (`question.requested.dialog`);
+  plugin commands listed before the first turn and sent by their owner-qualified route; a plugin
+  that cannot load stops the window's start; `/goal` run as a harness goal with its state shown.
+- Parity of what a turn does: plan runs carry only the plan's tools (`planTools: 'active'`); `!`
+  commands run as the turn's initial Bash on a resumed history; `/session` takes a file or a session
+  id; `/new` and steering ask the harness whether a reply really runs before refusing.
+- Lifecycle: `/stop` and Esc return at once and Pi's abort finishes behind them; the window closes
+  cleanly when its harness is gone; an uncaught error in the host closes the window before exiting
+  1; a frontend left after its terminal hangs up is ended after three seconds (this also leaked
+  in-process windows); the long-lived harness survives one plugin's uncaught error.
+- A harness fix every host gets: a provider request that timed out and was retried and answered no
+  longer marks the run failed.
+
+Evidence:
+
+- Harness: typecheck clean, 1,829 tests pass, `npm run prove` passes; App sidecar typecheck and 89
+  tests pass; `check:layers` flags none of the new files.
+- Production PTY suite (`scripts/verify-terminal.py`, its local provider, no real requests) in the
+  default client terminal: the full run passes at 40x20, 80x24, 100x30 and 120x40, and so do the
+  welcome, click-focus, composer, file-completion, history, resume, todo, questions, jump-latest,
+  help, command-completion, attachments, dialog-paste, thinking, queue and compaction suites. The
+  script now accepts what differs by design: either approval title, a question asked with or without
+  an approval, either `nativeSessionId` contract, a plugin overlay the client cannot draw, a size
+  shown in bytes, a varying usage-event count, and a long command name wrapped after its owner
+  prefix. Browser, palette, accounts at 120x40 and trajectory at 120x40 fail the same way on the
+  previous commit (Known drift D-30); markdown fails only with uncommitted work outside this change
+  (D-31). The full run's `/stop` step, which allows 0.8 seconds, failed twice while the machine's
+  load average was above 20 and passed every time below it.
+- Live, OpenCode account, `opencode-go/deepseek-v4.1-flash`, real frontend at 100x30: five turns
+  and a queued follow-up on one native session; `/stop` and Esc recorded the reply interrupted in
+  33–77 ms against 35–62 ms in process; turn latency within the provider's variation. One turn hit
+  a ten-minute provider timeout and its retry answered; the run now records `completed`. With
+  `--daemon`, a window hung up mid-reply left the reply running; `xagent attach` showed it complete.
+
+## Closing the migration — 2026-11-04
+
+- **Stall guard for every harness run.** The terminal's stall rule (15 minutes without an event, 30
+  with a tool running; ADR-0054, ADR-0078) lived only in the in-process controller, so a client
+  terminal reply, a live session and an App turn had only Pi's own request timeout (about ten
+  minutes, retried). `runTurn` now applies it to every run (`sessions/stallWatch.ts`, moved from
+  `terminal/`): the run settles `interrupted` with `stalled`, the native turn is aborted, and a live
+  session is closed (queued follow-ups parked), or closed under the turn if the abort has not
+  unwound it after 30 seconds. A pending approval or question, and a wait for subagents (each child
+  has its own guard), restart the clock. Pi's request timeout is unchanged: a shorter one multiplies
+  with the retry policy and could cut a slow reasoning model's first token, so the progress rule is
+  the cap.
+- **Heartbeat for every run.** `runTurn` emitted `heartbeat` only for work-slice runs, against
+  INV-RUN-14; a live reply with a quiet tool for 30 minutes could be settled `owner_gone`. It is now
+  unconditional (slice counters zero without a slice).
+- **Verifier.** The four D-30 suites asserted stale layouts, not product faults, and are fixed; the
+  `/stop` step polls the run record up to 8 seconds instead of reading for 0.8; the in-process
+  fallback's full run passes at 80x24 (the deny/approval-cancel stop did not reproduce). D-31 (the
+  markdown suite) is the other change's fixture overflowing the screen. Tests: `sessions/stall.test.ts`
+  (8) cover the guard and heartbeat.
+- Not done: PAR-018 (remote control bound to a live session). Notes in HANDOFF.md.

package/docs/doctor.md

@@ -0,0 +1,95 @@
+# 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.
+The application-window capture check reports blocked when no screenshot tool is listed, and
+unverified when one is listed; it does not capture a window or establish backend isolation.
+
+The shell check reports which `bash` the session would run and whether the platform's
+write-boundary sandbox (sandbox-exec on macOS, bubblewrap on Linux) is installed, because a missing
+backend stops every Bash call before the command starts. It runs nothing. On Windows it reports a
+warning naming the shell (Git Bash or PowerShell) and that each command asks for approval, because
+Windows has no write-boundary sandbox; the live shell check reports unverified there, since a
+command would need a person to approve it.
+
+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”. The shell check runs one fixed command written by the harness (`printf`) in the working
+folder through the same root, hard-link scan and write-boundary sandbox a normal Bash call uses, and
+reports only the exit status: no model input is sent, no file is written and no network request is
+made. A diagnostic never widens the boundary, so Full Permission cannot change its result; when the
+boundary refuses before the shell starts (for example a hard-link alias in the workspace), the
+finding is blocked with that reason instead of claiming the shell is broken. 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.