@xingular/harness 1.0.0 → 1.1.1

package/docs/architecture/proposals/PROP-0030-subagent-title.md

@@ -0,0 +1,86 @@
+---
+id: PROP-0030
+title: A parent-set title for each subagent, shown in the roster
+status: Accepted; implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [02-sessions-and-runs.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, terminal-tui.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0030: A parent-set title for each subagent, shown in the roster
+
+## Problem
+
+A live subagent row shows the child's `session_name` once the child calls it successfully, and
+otherwise the whole brief (`subagentsWidget.ts`, `safe(item.name) || safe(item.goal)`). The brief
+can run to 4000 characters, so the row shows a paragraph of instructions cut to the terminal width.
+In a live run of two explorers, neither had a name, and both rows showed their briefs.
+
+The child is the only one asked to name itself. The "six words at most" rule is in the
+`session_name` tool description and the prompt, and nothing checks it. A child may skip the call,
+or its call may fail, and the row then shows the brief for the whole run. The parent, which wrote
+the brief, knows the purpose in a few words and names nothing.
+
+## Affected rules
+
+No invariant changes. The contracts that change are:
+
+- `spawn_subagent` (page 07): a `title` parameter. The model must supply it.
+- `subagents.spawn` (page 10): an optional `title`.
+- The run record (page 02): an optional `title`, stored like `profile` (PROP-0029).
+- The live roster and `/subagents` (page 11, `terminal-tui.md`): the row title is the parent's title.
+- Parity (page 14, `parity.md`): the Subagents row names the title, not the child's session name.
+
+## Proposal
+
+- `spawn_subagent` takes `title`, a required string: one short imperative of at most six words,
+  such as "Map the auth flow". It is checked the way `session_name` is: whitespace collapses, and
+  control characters and empty values are refused with a message the model can act on.
+- `subagents.spawn` takes an optional `title` with the same check. A host or script that omits it
+  gets `briefTitle(brief)`: the first non-empty line of the brief, collapsed and capped at 60
+  characters. The model cannot omit it.
+- The child run record stores `title`, an optional text field (`RunRecord.title`). The spawn sets it
+  before the child launches, and a startup failure keeps it. A record written before this change
+  has no title and reads as `briefTitle(goal)`.
+- The terminal roster, the `/subagents` label and its search read the title. The row no longer
+  reads the child's `session_name`. The child still names its own Pi session with `session_name`,
+  and that name stays in the child's session history.
+- The transcript's `spawn_subagent` row shows the title, and the brief only when no title is given.
+
+## Alternatives
+
+- **Require the child to name itself.** This is the current design. The child must be prompted,
+  and the rule is not checked. The screenshot shows it was skipped.
+- **Make `title` optional in the tool.** A model skips an optional field the same way it skipped the
+  child's name. Rejected: the tool requires it, and only programmatic callers may omit it.
+- **Generate the title with an extra model call.** It costs a call and adds latency to every spawn.
+  Rejected.
+- **Keep the child's name first, then the parent's title.** A child that names itself would still
+  replace the title the parent chose. Rejected: one source keeps the roster stable.
+- **Do nothing.** Rows keep showing briefs whenever the child does not name itself.
+
+## Consequences
+
+- Applications built on the harness get a new required argument in `spawn_subagent`, and an
+  optional one in `subagents.spawn`. A model that omits `title` gets an error and retries.
+- The run record gains an optional field. Readers that ignore unknown fields are unaffected. The
+  App reads run records in Rust and does not render the roster.
+- The terminal monitor drops the child's `name` field. Its tests change with it.
+
+## Migration
+
+No data moves. Records without `title` read as `briefTitle(goal)`. The change can be undone by
+removing the parameter; records written with `title` stay readable, because the field is optional.
+
+## Checks
+
+- `src/sessions/subagentService.test.ts`: the title is stored on the child run, and defaults from the
+  brief's first line when omitted. An over-long title is refused.
+- `src/tools/spawnSubagent.test.ts` (new): the tool refuses a missing or over-long title before it
+  starts a child, and cleaning and the brief fallback behave as stated.
+- `src/terminal/subagentMonitor.test.ts`: the row takes the parent's title, and the child's
+  `session_name` does not change it.
+- `src/terminal/opentui/subagentsWidget.test.ts` and `model.test.ts`: the row and the transcript row
+  show the title.
+- `npm run typecheck`, `npm test`, and `npm run prove` (the spawn path is server code), then the App's
+  checks, because a harness change requires them.

package/docs/architecture/proposals/README.md

@@ -35,6 +35,31 @@ proposal is `Accepted`.
 
 | [PROP-0012](PROP-0012-release-baseline.md) | Public 1.0.0 distribution and generic browser ownership | Accepted; candidate implementation | INV-BND-2, 00, 07, 11, 13 | 2026-10-22 |
 
+| [PROP-0013](PROP-0013-resource-browser.md) | Unified terminal resource browser | Implemented; working tree verified | 03, 06, 09, 11 | 2026-10-22 |
+
+| [PROP-0014](PROP-0014-fullscreen-browser-tabs.md) | Full-screen browser with persistent section tabs | Implemented; working tree verified | 11, terminal-tui.md | 2026-10-23 |
+
+| [PROP-0015](PROP-0015-one-capability-surface.md) | One capability surface: the terminal and every host offer the same capabilities | Accepted | INV-BND-2, new INV-PAR, 00, 11, 14, AGENTS.md | 2026-10-23 |
+
+| [PROP-0016](PROP-0016-managed-worktrees.md) | Managed git worktrees in the terminal and every host | Harness/terminal in 4.0.0 candidate; App create integration, remaining actions PAR-012 | INV-BND-2, D-5, INV-STO-3, INV-SRV-1, 00, 02, 10, 11, 12, 14 | 2026-10-23 |
+
+| [PROP-0017](PROP-0017-page-annotations.md) | Page annotations captured in the headed browser or a host's web view | Harness/terminal in 4.0.0 candidate; App source pending native-gesture acceptance | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+
+| [PROP-0018](PROP-0018-annotation-queue-and-app-targets.md) | Inspector-style page notes, a fix queue to the agent, and app windows as capture targets | Harness/terminal in 4.0.0 candidate; App source present, native WKWebView acceptance pending | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+| [PROP-0019](PROP-0019-contextual-side-questions.md) | Harness-owned contextual side questions across surfaces | Implemented; working tree verified | INV-RUN-1/3/5, INV-GATE-1, INV-PLG-1/5, INV-CAP-1, INV-SRV-1/2, INV-PAR-1/2, 02, 04, 06, 07, 10, 11, 12, 14, ADR-0023 | 2026-10-24 |
+| [PROP-0020](PROP-0020-builtin-feature-plugins.md) | Built-in feature modules and namespaced plugin commands | Implemented; included in 4.0.0 candidate | INV-PLG-5/6, INV-TUI-2/7, INV-SRV-1, 06, 11, 13, 14 | 2026-10-24 |
+| [PROP-0021](PROP-0021-command-namespaces-and-duplicates.md) | Required built-in commands and duplicate command suppression | Implemented | INV-TUI-7, INV-PAR-1, 11, 14, ADR-0021 | 2026-10-24 |
+| [PROP-0022](PROP-0022-plan-only-questions.md) | Keep question tools available only in interactive plan mode | Implemented | INV-RUN-8, 02, 04, 06, 07, 11, 14, parity, ADR-0022 | 2026-10-24 |
+| [PROP-0023](PROP-0023-xagent-cli-name.md) | Rename the published CLI command to xagent | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0024 | 2026-10-24 |
+| [PROP-0024](PROP-0024-question-sketch-previews.md) | Add bounded ASCII sketch previews to question choices | Implemented; working tree verified | INV-RUN-3, INV-PAR-1/2, 02, 10, 11, 14, parity, App question contract and plan-mode docs, ADR-0025 | 2026-10-24 |
+| [PROP-0025](PROP-0025-contextual-question-wireframes.md) | Strict question columns and contextual ASCII wireframes | Implemented; working tree and isolated fixtures verified | INV-RUN-3, INV-PAR-1/2, 02, 11, 14, terminal-tui.md, parity, ADR-0026 | 2026-10-24 |
+
+| [PROP-0026](PROP-0026-connected-sketch-display.md) | Connect structural sketch lines in the terminal display | Implemented; working tree and isolated fixtures verified | 11, 14, terminal-tui.md, parity, ADR-0027 | 2026-10-24 |
+| [PROP-0027](PROP-0027-xingular-agent-product-identity.md) | Use Xingular Agent as the default Harness product identity | Accepted; implemented and verified | INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md, terminal-tui.md, ADR-0028 | 2026-10-24 |
+| [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
+| [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
+| [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+
 Numbers are four digits, start at `0001`, and are never reused.
 
 ## Template

package/docs/decisions/ADR-0009-xharness-command.md

@@ -1,15 +1,15 @@
 ---
 id: ADR-0009
 title: Publish the Harness CLI as xharness
-status: accepted
+status: superseded
 created: 2026-10-22
-updated: 2026-10-22
+updated: 2026-10-24
 related: [PROP-0005]
 supersedes: null
-superseded_by: null
+superseded_by: ADR-0024
 ---
 
-# ADR-0009 — Publish the Harness CLI as xharness
+# ADR-0009 — Publish the Harness CLI as xharness (superseded)
 
 ## Context and decision drivers
 
@@ -35,4 +35,5 @@ subcommands, data/state directory names, and `XINGULAR_HARNESS_*` environment va
 
 - The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
 - CI, the packed-tarball smoke test and the npm publication blocker are recorded in
-  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md).
+  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md). The executable-name decision
+  is superseded by [ADR-0024](ADR-0024-xagent-command.md).

package/docs/decisions/ADR-0014-public-release-baseline.md

@@ -9,8 +9,9 @@ updated: 2026-10-22
 # ADR-0014 — A compiled public SDK and explicit 1.0.0 baseline
 
 The user approved [PROP-0012](../architecture/proposals/PROP-0012-release-baseline.md) through the
-release implementation plan. Keep @xingular/harness and xharness, use Apache-2.0 for original
-code, publish compiled ESM/declarations, and preserve upstream notices and historical releases.
+release implementation plan. Keep @xingular/harness and the then-current `xharness` executable, use
+Apache-2.0 for original code, publish compiled ESM/declarations, and preserve upstream notices and
+historical releases. The executable-name portion was superseded by [ADR-0024](ADR-0024-xagent-command.md); the other release-baseline decisions remain.
 
 Generic isolated browser execution belongs in the foundation; App browser presentation, tab
 sharing and OS/computer integration remain with the host. No application concept or object is

package/docs/decisions/ADR-0015-resource-browser.md

@@ -0,0 +1,28 @@
+# ADR-0015 — One terminal browser for resources and discovery
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-22).
+Related: [PROP-0013](../architecture/proposals/PROP-0013-resource-browser.md),
+[source study](../study/tui-resource-browser.md).
+
+## Context
+
+Skills, plugins, Hub items and variant additions have different entry points and misleading
+availability labels. Users need to identify what exists, what this session can use, and what changes later.
+
+## Decision
+
+Use a shared responsive browser with section shortcuts, Installed/Discover views, provenance and
+inspection before management. Join saved configuration with actual runtime resources; never infer
+loaded state from attachment settings or the latest variant head. Keep the loader, gate and service
+ownership intact. Show foundation and variant as different ownership layers.
+
+## Alternatives
+
+Separate pages retain navigation fragmentation. A single combined remote/local list confuses
+installation with availability. A full editor expands the task beyond browse/manage.
+
+## Consequences
+
+The browser adds a protected service adapter and focused navigation state. Resource reads are bounded,
+credentials stay masked, and installing does not activate resources. Existing commands remain shortcuts.
+Implementation and verification evidence belong in the terminal guide, not in this decision record.

package/docs/decisions/ADR-0016-fullscreen-browser-tabs.md

@@ -0,0 +1,31 @@
+# ADR-0016 — Full-screen browser with persistent resource tabs
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-23).
+Related: [PROP-0014](../architecture/proposals/PROP-0014-fullscreen-browser-tabs.md),
+[ADR-0015](ADR-0015-resource-browser.md).
+
+## Context
+
+The unified browser's centered layout and nested section/detail navigation leave little space
+for inventory and inspection. The user wants one full-page workspace with resource-section tabs.
+
+## Decision
+
+Resource-browser commands use a full-screen surface with persistent section tabs. Wide terminals
+show inventory beside an inspector containing metadata, actions and content. Compact terminals
+show inline detail views under the same tab strip. Tab moves focus, arrows change a focused tab,
+and mouse tab selection targets the section directly.
+
+TerminalPage declares its presentation and optionally supports direct tab selection. Centered
+presentation remains the default for other pages. Resource services keep their existing ownership.
+
+## Alternatives
+
+Keeping the centered panel restricts working space. Replacing the list with details at all widths
+loses inventory context. Variant c1–c8 tabs do not match the selected resource-navigation intent.
+
+## Consequences
+
+The browser owns responsive inventory/inspector focus and preserves section search and selection.
+Small terminals use compact tab navigation. There are no storage or protocol changes.
+Verification belongs in the terminal guide and its automated page and PTY checks.

package/docs/decisions/ADR-0017-one-capability-surface.md

@@ -0,0 +1,34 @@
+# ADR-0017 — One capability surface for the terminal and every host
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0015](../architecture/proposals/PROP-0015-one-capability-surface.md),
+[PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[PROP-0017](../architecture/proposals/PROP-0017-page-annotations.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Capabilities grew in the App alone, so the Harness terminal could not do what the App did, and
+ownership between the repositories was unclear. The owner wants the App to be a richer
+presentation of the Harness, with the same capabilities as the terminal, and room for future
+host-only surfaces such as interactive agent output.
+
+## Decision
+
+Every user capability is a Harness capability with a terminal surface (INV-PAR-1, INV-PAR-2).
+Capabilities that need an operating-system object only a host has define a generic contract and a
+terminal fallback (INV-PAR-3). Host-only surfaces own no capability and are registered by the host
+with an owner decision (INV-PAR-4). Managed worktrees and page annotations move into the Harness
+under PROP-0016 and PROP-0017. Orchestration across agents (organizations, routed chats, group
+chats, delegated work queues) is not a Harness capability; the App removes it and keeps it only in
+an archived version.
+
+## Alternatives
+
+Keeping the App as the full product leaves two products. Identical front ends cannot accommodate
+presentation a terminal cannot show. Doing nothing lets the gap grow.
+
+## Consequences
+
+New user features start in the Harness with a terminal surface. The register `docs/parity.md`
+tracks gaps until both surfaces pass. Hosts keep native bridges, windows and presentation.

package/docs/decisions/ADR-0018-builtin-feature-plugins.md

@@ -0,0 +1,35 @@
+# ADR-0018 — Built-in feature modules and namespaced commands
+
+Status: Accepted (owner requested implementation of the plan, 2026-10-24).
+Related: [PROP-0020](../architecture/proposals/PROP-0020-builtin-feature-plugins.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[11 Terminal](../architecture/11-terminal.md).
+
+## Context
+
+First-party plugin descriptors existed, but runtime assembly, server handlers and TUI command
+dispatch were centralized in separate files. Plugin commands shared the same unprefixed namespace
+as core commands. Duplicate Pi extension commands were silently assigned suffixes by the SDK.
+
+## Decision
+
+Use a typed internal registry for built-in plugin modules. Modules own their existing plugin
+descriptor and may supply world parts, public method handlers, terminal command metadata and
+lifecycle. Foundation keeps plugin loading and trust, capability attachment and gating, the TUI
+framework, and the generic isolated browser engine. Plugin commands use `/plugin:<command>`;
+duplicate names are rejected with owner diagnostics. The ownership taxonomy is documentation only.
+
+Retire old unprefixed forms for doctor, worktree, trajectory, subagents, notes and annotate at the
+cutover. Public server methods and stored data keep their current names and shapes.
+
+## Alternatives
+
+Keeping direct central dispatch preserves the current drift between plugin descriptions and
+runtime ownership. Exposing categories in public metadata adds a schema without a runtime need.
+Letting the SDK suffix duplicate commands makes their identity depend on extension load order.
+
+## Consequences
+
+New Harness-managed features register through the built-in plugin registry. The terminal owns the
+page adapter and UI; feature plugins contribute namespaced command metadata. Embedding hosts see
+the existing method table and capability contracts.

package/docs/decisions/ADR-0019-managed-git-worktrees.md

@@ -0,0 +1,31 @@
+# ADR-0019 — Managed Git worktrees are a Harness capability
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Worktrees isolate source changes, but an App-only implementation leaves terminal users without
+that capability and lets each host invent its own lifecycle and safety rules.
+
+## Decision
+
+The Harness owns the worktree registry, lifecycle, session leases, and server methods. Managed
+worktrees are disposable detached checkouts in device-local state; permanent worktrees are retained.
+Creating a worktree disables repository filters, carries source changes only under the defined
+copy/apply rules, and runs setup scripts only after exact-text trust. Leases prevent concurrent
+removal; removal snapshots recoverable work before deleting a checkout. Hosts call `worktrees.*`
+rather than managing these records independently, and the terminal provides the reference surface.
+
+## Alternatives
+
+Keeping the feature in the App breaks terminal/host parity. Putting large worktree checkouts inside
+source repositories pollutes them and makes the data visible to tools and editors. Platform-specific
+copy-on-write clones were deferred in favor of Git's portable linked-worktree behavior.
+
+## Consequences
+
+`worktreeId` identifies a Harness-managed worktree in a run. Worktree state is device-local under
+the Harness state directory. Hosts can present richer controls but do not own lifecycle or safety.

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.