@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md

@@ -0,0 +1,179 @@
+---
+id: PROP-0018
+title: Inspector-style page notes, a fix queue to the agent, and app windows as capture targets
+status: Implemented
+created: 2026-10-23
+updated: 2026-10-23
+affects: [INV-STO-3, INV-SRV-1, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0018: Inspector, fix queue and app targets for page notes
+
+Requested by the owner on 2026-10-23. They chose these four things:
+- the popover's three choices: Save, Queue, Send now
+- the popover drawn inside the page
+- Electron over its DevTools port, and real Tauri windows on macOS, as targets
+- the Harness and terminal first, then the App pane
+
+Implemented for the Harness and terminal on 2026-10-23 and in the App source on 2026-10-24 (store migration, `page_notes_*` tools, Annotate panel). The Harness implementation is included in the 4.0.0 candidate. Native WKWebView gestures still need acceptance in the running App.
+
+## Problem
+
+Page notes (PROP-0017) take several prompts each. The person picks a kind, confirms in the terminal, types the note in the terminal, then shares it. A note never reaches the agent unless the person asks the agent to read it. Capture works only on http(s) pages, in a new browser context. So a person cannot point at a component of the app they are building, say what to change, and have the agent do it, and they cannot do it at all in a desktop app's own window.
+
+## Affected rules
+
+- `INV-SRV-1`: new methods `annotations.queue`, `dequeue`, `confirm`, `queued`, `createAndAct`, `compose`, `delivered`, `send`, `annotations.capture.*` and `annotations.bridge.start`. All are additive.
+- `INV-STO-3`: one new state-directory file, `<state dir>/notes-bridge.json`, which holds the page bridge's port and token. It is owned by `annotations/bridge.ts`.
+- 07: a new model tool, `page_notes_mark_fixed`. It is the first page-note tool that writes.
+- 13: "Capture happens in the terminal's visible browser or in a host web view" now also covers app windows, either over a loopback DevTools port or through the page bridge.
+
+## Proposal
+
+### Records
+
+A note gains an optional `delivery`:
+`{ state: 'queued' | 'sent' | 'fixed', sessionId, queuedAt, autoSend?, confirm?, sentAt?, runId?, fixedAt?, summary? }`.
+
+- `status` (`open` | `resolved`) is unchanged, and only a person resolves a note.
+- Queueing a note shares it with that session, because the agent must be able to read what it is asked to fix.
+- New history operations: `queue`, `dequeue`, `deliver`, `mark_fixed`.
+- A note captured in an app window carries `source.app: { kind: 'cdp' | 'bridge', name }`. Its URL may then also use `file:`, `app:`, `tauri:`, `electron:` or `asset:`, still without credentials. Web notes keep the http(s) rule.
+
+### Inspector and popover
+
+`begin` takes a third kind, `inspect`.
+- Hovering draws an outline and a `tag.class W×H` chip.
+- A click, or a drag over text, opens a popover beside the target. It has a comment box and three buttons:
+  - **Create annotation**: `save`
+  - **Ask agent to fix**: `queue`
+  - **Proceed now**: `send`
+- ⌘/Ctrl+Enter is Proceed now; with Shift it is queue.
+- Everything is drawn in a closed shadow root.
+- The page never receives the press or click on what is inspected, nor anything typed in the popover.
+- Inputs, secrets, `[data-sensitive]` elements, frames, shadow roots and custom elements are never picked, as in PROP-0017. (Open shadow roots and readable custom elements became pickable in [PROP-0038](PROP-0038-annotate-open-shadow-roots.md).)
+- The inspector stays on after each comment.
+- A new operation, `next`, returns `{ active, documentId, url, title, result }`, one comment at a time.
+- `toast` shows a short status in the page.
+- The helper's global key moves to `…page.v2`.
+
+### Trust
+
+What the page helper returns is page data. Whether a "Proceed now" goes straight to the agent depends on **where the helper ran**, decided by the Harness:
+- **Chromium (the capture browser and DevTools-attached apps):** the helper runs in an isolated script world (`Page.createIsolatedWorld`). The DOM is shared, but the JavaScript globals are not, so the page cannot read or forge results. These results are trusted and sent directly.
+- **Page bridge and host web views without isolation:** results are untrusted. A send becomes a queued note with `confirm: true`, which the person confirms in the panel before it goes out.
+
+A host's `annotations.createAndAct` passes `trusted: true` only for comments from its own UI or an isolated world.
+
+### Delivery
+
+`compose(notes)` builds one instruction for a batch:
+- It contains each note's id, where it is, the element (tag, role, name, selector, text) or the quoted text, and the person's comment.
+- Page-derived text is labelled untrusted and fenced; the comment is in a `comment` fence.
+- It asks the agent to call `page_notes_mark_fixed`.
+- A batch holds at most 20 notes.
+
+The `NoteDeliveries` service (`annotations/delivery.ts`) handles sending:
+- **Terminal session:** the batch goes out as a new run through `TerminalSessions.send`, and the notes become `sent` with that run id. If the session is busy, the notes stay queued with `autoSend`.
+- **Host session:** the reply is `{ state: 'host', text, ids }`. The host starts the run (`sessions.run`) and reports it with `annotations.delivered`.
+- **When a run ends** (`runs.listen`, after 250 ms), the session's `autoSend` notes go out. Notes still waiting for a person's confirmation are skipped. For a host session, the service emits the notice `annotations.ready`.
+- Every change emits `annotations.changed`.
+
+### Model tool
+
+`page_notes_mark_fixed { id, summary }` works only on a note shared with the caller. It sets `delivery.state = 'fixed'` with the summary. It never resolves a note and never changes grants. It is not read-only, so it is unavailable in plan mode.
+
+### Capture targets
+
+`AnnotationCapture` captures in one target per key:
+- **`web`:** the visible browser window from PROP-0017. Its helper calls now run in an isolated world.
+- **`cdp`:** an app started with a DevTools port, attached with `connectOverCDP` to a loopback address only. It uses the app's own windows, and nothing is routed or opened. Releasing the target disconnects; the app keeps running. The default name is `App at <host:port>`.
+- **`bridge`:** a loopback HTTP server (`annotations/bridge.ts`) serves `/page-notes.js?token=…`. That script is the page helper plus a long-poll loop that pulls operations and posts replies.
+  - The port and token are kept in `notes-bridge.json`, so the script tag in an app stays valid across restarts.
+  - Requests need the token and the host name `127.0.0.1:<port>` or `localhost:<port>`, which blocks DNS rebinding.
+  - At most 32 windows; a window is dropped after 45 s without a poll.
+
+Methods (`key`, `windows`, `selectWindow`, `inspect`, `stopInspect`, `next`, `toast`) behave the same for all three.
+
+`inspectStep` (`annotations/inspect.ts`) is the one loop step the terminal and hosts share. It:
+1. reads the next comment;
+2. creates the note with `source.surface` and `source.app`;
+3. applies the action with the target's trust;
+4. shows a toast in the page.
+
+### Server methods
+
+| Method | Input | Reply |
+|---|---|---|
+| `annotations.queue` | `{ id, sessionId, expectedVersion?, autoSend? }` | `Note` |
+| `annotations.dequeue` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.queued` | `{ sessionId }` | `{ notes }`, oldest first |
+| `annotations.createAndAct` | `{ note, action, sessionId?, trusted? }` | `{ note, send }` |
+| `annotations.compose` | `{ sessionId, ids? }` | `{ text, ids }` |
+| `annotations.delivered` | `{ ids, sessionId, runId }` | `{ notes }` |
+| `annotations.send` | `{ sessionId, ids? }` | `{ state: sent \| busy \| host \| empty, … }` |
+| `annotations.capture.attach` | `{ key, kind, endpoint?, name? }` | `{ kind, app, windows, bridge? }` |
+| `annotations.capture.target` | `{ key }` | `{ kind, app, inspecting, windows }` |
+| `annotations.capture.selectWindow` | `{ key, window }` | `{}` |
+| `annotations.capture.open` | `{ key, url? }` | `{ url, title }` |
+| `annotations.capture.inspect` / `stopInspect` | `{ key }` | `{ captureId }` / `{}` |
+| `annotations.capture.next` | `{ key, sessionId?, surface? }` | `{ active, trusted, app, note, send, message, … }` |
+| `annotations.capture.release` | `{ key }` | `{}` |
+| `annotations.bridge.start` | `{}` | `{ port, token, scriptUrl, snippet }` |
+
+### Terminal
+
+`/annotate` is now a full-screen pane. The browser window or the app's window is the canvas, and the pane is the panel beside it.
+
+Ways to start it:
+- `/annotate [url]`: a web page or dev server
+- `/annotate --app <DevTools address | port> [name]`: an app over its DevTools port
+- `/annotate --bridge [name]`: shows the script tag to load in the app
+
+The pane:
+- The header shows the target, the window, and whether the inspector is on.
+- Sections: **Queue (N)**, **Sent and fixed**, and **Saved**.
+- Keys:
+
+  | Key | Action |
+  |---|---|
+  | `i` | inspector on/off |
+  | `s` | send the queue, confirming page-origin notes first |
+  | `x` | take the selected note out of the queue |
+  | `t` | choose a window |
+  | `Enter` | note menu: reveal, send, confirm, queue, unqueue, edit, resolve, delete |
+
+- It polls `terminal.annotations.next` every 400 ms while the inspector is on.
+
+New terminal routes: `target`, `attach`, `windows`, `selectWindow`, `inspect`, `stopInspect`, `next`, `queue`, `dequeue`, `confirm`, `send`. They queue and send only to the terminal's own session and need the control key. `/notes` stays the plain list.
+
+## Alternatives
+
+- **The host draws the popover.** The App's native web view covers React content, and each host would build its own. The owner chose in-page drawing.
+- **A WebSocket bridge.** It would need a new dependency. Long-polling over plain HTTP is enough for one person's clicks, and `text/plain` posts avoid CORS preflights.
+- **Trust whatever the page reports.** A hostile page could start a run with its own text. The isolated world, plus confirmation where isolation is impossible, prevents that.
+- **Do nothing.** The owner's request goes unmet.
+
+## Consequences
+
+- **Notes:** the record has a new optional field; older notes read unchanged.
+- **Protocol:** additive methods and notices.
+- **Hosts:** the App replaces its bottom-strip panel with a pane, and calls `annotations.*`, `annotations.capture.*` for app targets, and `compose`/`delivered` around its own `sessions.run`.
+- **Agent tools:** sessions get a third page-note tool.
+
+## Migration
+
+No data migration: `delivery` is optional. The App's PAR-011 migration (`annotations.import`) is unchanged. The bridge settings file is created on first use and can be deleted to get a new port and token.
+
+## Checks
+
+| What | Where |
+|---|---|
+| Queue, delivery, busy and auto-send, confirmation, host hand-off, mark fixed, app URLs | `annotations/delivery.test.ts` |
+| Inspector in a real page: element, text drag, sensitive field refused, Escape, toast, cancel | `annotations/pageScript.test.ts` |
+| Isolated world (the page cannot see the helper), reload re-arm, DevTools attach leaves the app running, bridge round-trip as untrusted, stable port and token | `annotations/capture.test.ts` |
+| Bridge token, host-name check and relay | `annotations/bridge.test.ts` |
+| Pane | `terminal/tui/pages/annotatePage.test.ts` |
+| Terminal send and auto-send on run end | `terminal/terminal.test.ts` |
+| Host compose and delivered | `npm run prove` |

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.