@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/proposals/PROP-0019-contextual-side-questions.md

@@ -0,0 +1,122 @@
+---
+id: PROP-0019
+title: Harness-owned contextual side questions across surfaces
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-RUN-1, INV-RUN-3, INV-RUN-5, INV-GATE-1, INV-PLG-1, INV-PLG-5, INV-CAP-1, INV-SRV-1, INV-SRV-2, INV-PAR-1, INV-PAR-2, 02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 07-tools-and-the-gate.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, 12-storage.md, ADR-0023-contextual-side-question-runs.md]
+---
+
+# PROP-0019: Harness-owned contextual side questions across surfaces
+
+## Problem
+
+`/btw` currently has two different execution paths. The terminal constructs a direct, in-memory Pi
+session in `src/terminal/tui/sideQuestion.ts`; it supplies at most six visible turns and 6,000
+characters, names of tools called, but no tool inputs or results. It has no Harness run record. The
+App assembles a different bounded snapshot and starts a separate, tracked `sessions.run` with
+trigger `side-question` (`App/docs/features/FEAT-0014-side-questions.md`). The parity register calls
+these one capability but lists no Harness owner method (`docs/parity.md`).
+
+The terminal side model therefore answers from a short excerpt, lacks the main run's instructions
+and evidence, and is explicitly told to be brief. The two surfaces also have different observability
+and lifecycle. A question about work outside the repository can be answered incorrectly when that
+work is absent from the excerpt, even if the main run already read it.
+
+## Affected rules
+
+- **INV-RUN-1:** A side question pins its selected account and an empty capability set, with no
+  variant (`variantVersion: null`), because it uses only fixed Harness instructions and a redacted
+  projection supplied by or read from the main run.
+- **INV-RUN-3:** Parent run events used as context have already been validated, redacted and
+  persisted. Side-question events use the same contract.
+- **INV-RUN-5:** Side questions use a dedicated unattended launch: no extensions, context files,
+  variant code, connectors, providers, subagents, or Harness tools.
+- **INV-GATE-1:** A side-question run has no tools to call; this is enforced by the Harness.
+- **INV-PLG-1 / INV-PLG-5:** The Harness remains the only loader. Its fixed side-question
+  instruction is attributed to a Harness-owned plugin descriptor.
+- **INV-CAP-1:** The side run freezes an empty tool, connector, and contribution set.
+- **INV-SRV-1/2:** Hosts call an additive Harness service through the server contract and the same
+  in-process API.
+- **INV-PAR-1/2:** The Harness owns the capability; terminal and host surfaces use it.
+
+## Proposal
+
+1. Add a generic Harness side-question service with start, read and interrupt operations. It is
+   callable by the standalone terminal and embedding hosts. Each question is an independent
+   run with a new native history identity, ordinary run records, event validation and redaction.
+   It is not a child, subagent, continuation, queued message, or change to the main run.
+2. The service builds a bounded context from the main run's recorded effective system prompt,
+   current context update, visible tool inventory, persisted public run events, and a caller-supplied
+   transcript projection. Visible context includes assistant text, tool names, inputs and results.
+   Hidden reasoning and attachment bytes are excluded. Credential-like fields and common secret
+   forms are redacted before context enters the side run. Conversation and tool contents are framed
+   as evidence; they cannot expand the side run's authority. Context limits are fixed in code and
+   tested, keeping the effective prompt first and the newest conversation/activity when trimming.
+3. A side-question run uses the main conversation's selected account, model and effort, with an
+   independent session identity and a fixed, attributed Harness instruction. It records no variant
+   (`variantVersion: null`) and freezes an empty capability set. It loads no tools, providers,
+   connectors, subagents, project context files, user or variant plugin code, or main native history.
+   The main system prompt is context for answering, not permission to access the main run's tools.
+4. A side question and answer never enter, steer, stop or queue work on the parent conversation.
+   They are recorded only in the independent side run's ordinary events; clients may show that run
+   in Trajectory and Usage. No separate durable side-thread store is introduced.
+5. Each surface keeps its current side-question presentation. The terminal supports a scrollable
+   answer, copy and dismissal. The App continues to own its dock and conversation selection, while
+   the Harness owns launch policy, context construction, run lifecycle and result events.
+6. Phase two aligns the host path policy with the main read path: absolute and `~` paths are
+   available to read-only file tools anywhere the operating system permits. The working directory
+   is a default location, not a repository sandbox. Edit, write and command calls continue through
+   the existing gate.
+7. Update the capability register so the Harness service owns side questions and both terminal and
+   App surfaces call the shared contract.
+
+## Alternatives
+
+- **Keep the terminal-only Pi session and raise its excerpt limits.** This leaves the App and
+  terminal with different semantics and observability.
+- **Send hidden reasoning, attachment bytes, or the entire native history.** This exposes material
+  that is not needed to answer questions and can include private or provider-internal content.
+- **Give the side question the main run's tools.** This turns a side answer into independent work
+  with authority and can cause effects that the user did not request.
+- **Persist all side-question threads in a new store.** This adds retention, deletion and
+  cross-surface synchronization contracts; ordinary run records already capture model usage and
+  results.
+- **Treat the repository root as a read boundary.** Pi's read-only file tools accept absolute and
+  `~` paths, but the App's host policy also applies a working-folder/trusted-folder check. The
+  approved implementation removes that extra read restriction and accepts `~` in host path checks;
+  writes and commands keep their existing gates.
+
+## Consequences
+
+- Side-question requests and answers become ordinary, separately inspectable Harness run records.
+  They remain absent from the parent transcript and are no longer ephemeral from the run store.
+- The Harness owns the context schema, redaction, bounds, restricted launch and lifecycle. Hosts
+  provide only the transcript projection they own and present the Harness result.
+- A dedicated restricted launch and an attributed first-party instruction are required. The
+  restriction is explicit; `automatic: true` alone is not the contract because unattended runs have
+  their own plugin loading rules.
+- No data migration or protocol version change is required. New side runs use the
+  `side-question` trigger and no variant pin. A supplied parent run must belong to the supplied
+  parent session; the terminal and App derive that relationship from their active conversation.
+- The Harness file-reading behavior does not change. The App now aligns its host gate with that
+  OS-permission boundary for read-only native file tools. Its existing approval and scope gates
+  remain in place for writes and commands.
+
+## Migration
+
+No stored schema migration is planned. New side questions use standard run records under a distinct
+trigger; clients do not reopen old side-question sessions. The App switches its launch path to the
+shared Harness service and permits OS-readable paths in read-only native file tools. Existing run
+records and write/command gates are unchanged.
+
+## Checks
+
+- Unit tests for context redaction, ordering, bounds, omitted hidden fields, parent event projection,
+  attributed instructions, no-tool launch, run pinning and owner-scoped reads/interrupts.
+- Lifecycle checks for streaming, replacement, cancellation and dismissal without changing the
+  parent run or transcript.
+- Harness `npm run typecheck`, `npm test`, `npm run prove`, and `python3 scripts/verify-terminal.py`.
+- App `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.
+- Fake-provider tests are the default. Any real-model/cache or live UI acceptance run requires the
+  account owner's permission.

package/docs/architecture/proposals/PROP-0020-builtin-feature-plugins.md

@@ -0,0 +1,105 @@
+---
+id: PROP-0020
+title: Built-in feature modules and namespaced plugin commands
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-PLG-5, INV-PLG-6, INV-TUI-2, INV-TUI-7, INV-SRV-1, 06-plugins-and-capabilities.md, 11-terminal.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0020: Built-in feature modules and namespaced plugin commands
+
+**Command namespace note:** The initial decision to prefix every built-in command was superseded by
+[PROP-0021](PROP-0021-command-namespaces-and-duplicates.md) and
+[ADR-0021](../../decisions/ADR-0021-required-command-namespaces.md). Required built-in commands now
+use their bare names; this proposal remains the record of the feature-module architecture.
+
+## Problem
+
+`PluginDescriptor` already describes first-party tools, but runtime ownership is split across the
+central `World` constructor, `server/methods.ts`, and the TUI's command switch. TUI plugin commands
+are indistinguishable from core commands, while Pi extension commands are exposed under their
+unprefixed names. This makes feature ownership hard to follow and allows command-name conflicts to
+be resolved by Pi's automatic suffixes instead of a clear owner decision.
+
+Evidence: `src/world/world.ts` directly constructed the web, browser and annotation parts;
+`src/server/methods.ts` owned their handlers alongside Wiki, history, worktree and refinement
+handlers; `src/terminal/tui/commands.ts` held feature-page dispatch and exposed Pi commands as
+`/<name>`.
+
+## Affected rules
+
+- **INV-PLG-5:** Everything model-visible belongs to a plugin. A new prompt section, tool group or
+  tool is declared by a `PluginDescriptor` or reported as unattributed.
+- **INV-TUI-2:** The Harness owns screen composition, input, scrolling, command routing and plugin
+  UI. Pi owns the execution runtime, native history and rich content components.
+- **INV-SRV-1:** `src/server/methods.ts` is the contract for every non-Node host. Renaming, removing,
+  or changing the params or result shape of a method is an architecture change.
+
+## Proposal
+
+Add one internal typed registry of Harness-managed built-in plugin modules. A module may contribute
+its existing descriptor, world part and cleanup, server-method handlers, and terminal command
+metadata. The registry checks plugin IDs, terminal command names and built-in server-method names
+for duplicates. It does not add category fields to `PluginDescriptor`, plugin responses, or storage.
+
+The TUI uses `/plugin:<command>` for built-in and Pi extension commands. Core terminal commands
+remain unprefixed. The built-in commands become `/plugin:doctor`, `/plugin:worktree`,
+`/plugin:trajectory`, `/plugin:subagents`, `/plugin:notes`, and `/plugin:annotate`. Their former
+unprefixed forms are removed at cutover. Prompt templates and the existing `/skill:<name>` syntax
+keep their current behavior.
+
+Pi extension commands are invoked through their registered handler and command context. Duplicate
+extension names are omitted from completion and rejected with the owning extension paths when
+invoked. A built-in command name is reserved against extension commands; the built-in remains
+available and reports the colliding extension owner.
+
+Ownership taxonomy is documentation only:
+
+- **Foundation:** accounts, sessions and run recording, prompt/variant validation, the gate,
+  plugin loading/trust/attachments, resource browsing, server and terminal frameworks, and the
+  isolated browser engine/network safety.
+- **World:** web tools, browser tools and page annotations.
+- **Memory:** Wiki, history and trajectory.
+- **Automation:** subagents, ask-user, checklist, lessons and refinement.
+- **Integrations:** connected apps/MCP and Hub.
+- **Operations:** doctor and worktrees.
+
+The generic browser engine stays Foundation-owned. The browser plugin contributes the user-facing
+tools through an adapter. Required and switchable plugin availability remains as before. Public
+server method names, method schemas, stored data and capability gating do not change.
+
+## Alternatives
+
+- Keep the TUI switch and move only the annotation command. This leaves all feature commands and
+  world assembly split across central dispatch points.
+- Invoke extension handlers through rewritten user text. This relies on Pi's input parsing and
+  would not provide one collision policy or a stable plugin command context.
+- Expose plugin categories in the public descriptor. The categories are for ownership and
+  documentation, and do not improve current runtime decisions or user flows.
+- Do nothing. Feature ownership and command collisions stay implicit.
+
+## Consequences
+
+The built-in registry is the runtime source for first-party descriptors, world parts, server
+handlers and command metadata. The terminal adapter still owns page construction and rendering.
+Hosts retain the same RPC methods, tools pass through the same capability set and gate, and no
+storage migration is needed. People update plugin slash commands to the `plugin:` prefix.
+
+## Migration
+
+Change all current terminal documentation and tests to the namespaced forms. Do not retain aliases
+for old plugin command names. Keep the generic browser engine in Foundation and move only the
+browser tools adapter under the browser plugin. Record plugin categories as an ownership taxonomy,
+not public metadata.
+
+## Checks
+
+- Registry tests cover unique module IDs, command owners, duplicate server handlers and lifecycle
+  part construction.
+- Terminal tests cover built-in and Pi command completions, argument dispatch, duplicate-owner
+  diagnostics and rejection of retired command names.
+- Existing attachment tests continue to prove that switchable tool contributions obey the saved
+  capability set.
+- Run Harness typecheck, tests, build and `npm run prove`; run terminal PTY journeys and the App's
+  typecheck, tests, layer check and Rust tests.

package/docs/architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md

@@ -0,0 +1,99 @@
+---
+id: PROP-0021
+title: Required built-in commands and duplicate command suppression
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-TUI-7, INV-PAR-1, 11-terminal.md, 14-surfaces-and-parity.md, ADR-0021]
+---
+
+# PROP-0021: Required built-in commands and duplicate command suppression
+
+Accepted by the user’s request to implement this plan on 2026-10-24; implemented in the working tree and recorded in ADR-0021.
+
+## Problem
+
+PROP-0020 put every built-in plugin command behind `/plugin:`. This makes required Harness features
+less direct to invoke, and stale bridge registrations create duplicate `/plugin:accounts`,
+`/plugin:hub`, and `/plugin:plugins` entries beside their core commands. Loaded extension commands can
+also duplicate an existing bare command or prompt, as with `/plugin:mcp` or `/plugin:llama`.
+
+Evidence: the required `subagents`, `history`, `doctor`, and `worktrees` plugin descriptors own
+`subagents`, `trajectory`, `doctor`, and `worktree` terminal commands in `src/plugins/builtin.ts`.
+`src/terminal/tui/commands.ts` prefixes every registry command and does not check extension names
+against core commands or prompt templates. `src/terminal/piExtension.ts` separately registers
+`hub`, `plugins`, and `accounts`, although the owned terminal already routes those names. `/mcp` is a
+core alias for Connections. `/llama` is resource-dependent rather than a Harness core command; when
+a matching prompt is loaded, it is the bare command that takes precedence.
+
+## Affected rules
+
+- **INV-TUI-7:** A plugin command is invoked as `/plugin:<command>`, dispatched to its registered
+  owner and shown that way in completion and help. Duplicate names are rejected with owner
+  diagnostics. Old unprefixed plugin command forms are not aliases; core commands stay unprefixed.
+- **INV-PAR-1:** Every capability a person can use in a host is a Harness capability; the standalone
+  terminal surfaces it.
+- **14 Surfaces and parity, Contracts:** Plugin-owned terminal commands use `/plugin:<command>`;
+  Foundation commands remain unprefixed.
+
+## Proposal
+
+Use an explicit namespace on each built-in terminal command. Commands owned by a required
+`PluginDescriptor` use the bare terminal namespace; optional built-in plugin commands use
+`/plugin:<command>`. This yields:
+
+| Plugin | Command | Invocation |
+|---|---|---|
+| `subagents` (required) | `subagents` | `/subagents` |
+| `history` (required) | `trajectory` | `/trajectory` |
+| `doctor` (required) | `doctor` | `/doctor` |
+| `worktrees` (required) | `worktree` | `/worktree` |
+| `annotations` (switchable) | `notes`, `annotate` | `/plugin:notes`, `/plugin:annotate` |
+
+Keep core `/accounts`, `/hub`, `/plugins`, and `/mcp` unprefixed. Remove the Pi bridge's duplicate
+`accounts`, `hub`, and `plugins` command registrations.
+
+A bare core command, alias, required built-in command, or loaded prompt owns that bare name. Do not
+show or execute `/plugin:<name>` when its name collides with one of those commands; direct use reports
+the bare command to use. The same rule handles dynamic duplicates such as `/plugin:mcp` or
+`/plugin:llama` without special-casing installed packages. Pi extension commands with no bare-name
+collision remain `/plugin:<name>`. Namespace collisions between core and required built-in commands
+are rejected rather than silently overwritten. Old prefixed forms of required built-in commands are
+not aliases.
+
+Command routing, pages and existing account/plugin methods remain Harness-owned. No server method,
+capability gate, storage layout, or plugin availability changes.
+
+## Alternatives
+
+- Keep all built-in commands namespaced. This preserves the duplicate entries and makes required
+  Harness operations less direct.
+- Unprefix every built-in plugin command. This also changes the optional, switchable Annotations
+  commands even though the request targets required plugins.
+- Hide only the five currently named duplicate entries. A general same-name rule would still allow
+  future extensions or prompts to create duplicates.
+- Do nothing. The current prefixed required commands and duplicate entries remain.
+
+## Consequences
+
+Completion, help and dispatch use the namespace declared by the built-in registry. Bare names for
+required plugins participate in the core command collision checks. Optional built-in and third-party
+plugin commands retain the plugin namespace. When a bare prompt or command conflicts with a Pi
+extension command, the bare command wins and the extension's slash command is unavailable under that
+name; the extension must choose another name to expose both.
+
+## Migration
+
+Use `/subagents`, `/trajectory`, `/doctor`, and `/worktree` in place of their `/plugin:` forms. Keep
+`/plugin:notes` and `/plugin:annotate`. Use `/accounts`, `/hub`, `/plugins`, and `/mcp` for their
+existing core commands. No stored data or server methods migrate.
+
+## Checks
+
+- Registry tests cover the explicit namespace derived for required and optional plugin commands.
+- Terminal tests cover bare command routing, optional/plugin-prefixed routing, help/completion,
+  bridge registration removal, extension duplicates, and extension collisions with bare commands,
+  aliases, and loaded prompts.
+- Update parity and command documentation, including Doctor, trajectory, subagents and worktrees.
+- Run Harness typecheck, tests, build and terminal proof; then run the App typecheck, tests, layer
+  check and Rust tests.

package/docs/architecture/proposals/PROP-0022-plan-only-questions.md

@@ -0,0 +1,102 @@
+---
+id: PROP-0022
+title: Keep question tools available only in interactive plan mode
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-RUN-8, 02-sessions-and-runs.md, 04-prompt.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 11-terminal.md, 14-surfaces-and-parity.md, docs/parity.md]
+---
+
+# PROP-0022: Keep question tools available only in interactive plan mode
+
+## Problem
+
+The user wants ordinary chat not to expose a model-initiated question tool, while plan mode retains
+questions, with no setting or plugin toggle. Today `Sessions.start` requests `ask_user` whenever
+Harness tools are enabled (`src/sessions/sessions.ts`), and the terminal bridge registers both
+`ask_user` and `ask_user_question` (`src/terminal/piExtension.ts`). Plan mode currently retains the
+same SDK tool list (`src/sessions/planMode.ts`) and filters the terminal's active list from its
+current tools (`src/terminal/tui/runtime.ts`).
+
+`ask-user` is a required built-in plugin (`src/plugins/builtin.ts`); it has no switchable attachment,
+and `plugins.attach` rejects required plugins (`src/plugins/api.ts`). `harnessTools: false` is too
+broad: it also omits History, Wiki, skill loading, checklist, and session naming. A mode-aware tool
+policy is needed instead of disabling the plugin.
+
+## Affected rules
+
+- **INV-RUN-8:** “Plan mode never changes the tool list or the system prompt, so switching it keeps
+  the cached prefix. Its refusals happen before approvals and no approval can lift them.” This
+  proposal changes the tool-list part: an attended plan request may expose the question tools that
+  ordinary runs omit. Plan refusals remain before approvals. The stable system prompt remains
+  unchanged; provider cache effects of the tool-list difference are not assumed.
+
+## Proposal
+
+1. New, ordinary interactive runs do not expose the Harness-owned `ask_user` tool. This is enforced
+   while the Harness resolves the run's callable tools, before the capability set is frozen, so a
+   caller cannot restore it by adding its name to `tools.allow` or a wider requested capability set.
+2. An attended `plan: true` run may expose `ask_user`. Explicitly narrower caller capabilities
+   still win. Automatic, probe, improver, and reflection runs do not receive a question tool.
+3. In the Harness terminal, ordinary mode does not activate `ask_user` or its terminal-specific
+   `ask_user_question` counterpart. A plan request may temporarily activate both from the registered
+   tool inventory; the normal active-tool set is restored when planning succeeds, fails, or is interrupted.
+4. Keep the `ask-user` built-in required and non-switchable. Do not add an attachment, preference,
+   or per-run UI toggle. Approval prompts for gated actions remain available in normal mode; this
+   proposal only removes model-initiated question forms. A model can still state an assumption or
+   ask in ordinary reply text.
+5. Preserve the existing run capability pinning contract. A continuation keeps its earlier frozen
+   capability set, even when that set contains a question tool; suppression applies to newly resolved
+   ordinary runs. If that snapshot includes `ask_user`, an automatic or probe/improver/reflection
+   continuation is rejected with `continuation_mismatch` rather than narrowing the snapshot or
+   allowing an unattended question. Update `INV-RUN-8` to document the plan-mode tool-list exception
+   and update the session and terminal contracts plus the parity register.
+
+This proposal concerns Harness-owned question tools. It does not blacklist arbitrary third-party
+extensions that independently implement a question interface under another tool name.
+
+## Alternatives
+
+- **Make `ask-user` switchable and default it off.** This would remove it in plan mode too unless
+  mode-specific overrides were added, and would contradict the requested fixed behavior. Making a
+  required Harness part optional also changes the plugin contract and `INV-PLG-9`.
+- **Set `harnessTools: false`.** This hides unrelated Harness tools and is not a question-only
+  control.
+- **Leave the tool visible but refuse calls outside plan mode.** The model would still see and may
+  call the tool in normal mode, receiving a refusal rather than having no question surface.
+- **Do nothing.** Preserves current behavior, which does not meet the request.
+
+## Consequences
+
+- Newly resolved normal runs have a narrower frozen tool set. Attended plan runs may include
+  `ask_user` subject to their caller's capability set; this is the explicit exception to
+  `INV-RUN-8`.
+- The terminal derives plan-safe tools from registered tools as well as its normal active-tool list,
+  then restores the ordinary list on success, failure or interruption.
+- Tool-list changes may affect provider request caching. No cache-preservation claim is made; any
+  real-provider measurement follows `INV-PRM-8` and requires the account owner's permission.
+- Existing stored runs and plugin attachments need no migration. Continuations retain the earlier
+  pinned tool set as required by `INV-RUN-2`.
+- Gated tool approvals and plain-text questions remain possible. The guarantee is specifically
+  that the Harness-owned question tools are not callable in newly started normal runs.
+
+## Migration
+
+No protocol, storage schema, or attachment migration is required. New runs resolve the mode-specific
+callable set before `freezeRun`; existing run records and their capability snapshots are unchanged.
+Continuations preserve their original snapshot. The App needs no separate preference or UI; it
+continues to call Harness, which enforces the selection. Its sidecar tests must verify the resulting
+tool set.
+
+## Checks
+
+- SDK session tests prove normal runs omit `ask_user` even when requested, attended plan runs can
+  include it, narrower capability sets still exclude it, automatic/refinement/reflection runs do not
+  receive it, and continuation snapshots remain exact.
+- Terminal tests prove normal active tools omit both question names, plan mode activates them, and
+  the normal set is restored after success, failure and interruption.
+- Run Harness `npm run typecheck`, `npm test`, `npm run prove`, and the terminal question/plan
+  verification. After Harness implementation, run the App's typecheck, tests, layer check, and Rust
+  tests, including sidecar coverage of normal and plan tool lists.
+- Use fake-provider tests by default. Any real provider cache check requires the account owner's
+  explicit permission.

package/docs/architecture/proposals/PROP-0023-xagent-cli-name.md

@@ -0,0 +1,61 @@
+---
+id: PROP-0023
+title: Rename the published CLI command to xagent
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [11-terminal.md, package.json#bin, CLI documentation, ADR-0009]
+---
+
+# PROP-0023: Rename the published CLI command to xagent
+
+## Problem
+
+The package currently publishes `xharness` as its only executable, and invoking it without a
+subcommand starts the Harness-owned OpenTUI terminal. The requested launch command is `xagent`.
+The command name is a public CLI contract, so replacing it must update the package bin mapping,
+help text, command examples, smoke checks, and the terminal specification.
+
+## Affected rules
+
+- Page 11 names `xharness` as the published executable and standalone terminal command.
+- `package.json#bin`, the package lock, CLI usage, and command-specific help publish and document
+  `xharness`.
+- ADR-0009 records `xharness` as the sole published executable.
+
+## Proposal
+
+Publish `xagent` as the sole executable mapped to `dist/cli.js`. Invoking `xagent` without a
+subcommand starts the existing OpenTUI terminal; `terminal` remains an explicit alias and the
+existing subcommands remain available. Do not keep `xharness` as a compatibility alias. Keep the
+npm package name, terminal runtime, data/state directory names, and environment-variable names
+unchanged. Update command examples and regression/smoke checks to use `xagent`.
+
+## Alternatives
+
+- Keep `xharness` as an alias. This avoids disruption but does not replace the requested launch
+  command.
+- Rename the npm package. This is unrelated to the executable name.
+- Do nothing. This leaves the requested command unavailable.
+
+## Consequences
+
+- Scripts and shell aliases using `xharness` must change to `xagent`.
+- The rename is a breaking CLI change. It is included before publication of the 4.0.0 candidate;
+  if `xharness` has already been released, the rename requires a new major release.
+- No account, data, state, or server-protocol migration is required.
+
+## Migration
+
+Install `@xingular/harness` and launch the terminal with `xagent`. Update invocations of the former
+`xharness` command. Existing `~/.xingular-harness/{data,state}` contents are reused unchanged.
+
+## Checks
+
+- `npm run typecheck` passed.
+- `npm test` passed: 137 test files, 1,036 tests passed, 3 skipped; the focused CLI test also passed (2 tests).
+- `npm run prove` passed, including the standalone server lifecycle.
+- `node dist/cli.js --help` printed usage beginning with `xagent`.
+- `npm pack --dry-run` passed and included the CLI, TUI bundle, and updated decision records.
+
+The lasting decision is recorded in [ADR-0024](../../decisions/ADR-0024-xagent-command.md).

package/docs/architecture/proposals/PROP-0024-question-sketch-previews.md

@@ -0,0 +1,130 @@
+---
+id: PROP-0024
+title: Add bounded ASCII sketch previews to question choices
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-RUN-3, INV-PAR-1, INV-PAR-2, 02-sessions-and-runs.md, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, docs/parity.md, App/shared/contracts.ts, App/src/modes/chat/QuestionBatchForm.tsx, App/docs/features/FEAT-0013-plan-mode.md, App/docs/architecture/implementation-stage.md, ADR-0025]
+---
+
+# PROP-0024: Add bounded ASCII sketch previews to question choices
+
+**Accepted by the product owner on 2026-10-24; implementation and verification completed in the working tree.**
+
+## Problem
+
+Question choices currently carry labels, descriptions and recommendation state. The validated
+`question.requested` run event persists those fields, but neither the Harness question contract nor
+the App's mirrored contract can carry a choice-specific visual sketch. As a result, an agent cannot
+show a small text diagram to clarify a choice, and neither question surface can preview one while a
+person compares choices.
+
+This changes the persisted run-event payload contract. It must be accepted before changing code or
+the architecture specification.
+
+## Affected rules
+
+- **INV-RUN-3:** “Every run event is validated against its schema, redacted, persisted, and only then
+  relayed to listeners, in order. An event that arrives after the run settled is kept as evidence and
+  never applied or relayed.” This proposal adds validated optional metadata to
+  `question.requested`; it does not change event ordering or persistence.
+- **INV-PAR-1:** “Every capability a person can use in a host is a Harness capability: a foundation
+  service, a world part or a first-party plugin, reachable through server methods. The standalone
+  terminal surfaces it. A host is a presentation of it.” Sketch metadata and the terminal preview
+  are Harness-owned; the App presents the same question data.
+- **INV-PAR-2:** “A capability is complete only when its terminal surface and its host surface both
+  pass acceptance. It lands in the Harness first, together with its terminal surface; the host
+  surface follows.” Both question surfaces must render and test the same metadata.
+
+## Proposal
+
+1. Extend each question input with optional `uiSketch?: true`. This question-level flag enables
+   sketch mode; it applies to that question only, including questions in an `ask_user` batch.
+2. Extend each choice with optional `sketch?: string`. When `uiSketch: true`, every choice must
+   contain a valid sketch. When the flag is absent, choices must not contain sketches. Reject an
+   invalid combination before emitting a question event; do not silently omit or truncate data.
+3. Bound each sketch to 1–8 lines and at most 32 printable ASCII characters per line. Lines are
+   separated by LF. Only bytes `0x20`–`0x7e` and LF are allowed; tabs, CR, terminal controls,
+   escape sequences and Unicode are rejected. The sketch must contain at least one non-space
+   printable character. Interior blank lines and trailing spaces are allowed and preserved exactly.
+   The maximum encoded length is 263 bytes (eight 32-character lines plus seven LF separators).
+4. Add the fields to both Harness question-tool schemas (`ask_user` and terminal
+   `ask_user_question`) and their runtime validation. Add them to the `question.requested` payload
+   schema and preserve them through `RunRegistry` into the persisted event. `question.answered` and
+   `QuestionAnswer` stay unchanged: sketch metadata is never part of an answer.
+5. The terminal question dock renders choice labels and descriptions in wrapping columns. It places
+   one shared, monospace sketch canvas below the choice list, displaying the hovered choice's sketch
+   or, with no hovered choice, the keyboard-focused choice's sketch. It does not create one canvas
+   per choice. Sketch content is rendered as literal text, without Markdown or ANSI interpretation.
+6. The App mirrors the payload schema and preview behavior in `QuestionBatchForm`. Its choice
+   label/description columns wrap at narrow widths, and its shared preview is literal monospace
+   text. Update plan-mode acceptance to cover sketch-enabled questions and record the implementation
+   in the App's implementation-stage log. Update Harness architecture/terminal docs and
+   `docs/parity.md` when implementing.
+7. On acceptance, add ADR-0025 to record the stable question-event and sketch-bounds contract.
+
+The optional flag is intentionally a positive literal, not a free-form renderer configuration.
+Sketches do not introduce an image/attachment type, a host-only surface or a new answer format.
+
+## Alternatives
+
+- **Accept optional sketches without a mode flag.** This leaves it unclear whether sketches are
+  expected, permits partially illustrated questions, and makes the preview's presence ambiguous.
+- **Allow Markdown, Unicode diagrams, ANSI or unbounded text.** Rendering differs across terminal
+  and host, escape/control content creates risk, and unbounded content can overwhelm a question
+  surface.
+- **Use image attachments or a rich-output event.** This adds a separate content/storage/rendering
+  contract for a small, readable diagram and cannot provide the same text fallback in the terminal.
+- **Do nothing.** Keeps the existing event stable but does not let questions explain choices with
+  compact diagrams.
+
+## Consequences
+
+- New `question.requested` events may carry `uiSketch: true` and per-choice `sketch` strings. The
+  event remains backward-compatible: both fields are optional, and old events continue to parse.
+- The App's shared contract must accept the same bounded fields as Harness. A stale host that does
+  not understand the optional metadata can still read the other question fields, but cannot show
+  the preview; parity requires updating the App before marking the feature complete.
+- The question surface gains a bounded preview with no answer semantics. Recommendation ordering,
+  selection, free text, notes, submission and cancellation remain unchanged.
+- There is no run-record layout change or migration. Sketches are stored only in the existing
+  `question.requested` event payload, subject to the existing event redaction and persistence path.
+- Existing question-tool and event callers that omit `uiSketch` behave as before. Calls that enable
+  it must provide a valid sketch for every choice.
+
+## Migration
+
+No migration is needed. New readers accept old question events because the new payload fields are
+optional; new writers validate the flag/choice relationship and bounds. Answer payloads are
+unchanged. The Harness implementation and terminal surface must land first; then the App schema and
+form are updated in a separate App repository change. No live-model request is required for
+verification.
+
+## Checks
+
+After acceptance, verify schema bounds and flag/choice consistency, preservation of literal sketch
+text through both tool paths and persisted events, compatibility with old events, unchanged answer
+payloads, and terminal/App hover/focus preview behavior. Run the focused Harness and App question
+tests, including the isolated question-form browser fixture. Also run:
+
+- Harness: `npm run typecheck`, `npm test`, `npm run build`, `npm run prove`,
+  `python3 scripts/verify-terminal.py --questions-only` at 40×20, 80×24 and 120×40, and a terminal
+  input-latency profile.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`,
+  `cd src-tauri && cargo test`, and the isolated question-form browser fixture.
+
+## Implementation evidence
+
+- Harness: `npm run typecheck`, all 1,041 tests (3 skipped), `npm run build` and `npm run prove`
+  passed. The isolated `--questions-only` PTY check passed at 40×20, 80×24 and 120×40 with
+  `pyte`; the 40-column run checks compact sketch navigation and answers, while wider runs also
+  check wrapped notes and free-text.
+- Input latency profile (160×45, four rounds, loopback provider, no live requests): idle p50/p95/p99/max
+  4.83/9.69/10.02/10.14 ms; history 4.72/9.79/10.41/10.60 ms; streaming 8.36/19.53/21.67/26.00 ms.
+  No keystrokes were missed.
+- App: `npm run typecheck`, `npm test` (566 renderer, 49 sidecar and 7 development-signing passed;
+  one signing test skipped), `npm run check:layers`, `npm run check:ui` and Rust tests (168 passed,
+  1 ignored) passed. The isolated question-form browser fixture passed all 5 tests using the installed
+  system Chrome executable.
+- The first App test run, executed concurrently with other checks, exceeded an existing run-event
+  performance threshold; the full suite passed when rerun alone. No live-model request was made.