@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/11-terminal.md

@@ -0,0 +1,555 @@
+# 11 Terminal
+
+## Purpose
+
+The harness owns a generic interactive terminal application (`xagent`) over a
+persistent Pi session on a variant. It is the standalone way to use the harness, and an
+embedding application can host it in its own PTY. Detail, screen layout and verification evidence
+are in [`../terminal-tui.md`](../terminal-tui.md); this page states the binding parts.
+
+## Components
+
+| Type / module | Role |
+|---|---|
+| `Terminals` (`terminal/terminals.ts`) | Parent side: `prepare` (account, compiled context, trusted resources, run writer) returns a launch specification; `send`, `state`, `input`, `dispose`. |
+| `src/terminal/opentui/` (`app.ts`, `root.tsx`) | The OpenTUI/Solid frontend: lifecycle, submission, commands, decisions, composition, transcript, composer, dialogs. |
+| `src/terminal/opentui/attachments.ts`, `composerMarks.ts` | Composer attachments: pasted images and collapsed large pastes, their atomic labels, and expansion into the prompt text and Pi image content on send. |
+| `src/terminal/tui/runtime.ts` | `AgentSessionRuntime` over `createAgentSession`, `ModelRuntime`, `SessionManager`, `DefaultResourceLoader`. |
+| `src/terminal/socket.ts`, `client.ts`, `control.ts`, `controller.ts` | The session socket, the private control key, and the run controller. |
+| `src/terminal/piExtension.ts` | The bridge extension, loaded last as the trusted inline gate. |
+| `src/terminal/cli.ts` | Wiki and connected-apps commands for the session's shell. |
+
+```text
+Harness parent: account + compiled context + trusted resources + run writer
+       | launch specification / session socket
+Harness terminal child (Bun): OpenTUI application + persistent Pi AgentSessionRuntime
+       | typed native events / plugin UI callbacks
+Screen: transcript above the composer, centred dialogs, full-screen resource browser
+```
+
+## Contracts
+
+- The published executable is `xagent`; `xharness` is not retained as a compatibility alias. With no command, `xagent` starts the interactive terminal. `terminal` remains an explicit alias, and `serve` remains the host-facing RPC path.
+- `TerminalAssets` is `{ node, cli, piExtension, openTui }`. The command is Bun with
+  `--conditions=browser` and `dist/terminal-opentui.js`; no global `pi` is needed.
+- The `piExtension` path is the final prepared extension argument; the runtime loads it as the
+  final trusted inline factory.
+- Each terminal `begin` returns the run's pinned `workspaceRoot` to that extension. Native file
+  writes use the same revalidated atomic helper and OS write scope as SDK sessions. Terminal Bash,
+  including initial `!` commands, defaults to the workspace sandbox and external-hard-link scan;
+  `!outside <command>` requests human-only approval before that exact command runs once; its full
+  escaped command is available in scrollable approval details, and an undersized terminal denies
+  the request. The eligible Full Permission switch is the only standing boundary bypass; remembered
+  per-tool grants do not widen it, and command output never triggers approval or replay.
+- The terminal compiles its prompt once (`compile` + `render`) and keeps that pack; each run
+  records a copy (page 04). Switching the conversation to another variant version (`/variant`,
+  restoring, reverting, or adopting a refinement) restarts the frontend on that version at a turn
+  boundary and resumes the same native conversation (`TerminalRelaunch.variantVersion`, ADR-0065).
+- Each turn a person types records a workspace snapshot before the agent acts (page 02); `/refine`
+  replays the latest one (page 05). The shared compaction checkpoint extension reintroduces the active
+  request and its todo list, as of a compaction during the run, right after the summary until the
+  run settles (ADR-0067).
+- The terminal runtime, not Pi, decides the model a conversation starts on. A fresh conversation
+  starts on the account's latest normal-mode choice; a resumed one keeps the model in its own
+  history while this account offers it and holds credentials for its provider. When it does not,
+  the runtime starts the conversation on the account's newest saved selection (the mode's, then
+  normal's, then the newest in any mode) with that selection's effort, writes that model change
+  into the conversation, and reports it in one notice; the account's `choices.json` is not touched
+  (ADR-0064). With no usable saved selection, Pi's own fallback message stands.
+- Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
+  shared tool alongside its read-only set and restores the normal set on success, failure or
+  interruption, and again after any rebuild from the transcript (page 02, `INV-RUN-8`). The question blocks until answered, then planning continues in the same run. There
+  is no terminal-only question alias (PROP-0040).
+- The approved plan outcome contract on page 02 applies equally to the terminal and server:
+  only `plan_ready` offers a plan card and Implement; `blocked` reports unavailable required input
+  without Implement; `no_plan` is an ordinary reply that offers nothing at all; `invalid` gets at
+  most one shared bounded repair and, if still invalid, a warning and the retained original text.
+  New final replies do not ask free-text questions or use
+  `<plan_clarification>`: clarification uses `ask_user`, which blocks the active run. Repair at
+  Pi's settlement boundary is in the same run and may call `ask_user`. Existing `<proposed_plan>`
+  cards and old transcripts, including clarification blocks, remain intact; see ADR-0077.
+- A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
+  (PROP-0043). A user `!` command submitted during a plan request waits as a separate turn; it
+  cannot run inside the plan's read-only request.
+- The terminal message-delivery contract is Enter to send or queue a follow-up, and
+  Cmd/Ctrl/Alt+Enter to steer an active reply. Pending steering, follow-up and deferred plan/Bash
+  inputs are projected above the working line from Pi's queues and the deferred barrier. Native
+  Follow-up and Steer rows are clickable and open `/follow-up`, which edits, sends the next eligible
+  item, or removes a selected message while preserving attached images. A successful reply keeps
+  Pi's configured queue behavior. At an explicit user-stop boundary, the terminal sends one
+  unconsumed steer before any follow-up and returns the remainder to Pi; retrying requests,
+  provider failures and non-user interruptions do not dispatch the queue. A queued plan or Bash
+  command runs separately after the active reply, and later inputs cannot bypass it through Pi's
+  native queues. Modified shortcuts require terminal support.
+- Current standalone source defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
+  `~/.xingular-harness-dev/{data,state}`. The standalone development launch uses a file SecretStore
+  under its resolved state directory or the `--account-state` one, even when its profile names a
+  host backend; it does not use or alter host credentials. `--account-state <dir>` signs in as the
+  accounts kept in that state directory (its `accounts` folder and `secrets.json`), and
+  `npm run dev` passes the installed state directory, so development and installed launches share
+  one sign-in while keeping their own data, approvals and plugin trust. `--variant <scope>`
+  explicitly selects a variant head.
+  PROP-0040 approves a shared Harness-owned interactive profile, neutral default scope and
+  credential backend; adoption and runtime verification remain in progress. Until that lands,
+  matching roots/scopes is explicit and matching roots alone does not share host Keychain secrets.
+- `Launch.standard` supplies the shared role and folder text. History, Wiki and skill model tools
+  use the session socket; enabled output-trim/budget-guard hooks load through `firstParty.list`.
+- `$name` is a skill invocation at any word start in the composer: the palette opens at the caret
+  and inserts the chosen skill there, keeping the rest of the draft, and every `$name` naming a
+  loaded skill is required for that request. The terminal builds the request-scoped text with
+  `requiredSkillsText` from Pi's loaded skills and appends it as a hidden `xingular-required-skills`
+  custom message. A required skill changes no tool or permission, and the person's message reaches
+  the model unchanged.
+  Pi CLI built-ins (llama.cpp, codemode, tool-search and MCP) are not loaded as a terminal-only
+  resource path. Harness MCP remains available.
+- An empty conversation shows a centered welcome using `env.productName` (default `Xingular Agent`):
+  the first letter of a multiword name is the orange block mark and its remaining words are letter-spaced
+  in blue. The welcome adds a greeting, tagline and `/help` hint without replacing the composer or
+  status bar. Explicit host product names use the same generic formatting.
+- `/remote-control` (`/rc`) lets a phone or iPad continue this session: a page with the pairing
+  link and its QR code, paired devices, and the person's answer to a pair request; `rc` / `rc ●` in
+  the status bar while it is on. `xagent --remote-control` (`--rc`) turns it on at start. The
+  binding rules are page 15.
+- `xagent --worktree [name]` (`-w`) starts in a new managed worktree of the current repository,
+  or in the named one, and prunes older managed worktrees (PROP-0016). A session that names a
+  worktree holds it for its whole life. `/worktree` opens the worktree page; selecting
+  one switches folders by asking the host to restart the frontend there (`TerminalRelaunch.cwd`),
+  as a new conversation: Pi keeps one history per working folder.
+- Slash-command aliases share one registry entry: `/session (resume)` opens the full-screen, searchable
+  saved-session page with unnumbered title and metadata rows; `/history (tree)` navigates branches in
+  the current session, and `/btw (side)` asks a side
+  question through the Harness `SideQuestions` service. It uses the same account/model/effort,
+  mirrors the main run's redacted prompt and public evidence, starts a separate tool-free run, and
+  leaves the main conversation untouched. The dock streams, scrolls and copies the complete answer.
+  Aliases remain callable and searchable, but help and palette show only the canonical
+  entry. `/context` opens the Context page, with Run details and Context usage tabs. Run details
+  shows recorded run configuration, available tools and connectors, skills loaded via `skill_load`,
+  and observed activated extensions; unrecorded facts remain unknown. The run selector stays within the current native conversation, and the page links
+  to `/trajectory` for the selected run. Context usage shows contributor attribution, reserve and
+  free space; `/context growth` opens measured request history and compaction markers. The page
+  reads `terminal.context`, never computes a figure of its own, and says `?` where nothing measured a
+  window. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
+  opens its Limits tab (PROP-0042); `/usage:accounts` opens the All accounts limits tab. These are plugin-owned namespaced routes. All-account refresh reads due providers using their own account credentials without switching the session account. The usage page is a
+  full-screen page with a top tab strip: each window is a label and reset line above a quota-left bar coloured green at
+  50% or more left, amber from 20–49%, and red below 20%. `commands.list`
+  publishes the effective routes; the browser-safe core catalogue is `commands/registry.ts`. First-class Harness commands are unprefixed and live in that registry,
+  independently of plugin command metadata. Every plugin-owned command uses
+  `/<owner-prefix>:<command>`; plugin-owned prompt templates use the same owner namespace as
+  extension commands. A plugin namespace root is offered only for an explicit default: built-in
+  default commands remain supported, and a package's `harness.defaultPrompt` selects its own named
+  template for `/<owner-prefix>:`. Standalone prompt templates retain their existing forms, as does
+  `/skill:<name>` (ADR-0061).
+
+The `/plugins` Proposals tab previews the complete stored files and generated manifest before
+confirmation. Accept and reject pass the preview hash through the control-key-protected socket;
+the proposal service checks it again. Acceptance leaves the package switched off and untrusted.
+
+## Client terminal and the long-lived harness (ADR-0083)
+
+The OpenTUI frontend is a client of the harness by default: `tui/harnessRuntime.ts` implements the
+same `TerminalRuntime` as `tui/runtime.ts`, so the screen code is shared.
+`XINGULAR_TERMINAL_RUNTIME=inprocess` runs the in-process runtime instead, for plugins that need
+their own terminal components (INV-TUI-8).
+
+- **Parent.** `terminal/liveTerminal.ts::LiveTerminal`, created on the first `terminal.live.*`
+  call, runs each turn as `sessions.run { live: true }` of the terminal's own session id, account,
+  folder, history folder, pinned variant version (`{ dir, scope }`), launch sections, Pi's four
+  default tools plus the launch and switched-on world tools, and no gated tools, as the in-process
+  terminal's policy has it. It journals the live session's native events (a newer
+  `message_update` replaces an unread one; at most 4,000) and serves them by long poll.
+- **Routes.** `terminal.live.state`, `.events { after, wait?, waitMs? }`, `.run { text, model?,
+  effort?, resume? | newHistory?, images?, plan?, goal?, command?, initialBashCommand?,
+  hiddenNotes? }`, `.steer`, `.followUp`, `.followUp.clear`, `.interrupt`, `.close { forget? }`,
+  `.rename`, `.pending`, `.pending.wait`, `.approve`, `.answer`, `.answers`. Once a client exists,
+  `terminal.pending|pending.wait|approve|answer|answers|interrupt` and remote control's send and
+  stop reach it instead of `TerminalController`. Pending decisions include the active reply's
+  subagents.
+- **Client.** It keeps the model catalogue, settings, the skills, prompts and themes it lists, and
+  `ModeChoices`. `$name` skills and goal notes go as `hiddenNotes`; a plugin command is sent as its
+  `/<prefix>:<name>` text; `/compact`, `/tree` navigation and HTML export are command runs;
+  `/new`, `/resume`, fork and import change the file it resumes and close the live session; `/session`
+  takes a history file or the session id its runs record. A `!` command is the run's initial Bash.
+  A plan run sends only the plan's tools (`planTools: 'active'`). A mode with no saved model keeps
+  the current one. Closing the client never interrupts a reply; the parent decides.
+- **What the window draws.** Besides the native events, the journal carries `harness_notice` (a
+  plugin's notice, status line, widget or title, and a failed reply's message), `harness_settled`
+  (the reply is over, with its goal state and history file, even when Pi's loop never started) and
+  `harness_dialog` / `harness_dialog_done` (a plugin's `select`, `confirm`, `input` or `editor`,
+  shown with the window's own dialog and closed when another surface answers first; the window's
+  question dock asks `terminal.pending.wait { ownDialogs: true }` and leaves them out). Before the
+  first turn the parent lists the trusted extensions' commands by loading them without a session;
+  one that cannot load stops the window's start, as in process. A session change or a steer first
+  asks the harness whether a reply really runs, so a window a moment behind its event stream does
+  not refuse `/new` or steer a reply that has ended.
+- **Failure.** When the window's harness is unreachable twice in a row, the window closes cleanly.
+  An error nothing caught in the standalone host (a plugin's timer, say) closes the window first,
+  then exits 1. The long-lived harness logs such an error and keeps its other sessions.
+- **Identity.** A client terminal's runs are harness runs: they record Pi's session id as
+  `nativeSessionId`, where an in-process terminal's record the history file. `/todo`,
+  `/trajectory`, `/context`, subagent rows and remote-control history match by the client's id, and
+  a relaunch resumes its history file.
+- **Long-lived harness.** `xagent daemon start|stop|status` runs one harness per state folder
+  (`terminal/daemon.ts`): a lock (`harness.lock`) refuses a second, and `harness.sock` (owner-only)
+  serves the protocol with `daemon.status` and `daemon.stop`. `xagent --daemon` starts it when
+  needed, prepares its terminal there and runs the client frontend. When the window closes while a
+  reply runs, `terminal.detach` keeps the reply and its live session without a window until it
+  settles; `xagent attach [session]` reattaches a new window to it (`prepare { attach: true }`, same
+  folder and account). Without a running reply, closing the window ends the session as before.
+
+## Invariants
+
+- **INV-TUI-1** OpenTUI is the only terminal frontend. Pi's `InteractiveMode` is never constructed
+  ([ADR-0006](../decisions/ADR-0006-opentui-only-terminal.md)).
+- **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. A host owns the
+  PTY and process supervision ([ADR-0001](../decisions/ADR-0001-owned-terminal.md)). In the default
+  client terminal the Pi session runs in the harness process as a live session (ADR-0083); the
+  window keeps composition, input and rendering.
+- **INV-TUI-3** Execution, account isolation, trust, authorization and run recording stay behind
+  their existing layers. The terminal adds no second path for any of them; its runs are written
+  through the controller and the run store.
+- **INV-TUI-4** Changes made through the session socket (`plugins.attach|detach|trust|untrust|configure`,
+  `plugins.proposals.*`, `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
+  `terminal.annotations.*`, `terminal.sideQuestions.*`, `terminal.remoteControl.*`,
+  `terminal.variant.*`, `terminal.refine.*`) require the control key the trusted terminal process claimed once
+  (`control.claim`). The session's shell can read the session token, so the token alone is never
+  enough. A phone paired through `/remote-control` is the one other party that answers decisions;
+  only the control-key holder can start remote control or allow a device (INV-RC-3, INV-RC-7).
+- The terminal watches decisions through the control-key-protected `terminal.pending.wait` revision
+  snapshot. It returns immediately for a changed revision and otherwise waits at most 20 seconds;
+  additions, removals and disposal wake waiters. `terminal.pending` remains available. The terminal
+  reconnects and resynchronizes after errors, and cancels its outstanding request on shutdown.
+- **INV-TUI-5** Every resource reload revalidates the original trusted selection; changed or
+  revoked code needs review and a fresh terminal.
+- **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The in-process terminal
+  keeps a persistent child instead of opening a session per turn; the client terminal (below) runs
+  every turn as a `sessions.run { live: true }` of one live session, which is equally persistent.
+- **INV-TUI-8** A client terminal runs no agent loop, tool or Pi extension of its own. It draws the
+  live session from its native events and its own read of the history file, and every action is a
+  protected `terminal.live.*` call (ADR-0083). Plugin presentation that needs an in-process
+  terminal (custom components, key handlers, renderers, shortcuts) is unavailable there, as it is
+  in a host: extensions get the dialog, notice, status and text-widget subset.
+- **INV-TUI-7** Harness core commands use unprefixed names and are registered independently of
+  feature-plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents`
+  and `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections
+  shortcut. Every plugin-owned terminal command, including a plugin-owned prompt template, uses
+  `/<owner-prefix>:<command>` for required and optional built-ins and Pi packages alike. There are
+  no bare plugin command or template aliases. Completions, help, recognition and dispatch use the
+  same owner-qualified routes. Prefixes are unique to an owner; a prefix collision or duplicate
+  route within an owner, including a template/extension collision, fails closed with owner
+  diagnostics rather than choosing a winner. A package root `/<owner-prefix>:` resolves only to the
+  package's explicitly declared, valid and unambiguous `harness.defaultPrompt`; built-in default
+  commands retain their roots. Standalone prompt templates keep their existing forms and
+  `/skill:<name>` remains reserved for skill invocation. Core commands and their core aliases remain
+  independent of plugin attachment. The prior temporary aliases for promoted core commands are not
+  a route to plugin-owned contributions (ADR-0061).
+- **INV-TUI-8** Terminal sessions use the Harness-pinned workspace root and the same write
+  boundary as SDK sessions. Native file mutations use revalidated atomic replacement under an OS
+  scope; default Bash scans for external hard-link aliases and runs inside the sandbox. The terminal
+  cannot widen the boundary through its socket or native extension. `!outside <command>` requests
+  human-only approval before one execution; the terminal shows the complete escaped command and
+  denies the request if it cannot display details and choices together. stdout/stderr cannot trigger
+  approval or replay. Missing enforcement fails closed. Full Permission bypasses the boundary only
+  for eligible interactive
+  user runs and does not override hard policy denials, read-only or plan mode, unattended work, or
+  refinement restrictions.
+
+## Source map
+
+`src/terminal/**`. Decisions: ADR-0001, [ADR-0004](../decisions/ADR-0004-fullscreen-terminal-layout.md)
+(superseded), ADR-0006, [ADR-0021](../decisions/ADR-0021-required-command-namespaces.md)
+(superseded by [ADR-0031](../decisions/ADR-0031-plugin-command-owner-namespaces.md)),
+[ADR-0024](../decisions/ADR-0024-xagent-command.md),
+[ADR-0027](../decisions/ADR-0027-connected-sketch-display.md),
+[ADR-0028](../decisions/ADR-0028-xingular-agent-product-identity.md),
+[ADR-0031](../decisions/ADR-0031-plugin-command-owner-namespaces.md),
+[ADR-0034](../decisions/ADR-0034-first-class-harness-terminal-commands.md),
+[ADR-0061](../decisions/ADR-0061-strict-plugin-command-namespaces.md),
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md). Experiments:
+EXP-0001, EXP-0002 in `../experiments/`.
+
+## Session name in the working line (PROP-0010)
+
+The bridge registers `session_name` against Pi's `getSessionName` / `setSessionName` APIs.
+The native `session_info_changed` event invalidates the frontend's cached snapshot and
+refreshes the working line. Both the active and retained completion line append
+` – <name>` after duration and token rate, for example
+`Working (2m, 50 tok/s) – Add web browser integrations`. Unnamed sessions omit the suffix.
+A substantive first turn also receives a provisional name through the terminal policy; a refused
+or failed name leaves the session unnamed.
+
+Each user turn appends a hidden `xingular-session-state` custom message with the current name,
+this run's empty todo, and the previous run's todo as context. The message is request-only and
+never changes the compiled stable pack. A first turn is marked as such; later turns say the todo
+list resets for each run.
+Names use the existing terminal text sanitization, remain outside the verb shimmer, and
+truncate at the right edge. Manual `/name` and existing long names remain supported.
+
+## Doctor command
+
+`/doctor` opens a command page and runs local readiness checks. Refresh and retry are local;
+Live checks opens an explicit selection followed by account/model, destination, cost and isolation
+confirmation. The page polls structured reports, retains findings after cancellation, and cancels
+on close. No command text is sent to the conversation model. See [Doctor](../doctor.md).
+
+## Resource browser (PROP-0013)
+
+`/harness` owns broad navigation for Foundation, Variant, Skills, Plugins, Connections, Tools and
+Library. `/skills`, `/connections` (`/mcp`), `/tools` and `/components` are shortcuts into that
+browser. `/plugins` opens the focused local plugin manager (Plugins, Trust and Packages tabs); `/hub`
+opens the separate Community catalog (Catalog and Installed tabs). The Hub Catalog shows Community
+entries across supported types; Installed retains receipts from every channel with its channel
+visible. Registry/document entries offer bounded payload Preview; Pi packages do not. Current
+availability in `/harness` comes from the live resource loader and active tool registry,
+independently of saved configuration and the latest variant head.
+
+Every `terminal.browser.*` call requires the private control key, including bounded resource
+inspection, local imports, connection management and browser settings. Direct plugin package
+install/update/remove and attachment/trust/settings actions use protected `plugins.*`; Hub catalog
+list/install/uninstall use protected `hub.*`. Hub-owned package removal keeps the receipt and
+resource ownership in the Hub service. These routes are adapters to the existing services, not
+another loader, attachment store, gate or secret store. Browsing neither executes plugin code nor
+connects MCP.
+The browser uses the full terminal with persistent section tabs (PROP-0014); wide screens keep
+inventory beside details, actions and content, while compact screens keep inline details under
+the same tabs. The separate `/plugins` and `/hub` pages also use full-screen layouts with persistent
+section tabs, responsive inventory/details panes and their existing protected operations. Other
+command pages remain centered except `/settings`, `/accounts`, `/plugins`, `/hub`, `/context` and `/usage:`, which use
+full-screen page layouts.
+Accounts keeps Accounts/Pools tabs, search and account-service operations.
+Wide terminals show selected-account details beside the list; Enter or a primary click opens grouped
+actions in that inspector. Compact terminals replace the list with a full-page account detail view
+and its grouped actions. Enter opens the selected account; Escape returns to the list while
+preserving its section, query and selection across navigation and resizing. Tab/Shift+Tab moves focus
+between tabs, the list and (when open) actions; Left/Right changes a focused tab and Up/Down moves
+the focused list or action list. Account actions retain their Session, Account, Sign-in and Remove
+groups; pool actions remain grouped under Manage and Remove. See the
+[terminal guide](../terminal-tui.md#blocks-and-pages) for layout and interaction.
+
+`/settings` is a full-screen page with category tabs, search, settings list and a device-local Browser
+tab. It selects the isolated browser or Brave profile; selecting Brave requires explicit confirmation.
+The tab also shows bridge status, pairing instructions and `allowPrivate`. Brave pairing is explicit,
+site access is granted separately in the extension popup, and the in-page badge provides Pause and
+Stop. Brave exposes normal tabs only, never Incognito; the extension does not request history or
+cookie permissions or export cookies. A disconnect refuses calls without switching backends.
+Enabling private address access requires confirmation and allows both agent browsing and annotation
+capture to reach localhost and private networks. It is off by default.
+
+## Worktrees command (PROP-0016)
+
+`/worktree` opens a page of the managed worktrees of the repository the session works in: make a
+managed or permanent worktree, switch the terminal to one (or back to the main checkout), create a
+branch on a detached one, hand changes off in either direction, remove one (with a snapshot when it
+holds work, never the one this terminal uses), restore a removed one, prune older ones, and trust
+the repository's setup script. The page calls `terminal.worktrees.*` routes, which use the same
+`Worktrees` service as the `worktrees.*` server methods. `xagent worktree <command>` offers the
+same actions from a shell.
+
+## Question dock
+
+Pending questions appear in a flat block above the composer, with a tab for each 1–2 word question
+label above its title. Tabs can be clicked; Left/Right also switch questions and preserve staged
+answers. The header has no pager or collapse control, and the dock stays expanded until the answer
+is accepted or Escape cancels the pending question. A refused answer stays in the dock with its
+choices, notes and typed text, and the refusal reason appears inside the dock; the same rule is
+checked before the answer leaves the terminal. While it is active, the chat composer and its lower
+status bar are hidden. `n` opens a note for the focused selected choice; Tab and Shift+Tab
+navigate existing note fields, the free-text answer and the action without creating notes. Notes
+and the “Something else” answer wrap across lines. Choice recommendations remain visual only and
+never preselect an answer.
+
+Every choice uses one shared measured layout: a marker gutter, a one-third label cell, a two-cell
+gap, and the remaining description cell. Column boundaries align across all rows at every terminal
+width, including compact widths. Text wraps within its cell; a missing description keeps its cell
+and columns never stack. Recommendation text uses `(Rec.)` when the label column is fewer than 14
+cells. Below 60 terminal columns, the dock uses a compact hint. Multi-select choices use `✓`
+when selected and `○` when unselected, matching checklist glyphs; single-choice options remain
+numbered.
+
+The dock body has bounded height and vertical scrolling; question tabs and answer/action controls
+stay outside that scrolling region. PageUp/PageDown scroll the body and Ctrl+Home/End jump to its
+beginning/end while the dock is active, rather than scrolling the transcript. Focused choices and
+note fields are brought into view. Ordinary arrows retain question/choice navigation; Shift+arrows
+pan the sketch horizontally or vertically.
+
+When a question sets `uiSketch: true`, one shared border-only monospace preview below the choices
+shows the hovered or focused choice's ASCII wireframe, with no visible caption or extra left rule.
+Sketch source supports up to 80 columns by 24 lines (page 02) and remains literal ASCII in
+persistence. The terminal projects every valid sketch onto a fixed 80-column content canvas, padding
+short rows and extending standalone hyphen dividers to that width. The outer preview frame stays
+bounded to the available dock width and the canvas remains horizontally pannable when it does not
+fit. Within the canvas, recognized ASCII table-border rows—including a title between horizontal
+runs—and enclosed vertical table edges become connected box-drawing glyphs, while internal framed
+tables retain their original widths and positions. For a high-confidence frame with matched `+`
+corners, missing or slightly displaced side edges may be filled or moved only through whitespace to
+the established boundary columns; interior text is never moved or overwritten, and conflicting or
+ambiguous rows remain literal. This is not a global `+|-` substitution: prose, content operators,
+ordinary pipes and unrecognized rows remain literal. Source sketches and all persisted whitespace
+remain unchanged; padding, projected glyphs and expanded dividers exist only in the display.
+
+There is no wrapping, reflow, truncation or markup interpretation. A bounded two-axis viewport makes
+all overflow reachable by panning. Moving focus changes the preview without changing the staged
+answer. Projected glyphs and expanded dividers never enter persisted events or answers; the wire
+contract is unchanged. See [PROP-0025](proposals/PROP-0025-contextual-question-wireframes.md),
+[ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md) and the approved display amendment
+[PROP-0026](proposals/PROP-0026-connected-sketch-display.md) /
+[ADR-0027](../decisions/ADR-0027-connected-sketch-display.md), amended for the fixed canvas by
+[ADR-0080](../decisions/ADR-0080-fixed-width-question-sketch-canvas.md), and
+[PROP-0028](proposals/PROP-0028-normalize-question-wireframes.md) /
+[ADR-0029](../decisions/ADR-0029-normalized-question-wireframe-borders.md). Isolated production
+PTY verification is retained in `docs/evidence/terminal-wireframe-normalization/`; it establishes
+cell topology for bounded fixtures, not every emulator/font or live-model sketch quality.
+
+## Web annotations commands (PROP-0017, PROP-0018, PROP-0048)
+
+`/annotate:` opens the annotate page, a full-screen page with two tabs. `/annotate:notes` opens it on
+**All annotations**: every annotation in the data root, with search, and reveal, edit, resolve or
+reopen, share with this session or stop sharing, and delete. An annotation is private until shared;
+this session's agent then reads it with `page_notes_list` and `page_notes_read`.
+
+The **Annotate** tab is the panel beside the window being inspected.
+
+- **Ways to start it:**
+  - `/annotate: [url]`: the capture browser (its own window and profile, separate from the agent's
+    browser). With no address, the page returns to the window that is still open, with its URL and
+    the inspector on, and asks for one in its own inline field only when no window is open.
+  - `/annotate: --app [port | address] [name]`: an app's own windows over its DevTools port. With no
+    port, the page lists the apps answering on one (`annotations.capture.discover`).
+  - `/annotate: --bridge [name]`: app windows that load the page bridge script, which the page shows.
+- **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in
+  the page with **Annotate** and **Annotate & send**. Every annotation is shared with this session
+  at once.
+- **Groups:** Unsent (n) and Sent, for this session.
+- **Other keys:** `s` sends every unsent annotation as one run of this session, confirming the
+  page-origin ones once first; `o` types a page address; `a` lists apps with a DevTools port, with
+  *Start an app with a DevTools port*, *Type a DevTools port*, *Use the page bridge*; `t` picks a
+  window; `Tab` switches tab. A key pressed while the page is busy gets a notice, never nothing.
+- **Commands:** `/annotate:submit <request>` sends the unsent annotations with the request after
+  them; `/annotate:clear` resolves the unsent ones and stops sharing them.
+- **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|confirm|confirmAll|send|clear|discover|launch`
+  act only on this terminal's session and need the control key.
+
+A page that opens a dialog as it starts gets it above itself: `PageOverlay` starts its page when the
+host reports the overlay mounted.
+
+## Todo list (PROP-0006, PROP-0045, PAR-001)
+
+Terminal sessions register the shared `todo_write` tool. The extension validates each list with
+the same tool code and sends it as `todo` telemetry; the controller emits it as `todo.updated` on the
+active run, so `runs.todo` and continuation read terminal runs too. The gate treats it as read-only,
+plan mode allows it, and terminal children inherit it. The transcript shows each write as a todo
+block (`✓` done, `●` in progress (warning yellow), `○` pending) under a `Todo · n of m done` header
+instead of a tool row; a failed or malformed call stays a tool row. `/todo` reads the latest
+non-side-question run of this terminal's native session and appends the same card as a snapshot,
+without a model request; an empty list is a one-line notice. `/checklist` remains its alias for one
+release.
+
+## Work-slice checkpoint (PROP-0041)
+
+Terminal tool-gate and work-slice refusals are relayed as `tool.refused` events with a code and reason; the original refusal text remains the tool response. Interrupted terminal runs record stop codes for work-slice limits, user abort, stalls and terminal closure.
+
+Terminal replies carry the same work-slice guard as structured runs, with no budget by default
+(ADR-0081): no tool-call, time or token limit. When a limit is set (below), the guard refuses the
+next call and asks the model to stop and report where it is. An ordinary terminal reply settles as it ends (INV-RUN-15, ADR-0075): the terminal
+never sends it back and never marks it unfinished from the todo list. A `/goal` is the only layer
+that continues a reply; a goal that stops blocked, paused or at a limit sends a harness-written
+`checkpoint` and the `needs_person` or `unfinished` code, which the controller records on the active
+run, so an App reading the same session sees the handoff. No model judges an ordinary reply. A reply that
+reaches a budget someone set, after doing work, continues in place as its next slice (ADR-0070): a
+`xingular-slice-continue` message in the same run, a checkpoint and a notice per boundary, up to
+`maxSlices` (8 by default). A fruitless, blocked, failed, aborted or plan slice, or one whose todo items are all
+done, is not continued; the reply then settles `interrupted` with terminal reason `slice_complete`
+so the person or a host can continue it. A checkpoint card in the transcript is not built yet
+(PAR-004). Start the terminal with key=value pairs such as `XINGULAR_WORK_SLICE=maxToolCalls=15,maxSlices=3`
+to give replies a budget; `off` also disables the compaction guard. Neither is persisted, so the
+next launch without it restores the default of no budget.
+
+## `/goal` (ADR-0072, INV-RUN-16)
+
+`/goal <objective>` sets the session's goal and starts work at once; `--rounds N` and `--hours H`
+before the objective set this goal's caps (30 rounds, 8 hours by default). Bare `/goal` shows the
+status (status, objective, rounds, time used, last check, and the commands that apply). `/goal edit`
+asks for a new objective (the same goal, its usage kept), `pause` stops a running reply and keeps the
+goal, `resume` continues it, `clear` removes it. A subcommand matches only as the whole argument, so
+"/goal pause now" is an objective. Setting a goal while an unfinished one exists asks first. Esc or
+Ctrl-C on a running goal pauses it, as in Codex. The status bar shows `Pursuing goal (2m, round
+3/30)`, `Goal paused (/goal resume)`, `Goal stalled (/goal resume)`, `Goal hit usage limits (/goal
+resume)`, `Goal unmet (...)` or `Goal achieved (...)`.
+
+The goal lives in the Pi session as a `xingular-goal-state` entry, so a reopened conversation shows
+it, as `paused`: nothing resumes by itself. The model gets `get_goal` and `update_goal` only while a
+goal exists (INV-TOOL-9). The goal loop runs before slice continuation; a goal's slices continue even
+when every todo item is done. `/goal` is a `session`
+command that uses `sessions.run` with `goal` (page 10); in plan mode the loop stays silent.
+
+## Liveness and a reply that stops working (INV-RUN-14, ADR-0054)
+
+While a reply is live the extension sends `heartbeat` telemetry every 30 seconds, carrying the work
+slice counters it already keeps (steps, elapsed time, last tool, compactions, slice and the call
+budget); the controller records it as `heartbeat` on the active run, so the run sweep settles a
+terminal reply that stopped reporting by the same five-minute rule as a structured one.
+
+A heartbeat proves the turn is alive, not that it is working. A reply that produces no event other
+than a heartbeat for fifteen minutes — the state a model request that never returns leaves it in —
+is ended: the controller queues the same `interrupt` command the person's Esc queues, the native turn
+aborts, and the run records `interrupted` with reason `stalled`. Pi's abort reports back through
+`terminal.interrupt` as Esc does; the controller passes that interrupt on as `stalled`, not
+`user_abort`, when the stall watch asked for it. A reply whose oldest running tool
+has run for thirty minutes ends the same way, and a reply waiting on an approval or question is never
+cut short. An interrupt, a stall included, also ends a settling reply's wait for its subagents
+(`terminal.subagents.delivery`).
+
+The client terminal (ADR-0083) has no controller of its own: its replies are harness runs, so
+`runTurn` heartbeats and applies the same stall rule (page 02, INV-RUN-14), and the live session of a
+stalled reply is closed. The in-process runtime keeps the controller's watch.
+
+## Subagent activity monitor
+
+During an active parent run, the terminal polls a private read-only monitor once per second. It
+projects the flat set of child and nested-child runs with task, status, elapsed time, the latest
+tool name, the child's agent profile (name and colour, PROP-0029), the title the parent gave it
+(PROP-0030), counts from the child's own todo list, the pinned account label, effective model and
+effort, and cumulative usage totals. Model and effort come from the volatile launch selection; the
+latest provider-reported model supersedes the launch model when usage is available. Usage is an
+explicit projection of token, cache, cost, request-count and context-window totals. Per-request
+payloads and reasoning summaries do not enter the monitor. The child's own `session_name` is not
+projected; it names the child's session, not its row. Tool summaries, other arguments, output and
+todo item text never enter the monitor. The latest completed tool name remains visible across
+one-second snapshots until new tool or response activity replaces it. The monitor exposes no
+controls to steer or stop children.
+
+The live rows sit under the status line, after one blank row, with no heading. Each row reads, in
+order: the status mark (`○` queued, a running row that shows the working spinner's frame in the profile's colour (warning for a copy of the parent), `●` waiting in the accent,
+`✓` done, `✕` failed, `!` stopped), the profile name in its colour (`subagent`, muted, for a copy
+of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` when the child
+keeps a todo list. Active rows come first, at most three, then `+N more · /subagents`; a narrow
+terminal cuts the title first. `/subagents` opens the searchable full roster, with a colored
+profile and normal-color title on its first line, then muted account, model, effort and usage
+metadata on its second line. One blank row separates each two-line entry. Narrow rows truncate this
+lower-priority summary without hiding the title.
+At parent settlement, the terminal makes a final monitor read and keeps the latest parent's rows
+visible until the next parent run starts.
+
+The monitor also projects the parent run itself as a `main` row (profile `main`, a reserved name,
+in the theme's primary colour) with the same account, model, effort, usage, activity and todo
+fields. The `/subagents` page pins it first and counts only children in its header; the rows under
+the status line omit it, since the status line already describes the main agent.
+
+Every turn marks its run on the native branch (`xingular-subagent-owner`), and `ready` sends those
+owners. When a conversation opens or is switched to with no run active, the monitor is rebuilt from
+the branch's latest top-level run in this folder and its descendants, by folding their saved events
+with their final status. Runs a stopped process left active were already marked `interrupted`.
+The rows show under the status line and on the page until the next parent run starts (ADR-0043).
+The projection remains read-only and scoped to one parent run; a switch to a conversation with no
+such run clears it, as does terminal disposal. It is not a persisted event or public server method.
+
+## Agent profiles (PROP-0029)
+
+`/agents` opens the Agents page over `terminal.agents.list|create|remove`, which call the same
+`agents/profiles.ts` functions as `agents.*`. It lists built-in, global, project and variant
+profiles, and files that cannot be read. The detail pane shows the colour, description, tools,
+plugins, variant, model, effort, file and instructions. Enter on a row offers: for a person's own
+profile, edit (opens the file in `$VISUAL`/`$EDITOR` with the renderer suspended), copy and delete
+(confirmed); for a built-in or variant profile, copy. New profile asks for a name and a place
+(project or global), writes the template and opens it. The terminal passes its pinned variant to
+`Subagents.register`, so the variant's c5 names are profiles there too.