@xingular/harness 1.0.0 → 1.1.1

package/docs/README.md

@@ -9,18 +9,38 @@ its pages are descriptive, while the architecture specification remains binding.
 Current implementation: [Harness terminal frontend](terminal-tui.md). The package-level
 [README](../README.md) describes the embedding API, accounts, plugins, memory and storage.
 
+**Parity:** [Capability parity register](parity.md) lists every capability, its terminal surface
+and its host surface ([14 Surfaces and parity](architecture/14-surfaces-and-parity.md) is binding).
+
+**Future work:** [Feature backlog](future-work.md) records planned concepts. Backlog entries do not
+change the binding architecture or describe implemented capabilities.
+
 | ID | Record | Type | Status | Related |
 |---|---|---|---|---|
-| ADR-0014 | [Public release baseline](decisions/ADR-0014-public-release-baseline.md) | Decision | Accepted; candidate preparation | [Release procedure](releases/README.md), [PROP-0012](architecture/proposals/PROP-0012-release-baseline.md) |
+| PROP-0026 | [Connect structural sketch lines in the terminal display](architecture/proposals/PROP-0026-connected-sketch-display.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0027](decisions/ADR-0027-connected-sketch-display.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
+| ADR-0027 | [Project structural ASCII sketch lines into connected terminal borders](decisions/ADR-0027-connected-sketch-display.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md), [14 Surfaces and parity](architecture/14-surfaces-and-parity.md) |
+| FW-0001 | [Agent Modes, starting with Router Agent Mode](future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode) | Future work | Candidate; requires architecture proposal before implementation | [Architecture glossary](architecture/README.md#glossary), [Feature guide](features/README.md#planned-agent-modes) |
+| PROP-0025 | [Strict question columns and contextual ASCII wireframes](architecture/proposals/PROP-0025-contextual-question-wireframes.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0026](decisions/ADR-0026-contextual-question-wireframes.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
+| ADR-0026 | [Align question columns and preserve contextual ASCII wireframes](decisions/ADR-0026-contextual-question-wireframes.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0025](architecture/proposals/PROP-0025-contextual-question-wireframes.md), [02 Sessions and runs](architecture/02-sessions-and-runs.md), [11 Terminal](architecture/11-terminal.md) |
+| ADR-0025 | [Store bounded ASCII sketches with question requests](decisions/ADR-0025-question-choice-sketches.md) | Decision | Accepted; working tree implementation verified | [PROP-0024](architecture/proposals/PROP-0024-question-sketch-previews.md) |
+| ADR-0024 | [Publish the Harness CLI as xagent](decisions/ADR-0024-xagent-command.md) | Decision | Accepted; implemented in the 4.0.0 candidate | [PROP-0023](architecture/proposals/PROP-0023-xagent-cli-name.md) |
+| ADR-0020 | [Page annotations and delivery are Harness-owned](decisions/ADR-0020-page-annotations.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0017](architecture/proposals/PROP-0017-page-annotations.md), [PROP-0018](architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md), [parity register](parity.md) |
+| ADR-0019 | [Managed Git worktrees are a Harness capability](decisions/ADR-0019-managed-git-worktrees.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0016](architecture/proposals/PROP-0016-managed-worktrees.md), [parity register](parity.md) |
+| ADR-0018 | [Built-in feature modules and namespaced commands](decisions/ADR-0018-builtin-feature-plugins.md) | Decision | Accepted; 4.0.0 candidate | [PROP-0020](architecture/proposals/PROP-0020-builtin-feature-plugins.md) |
+| ADR-0017 | [One capability surface for the terminal and every host](decisions/ADR-0017-one-capability-surface.md) | Decision | Accepted; implementation in 4.0.0 candidate, App parity gaps tracked | [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), [parity register](parity.md) |
+| ADR-0016 | [Full-screen browser tabs](decisions/ADR-0016-fullscreen-browser-tabs.md) | Decision | Accepted; working tree verified | [PROP-0014](architecture/proposals/PROP-0014-fullscreen-browser-tabs.md) |
+| ADR-0015 | [Unified resource browser](decisions/ADR-0015-resource-browser.md) | Decision | Accepted; working tree verified | [PROP-0013](architecture/proposals/PROP-0013-resource-browser.md), [source study](study/tui-resource-browser.md) |
+| ADR-0014 | [Public release baseline](decisions/ADR-0014-public-release-baseline.md) | Decision | Accepted; 1.0.0 published; 4.0.0 candidate in preparation | [Release procedure](releases/README.md), [PROP-0012](architecture/proposals/PROP-0012-release-baseline.md) |
 | ADR-0013 | [Evidence-based diagnostics with opt-in live probes](decisions/ADR-0013-doctor.md) | Decision | Accepted; working tree implementation | [PROP-0011](architecture/proposals/PROP-0011-doctor.md), [Doctor guide](doctor.md) |
 | SPEC | [Harness architecture specification](architecture/README.md) | Specification | Binding; as of 2026-10-21 | [Proposals](architecture/proposals/README.md), [Known drift](architecture/README.md#known-drift) |
+| STUDY-0002 | [Proactive autonomy: a harness with its own readable agenda](study/proactive-autonomy.md) | Study | Research and three feature hypotheses; not implemented | [Proactive-system sources](study/autonomy-sources.md), [engineering sources](study/autonomous-engineering-sources.md), [known drift D-11](architecture/README.md#known-drift) |
 | STUDY-0001 | [Agent-harness arm study](study/00-index.md) | Study | Arms 01–10 audited (core sources); matrix + roadmap done; remaining-source fills pending | [insights.md](study/insights.md), [roadmap.md](study/roadmap.md), [`/btw` comparison](study/btw-comparison.md) |
 | DESIGN-0001 | [System-prompt design: fixed foundation + adapting harness](system-prompt-design.md) | Design | Draft — not yet accepted; refs current `compile.ts`/tree contracts | STUDY-0001 (arms 01, 10), [roadmap.md](study/roadmap.md) T1-1/9 |
 | EXP-0001 | [Terminal input latency profile](experiments/EXP-0001-terminal-input-latency/plan.md) | Experiment | Completed on one local machine; slow-machine validation pending | ADR-0001, [Profile instructions](terminal-tui.md#input-performance-profile) |
 | ADR-0012 | [Agents name their own native Pi sessions](decisions/ADR-0012-native-session-names.md) | Decision | Accepted; working tree implementation verified | [PROP-0010](architecture/proposals/PROP-0010-session-names.md) |
 | ADR-0011 | [The harness is a fixed foundation running a mutating variant](decisions/ADR-0011-foundation-and-variants.md) | Decision | Accepted; implemented in 5.0.0 | [PROP-0009](architecture/proposals/PROP-0009-foundation-and-variants.md), [Foundation and variants](architecture/00-overview.md#foundation-and-variants) |
 | ADR-0010 | [Lessons from ordinary runs live in the Wiki](decisions/ADR-0010-lessons-in-the-wiki.md) | Decision | Accepted; working tree implementation | [PROP-0008](architecture/proposals/PROP-0008-lessons-from-runs.md), [08 Memory and history](architecture/08-memory-and-history.md), [feature-gap review](study/feature-gap-review.md) |
-| ADR-0009 | [Publish the Harness CLI as xharness](decisions/ADR-0009-xharness-command.md) | Decision | Accepted; implementation verified, npm publication pending authorization | [PROP-0005](architecture/proposals/PROP-0005-xharness-cli-name.md), [11 Terminal](architecture/11-terminal.md) |
+| ADR-0009 | [Publish the Harness CLI as xharness](decisions/ADR-0009-xharness-command.md) | Decision | Superseded by ADR-0024 | [PROP-0005](architecture/proposals/PROP-0005-xharness-cli-name.md), [11 Terminal](architecture/11-terminal.md) |
 | ADR-0007 | [A fixed Reporting section shapes the final reply](decisions/ADR-0007-reporting-section.md) | Decision | Accepted; working tree implementation | [PROP-0001](architecture/proposals/PROP-0001-reporting-section.md), [04 Prompt](architecture/04-prompt.md) |
 | EXP-0002 | [OpenTUI typing latency against Pi and opencode](experiments/EXP-0002-opentui-typing-latency/plan.md) | Experiment | Completed on one local machine (Apple M2) | ADR-0006, EXP-0001, [Profile instructions](terminal-tui.md#input-performance-profile) |
 | ADR-0006 | [OpenTUI is the only terminal frontend](decisions/ADR-0006-opentui-only-terminal.md) | Decision | Accepted; working tree implementation | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |

package/docs/architecture/00-overview.md

@@ -11,9 +11,11 @@ of the harness is improved from evidence (refinement). It knows a *caller*, a *s
 ## Layers
 
 ```text
-Application (for example the App repo)      agents, groups, tasks, projects, worktrees, UI, PTY, keychain
+Host (for example the App repo)             presentation, windows, PTY, keychain, native OS bridges, host-only surfaces
    │  seven extension points (01) and the server protocol (10)
-Harness (this package)                      variants, prompt, sessions, runs, gate, Wiki, history, plugins, MCP, refinement, terminal
+Harness (this package)                      every capability: variants, prompt, sessions, runs, gate, Wiki, history,
+                                            plugins, MCP, refinement, world tools, worktrees, annotations,
+                                            and the reference terminal frontend
    │  Pi SDK: createAgentSession, ModelRuntime, SessionManager, DefaultResourceLoader
 Pi                                          model calls, native JSONL history, tool execution, extensions
 ```
@@ -21,17 +23,23 @@ Pi                                          model calls, native JSONL history, t
 - **Pi** supplies the model runtime, native history, tool execution and the extension API.
 - **The harness** decides everything Pi is given: the account folder, the prompt, the tools, the
   extensions, skills and prompts it may load, and the gate in front of each tool call. It records
-  every run.
-- **The application** supplies what only it knows, through the extension points, and reads what
-  the harness records.
+  every run. It owns every capability a person uses, and its standalone terminal surfaces each one
+  (page 14, `INV-PAR-1`).
+- **A host** presents the same capabilities with its own UI, supplies what only it knows through
+  the extension points, and reads what the harness records. The terminal and a host offer the same
+  capabilities; a host may add registered host-only surfaces (`INV-PAR-4`).
 
 **Belongs in the harness:** Pi sessions and accounts, variants and refinement
 (Propose–Probe–Compose, selection, the experience library), the prompt compiler and its delivery,
 project notes (the Wiki), recall, the tool gate and standing approvals, connectors (MCP), terminal
-sessions and their owned standalone frontend, generic web/isolated-browser tools, and the server protocol.
+sessions and their owned standalone frontend, generic web/isolated-browser tools, managed git
+worktrees (PROP-0016), page annotations (PROP-0017), and the server protocol.
 
-**Stays in the application:** agents, groups, conversations, tasks and coordination, projects and
-worktrees, App browser UI and tab sharing, computer use, windows, the PTY, the keychain, and application UI.
+**Stays in the host:** windows, the PTY, the keychain, native operating-system bridges (a WebKit
+tab, computer control) behind Harness contracts (`INV-PAR-3`), presentation, and registered
+host-only surfaces (`INV-PAR-4`). Orchestration across agents (organizations, routed chats, group
+chats, delegated work queues) is not a Harness capability; a host that wants it must first bring it
+here through a proposal, with a terminal surface.
 
 This package is consumed as source by the App's sidecar and is meant to be embedded by other
 applications, so a change here changes every application built on it.
@@ -102,6 +110,7 @@ opens the data root.
 | `apps` | `ConnectedApps` | `mcp/service.ts` | 09 |
 | `hub` | `Hub` | `hub/hub.ts` | 09 |
 | `terminals` | `Terminals` | `terminal/terminals.ts` | 11 |
+| `worktrees` | `Worktrees` | `worktrees/service.ts` | 02, 14 |
 | `bus` | `Bus` (state-changed notices) | `core/bus.ts` | 10 |
 
 Modules with no member of their own: `variant/` (functions over the variant store), `prompt/compile.ts`,
@@ -132,18 +141,20 @@ Modules with no member of their own: `variant/` (functions over the variant stor
 | **V** Verification | Isolated refinement probes and answer-free selection |
 | **G** Governance | The per-call gate, standing approvals, account pinning, redaction |
 
-The application's column (PTY, worktrees, roles, tasks, review, schedules, UI) is in the parent
-`AGENTS.md` and the App's architecture pages.
+The host's column (PTY, windows, native bridges, presentation) is in the parent `AGENTS.md` and
+the App's architecture pages. Page 14 states how the terminal and a host share capabilities.
 
 ## Invariants
 
 - **INV-BND-1** The harness imports nothing from an application. Application data reaches it only
   through the extension points (page 01) or the server protocol (page 10).
-- **INV-BND-2** The harness names no application and no application concept (agent role, group,
-  task, pane, worktree, handoff, App browser workspace, computer use) in code paths it reads or text a model or
-  person sees. Text names the product through `env.productName` (default `Xingular Harness`;
-  `{product}` in a tool description). Ids such as `agentId`, `projectId` and a variant `scope` are
-  opaque; names come from `Directory` or `CallerContext.agentName`.
+- **INV-BND-2** The harness names no application or application concept (agent role, group, task,
+  pane, handoff, App browser workspace, computer use) in code paths it reads or text a model or
+  person sees, except for its canonical product name `Xingular Agent`. Text names the product through
+  `env.productName` (default `Xingular Agent`; `{product}` in a tool description); an embedding host
+  may supply another product name. Ids such as `agentId`, `projectId` and a variant `scope` are opaque;
+  names come from `Directory` or `CallerContext.agentName`. A managed git worktree is a Harness
+  object since PROP-0016.
 - **INV-BND-3** A new need of one application is met by a generic extension point or option,
   never by a branch on an application's name or concept.
 - **INV-BND-4** Variants, the prompt compiler and Wiki notes are synchronous (`variant/`, `prompt/`,
@@ -156,4 +167,5 @@ The application's column (PTY, worktrees, roles, tasks, review, schedules, UI) i
 ## Source map
 
 `src/harness.ts`, `src/index.ts` (public exports), `src/core/` (env, caller, bus, errors, fs,
-text, index), `src/cli.ts` (command line).
+text, index), `src/cli.ts` (command line). Boundary decisions: [PROP-0015](proposals/PROP-0015-one-capability-surface.md),
+[ADR-0017](../decisions/ADR-0017-one-capability-surface.md).

package/docs/architecture/02-sessions-and-runs.md

@@ -17,6 +17,7 @@ records everything the run does as validated events.
 | run store functions | `sessions/runStore.ts` | `saveRun`, `updateRun`, `persistEvent`, `appendEvent`, `readEvents`, `markInterruptedRuns`, `runFamily`, `listRuns`. |
 | `RunRecord`, `RunEvent`, schemas | `sessions/contracts.ts` | The one contract every session shares. |
 | `Subagents` | `sessions/subagentService.ts` | `spawn`, `wait`, `results`, delivery receipts, recovery. |
+| `SideQuestions` | `sessions/sideQuestions.ts` | Starts, reads and interrupts independent tool-free runs using bounded context from the main conversation (PROP-0019). |
 | plan mode | `sessions/planMode.ts` | `planSection`, `planRefusal`, `PLAN_READ_ONLY_TOOLS`. |
 | `Approvals` | `sessions/approvals.ts` | Standing approvals (page 07). |
 | history selection | `sessions/history.ts` | `selectHistory`: which native history file a run continues. |
@@ -33,8 +34,8 @@ records everything the run does as validated events.
 5. `saveRun` with status `queued`, the account, `harnessScope` and `harnessVersion`.
 6. Compile the prompt (`sessionLaunch`, page 04): a stable system prompt and an optional context
    update.
-7. `runs.start` the live run; build the tool list (broker, harness tools, `ask_user`, subagent
-   tools, provider tools) and the gate.
+7. `runs.start` the live run; build the tool list (broker, harness tools, the plan-eligible
+   `ask_user`, subagent tools, provider tools) and the gate.
 8. Open Pi through the `SessionFactory`, with resources loaded in order: disk extensions chosen by
    the harness, variant extensions, inline extensions, and the gate last.
 9. Record `nativeSessionId`, register the run with `Subagents`, start `runTurn`, and return
@@ -53,6 +54,16 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `reaction.added`, `agent.message`, `checklist.updated`, `artifact.added`, `file.changed`, `usage.updated`,
   `account.status`, `status.changed`, `failed`, `completed`. Each has a payload schema in
   `runEventPayloadSchemas`.
+- **Question sketches** (PROP-0025, ADR-0026; originally PROP-0024, ADR-0025). `question.requested` may include `uiSketch: true`
+  and `sketch` text on each choice. If enabled, every choice must have a sketch; otherwise no
+  choice may carry one. A sketch is 1–24 LF-separated lines, at most 80 printable ASCII characters
+  per line (1,943 bytes maximum), with at least one visible character. Tabs, CR, other controls,
+  escape sequences and non-ASCII text are rejected. Whitespace, including interior blank lines and
+  trailing spaces, is preserved literally in the persisted request event. Tool guidance requests
+  contextual UI wireframes with actual panel/table structure and neighboring elements, consistent
+  across alternatives; generation quality is guidance, not a schema guarantee. Old events remain
+  valid without a data rewrite; readers with the old bounds must update before accepting larger
+  sketches. `question.answered` and `QuestionAnswer` are unchanged.
 - **Checklist** (PROP-0006): `checklist.updated` carries the whole list the model last wrote with
   `checklist_write`, `{ items: { text, status: pending | in_progress | completed }[] }`, at most 50
   items. The latest event replaces every earlier one; `checklistOf(events)` reads it.
@@ -61,14 +72,32 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   application: stored and returned, and only `mode` and `trigger` are read.
 - **Triggers the harness reads:** `user` (may carry an initial Bash command), `probe` and
   `improver` (refinement, page 05), `reflection` (lessons, page 08). Runs with the last three are
-  never asked about: the gate refuses what would need a person.
+  never asked about: the gate refuses what would need a person, and they receive no question tool.
+  Only attended plan runs may newly receive `ask_user`.
+- **Side questions** (PROP-0019). `sideQuestions.start` creates a separate run with trigger and
+  relation `side-question`, a fresh native history, the selected account/model/effort, no variant,
+  and an empty frozen capability set. It combines the parent's persisted effective prompt and
+  public run events with the surface's visible transcript and selected references, after redaction
+  and fixed bounds. Hidden reasoning and attachment bytes are omitted. A supplied parent run must
+  belong to the supplied parent session. `sideQuestions.read` and `interrupt` require the side run's
+  session id. The run is not a subagent or continuation and never changes the parent.
 - **Subagents.** `spawn_subagent` / `wait_subagents` for the model; `subagents.spawn`, `wait`,
   `results` for the host (`sessions.spawnSubagent` is a compatibility alias). Child runs have
   `relation: 'subagent'` and `parentRunId`. Nesting defaults to 1, at most 3 (`subagentDepth`).
-- **Plan mode** (`plan: true`). The tool list is unchanged; the gate refuses everything outside
-  `PLAN_READ_ONLY_TOOLS`, provider tools marked `readOnly`, and calls a provider marks
-  `planModeSafe`. The plan instruction arrives as a dynamic section; the reply ends with one
-  `<proposed_plan>` block.
+  The child's record carries `title`, the short name the parent gave it (PROP-0030).
+- **Agent profiles** (PROP-0029). `agent` names a profile: built-in (`worker`, `explorer`),
+  `<data root>/agents/<name>.md`, `<project>/.xingular/agents/<name>.md`, or a c5 definition of
+  the parent's variant, later sources winning (`agents/profiles.ts`). A profile narrows the
+  child's tools and plugins (`agents/narrow.ts`), may choose its variant, model and effort, and
+  frames it with a "Your role" section. The child's record carries `profile`; the spawn result
+  carries `agent` and any `unavailableTools`. A run that may spawn lists every profile in its
+  `subagents` section.
+- **Plan mode** (`plan: true`). The stable system prompt is unchanged. An attended plan run may
+  include `ask_user`, subject to the caller's frozen capabilities; the gate refuses everything
+  outside `PLAN_READ_ONLY_TOOLS`, provider tools marked `readOnly`, and calls a provider marks
+  `planModeSafe`. The plan instruction arrives as a dynamic section; for UI-related plans it asks
+  the model to explore distinct design directions, compare trade-offs and recommend one, using
+  contextual `uiSketch` questions when helpful. The reply ends with one `<proposed_plan>` block.
 - **Continuation** (PROP-0007). `continuationOf(root, runId, sessionDir?)` (`runs.continuation`)
   says whether a stopped run can be continued: `resumable`, a `reason` when not (`not_found`,
   `active`, `completed`, `no_history`, `history_missing`), the exact native history to reopen,
@@ -77,22 +106,35 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `SessionRunInput.continueFrom` starts a **new** run from it: it reopens that history, records
   `resumedFromRunId`, pins the same account, variant version and capability set (anything different
   fails with `continuation_mismatch`; a run that cannot be continued fails with
-  `continuation_unavailable`), defaults empty text to "Continue from where you stopped.", and adds
+  `continuation_unavailable`). If the earlier snapshot includes `ask_user`, an automatic or
+  refinement-triggered continuation fails with `continuation_mismatch` rather than narrowing it.
+  Empty text defaults to "Continue from where you stopped.", and the new run adds
   a dynamic `continuation` section (order 26) saying where the earlier run stopped. The next run
   without `continueFrom` withdraws it. `Recovery.interruptedRunIds` lists the runs `open` marked
   interrupted.
+- **Worktrees** (PROP-0016). When `run.worktreeId` names a worktree in the Harness registry
+  (`worktrees/`), the run works in that worktree's folder (the given `cwd` is replaced), holds a
+  lease on it (holder: the session id, with `git worktree lock`) until the run completes, fails or
+  is interrupted, and records the id. An id the registry does not know is stored and returned as
+  the caller's own field, as before. A terminal session holds its worktree for its whole life.
 - **Usage** (`usage.updated`). `inputTokens` is uncached input; `cacheReadTokens` and
   `cacheWriteTokens` are separate; `outputTokens` includes `reasoningTokens`. Totals are
   cumulative for the run, not the native session. `contextTokens` is the latest request's size.
+- **Provider reasoning summaries.** For supported Responses API families, when reasoning is
+  enabled the runner requests a `detailed` summary and records only the provider's explicit summary
+  (bounded to 4,000 characters) in request-level usage. This does not change reasoning effort or
+  guarantee a provider will return a summary; raw reasoning is not used as a substitute.
 
 ## Invariants
 
 - **INV-RUN-1** A run pins one account, one variant version and one capability set when it
   starts. None of them changes during the run. A pinned account that cannot be used fails the
-  run; it is never swapped (`INV-ACC-2`).
+  run; it is never swapped (`INV-ACC-2`). A side-question run is the explicit exception for the
+  variant: it pins no variant and uses the fixed Harness instruction plus a redacted main-run
+  context projection (PROP-0019).
 - **INV-RUN-2** A run's capability set is written once (`freezeRun`). A resumed or duplicate launch
   with a different set fails with `capabilities_frozen`. A child run's set is the intersection of
-  its parent's and what it asked for; it never widens.
+  its parent's, its profile's tools and plugins, and what it asked for; it never widens.
 - **INV-RUN-3** Every run event is validated against its schema, redacted, persisted, and only then
   relayed to listeners, in order. An event that arrives after the run settled is kept as evidence
   and never applied or relayed.
@@ -103,7 +145,8 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   version and capability set, and the earlier run's record is never reopened.
 - **INV-RUN-5** Unattended runs (`automatic: true`) load no extension found on disk, read no
   context files, and never ask a person: anything that would need approval is refused. A variant's
-  own trusted plugins still load.
+  own trusted plugins still load, except for side-question runs, which have no variant or plugin
+  code and use an empty capability set (PROP-0019).
 - **INV-RUN-6** Only the harness writes `runs/<id>/`; an application reads it. `run.json`,
   `events.jsonl`, `owner.json` and `subagents.json` are written only through
   `sessions/runStore.ts`. Side files are written by their owning module: `context.json`
@@ -112,26 +155,40 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   or side file needs a proposal. (See drift D-1.)
 - **INV-RUN-7** Token accounting follows the usage contract above. Changing what a field means is
   an architecture change.
-- **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.
+- **INV-RUN-8** Plan mode keeps the stable system prompt but has mode-specific tools: an attended
+  plan may include `ask_user`, subject to the frozen caller capabilities; newly resolved normal,
+  automatic, probe, improver and reflection runs omit it. The terminal activates `ask_user` and
+  `ask_user_question` only for a plan request, then restores its normal set. Plan refusals happen
+  before approvals and no approval can lift them. Provider-cache effects of the tool-list difference
+  are not assumed (page 04, `INV-PRM-8`).
 - **INV-RUN-9** Subagent results reach the parent at native turn boundaries, at most once
   automatically (typed receipts in native history). A parent joins outstanding children before it
   completes.
 - **INV-RUN-10** An initial Bash command is allowed only on a new interactive user turn (not
   automatic, plan, resumed, continuing, relation, probe or improver runs), must match the leading `!` command
   in the text, and passes the same gate as model-issued Bash.
+- **INV-RUN-11** A side-question run is independent, tool-free and temporary. It receives only a
+  bounded, redacted projection of the main run's effective prompt and public events plus the
+  surface's visible transcript and selected references. It excludes hidden reasoning and attachment
+  bytes, never reads the main native history, and never changes or steers the parent. Its own run
+  record and events use the normal store contract (PROP-0019).
 
 ## Data
 
 `<data root>/runs/<id>/`: `run.json`, `events.jsonl`, `owner.json`, `subagents.json`,
 `context.json`, `caller.json`, `capabilities.json`, `mcp-context.json`. Native history lives in
-the session directory the caller passes (`sessionDir`), owned by Pi.
+the session directory the caller passes (`sessionDir`), owned by Pi. Side-question native history
+uses a one-use OS temporary directory, removed when the run settles; its tracked run and events
+remain in the ordinary run store.
 
 ## Source map
 
 `src/sessions/*.ts`, `src/capabilities/runSnapshot.ts`, `src/tools/spawnSubagent.ts`.
 Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (superseded),
-[ADR-0003](../decisions/ADR-0003-shared-asynchronous-subagents.md).
+[ADR-0003](../decisions/ADR-0003-shared-asynchronous-subagents.md),
+[ADR-0022](../decisions/ADR-0022-plan-only-question-tools.md),
+[ADR-0023](../decisions/ADR-0023-contextual-side-question-runs.md),
+[ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md).
 
 ## Native session names (PROP-0010)
 

package/docs/architecture/03-variants.md

@@ -26,7 +26,7 @@ The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness
 | c2 | Guardrails | `guardrails.md` | always (`guardrails`, 40) | context |
 | c3 | Memory | `memory.md` | always (`memory`, 45) | context |
 | c4 | Tool guidance | `tool_guidance.md` | always (appended to the `tools` section) | tool interface |
-| c5 | Subagents | `sub_agents/<name>/AGENT.md` | own context, listed in `subagents` (64) | orchestration |
+| c5 | Subagents | `sub_agents/<name>/AGENT.md` | own context; instruction-only agent profiles, listed with the other profiles in `subagents` (64, PROP-0029) | orchestration |
 | c6 | Skills | `skills/<name>/SKILL.md` (+ `scripts/`) | on demand, loaded by Pi as skills | context |
 | c7 | Scripts | `scripts/<name>.py` or `.mjs` | on demand, listed in `scripts` (66) | tool interface |
 | c8 | Plugins | `plugins/<name>.ts` | inside the tool loop, as Pi extensions | middleware |
@@ -68,7 +68,8 @@ The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness
 - **INV-VAR-3** A version is never edited. A change is a new version; `restore` moves the head
   and appends to `restores.jsonl`.
 - **INV-VAR-4** A run resolves its variant once and pins it; a child run or later turn uses the same
-  files even if the head moves.
+  files even if the head moves. A child whose agent profile names another variant resolves and
+  pins that one when it starts (PROP-0029).
 - **INV-VAR-5** c8 plugin code loads only when its exact text is trusted (SHA-256 in
   `variant-plugin-trust.json`). A changed file asks again. The one exception: a refinement probe may
   run improver-written code for a scope whose person allowed it (`probeCode`), and adopting that
@@ -93,3 +94,10 @@ The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness
 ## Source map
 
 `src/variant/*.ts` (`migrate.ts` renames state written before PROP-0009 on `open`). Method origin: Harness² (`harness2/core/tree.py`, Apache-2.0).
+
+## Terminal inspection
+
+The resource browser retains the materialised preparation snapshot and labels it pinned. The
+current scope head is separately labelled latest saved; browsing and comparison never rematerialise
+the head as the running variant. Directory-backed variants remain browse-only. Library additions
+use the existing validated commit door and affect future terminals.

package/docs/architecture/04-prompt.md

@@ -12,7 +12,7 @@ keeps provider caching effective across turns.
 
 | Type / function | Role |
 |---|---|
-| `compile(env, caller, launch, variant)` → `ContextPack` | Builds the ordered, budgeted sections. |
+| `compile(env, caller, launch, variant)` → `ContextPack` | Builds the ordered, budgeted sections, including the configured data-root path in native file guidance. |
 | `render(env, pack)` → `string` | One string for a session that takes a single prompt. |
 | `sessionLaunch(env, caller, launch, historyFile, variant)` → `{ system, update, pack }` | SDK sessions: stable prefix plus an update with only the dynamic sections that changed since the last delivered snapshot. |
 | `deliveredSnapshot(sessionFile)` | Reads the last delivered snapshot on the active history branch; a compaction forces a fresh one. |
@@ -26,9 +26,17 @@ All in `prompt/compile.ts`. A `ContextPack` holds `sections: Section[]` (each wi
 
 ## Section order
 
-`SECTION_ORDER`: `system` 25, `guardrails` 40, `memory` 45, `references` 50, `subagents` 64,
-`scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections sit among them by their `order`; plan
-mode uses `plan` at 25. Ties keep insertion order.
+`SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `guardrails` 40, `memory` 45, `references`
+50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
+sit among them by their `order`; plan mode uses `plan` at 25. Ties keep insertion order.
+When a run may spawn, `subagents` lists every agent profile it can start (built-in, global,
+project and the variant's c5 names) and replaces the variant's own list (PROP-0029). The `tools`
+section has a Progress paragraph whenever `checklist_write` is available: it asks for a checklist
+early and kept current, because the person follows work from it (PROP-0006).
+
+The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
+`env.productName` (default `Xingular Agent`). Host-provided identity and role sections remain
+separate, so an embedding application can still describe its agent and task.
 
 Budgets (characters): variant sections 30,000 each (already capped at save, so never cut here);
 references 12,000; Wiki pointer 2,500; tools 8,000; reporting 2,000; application sections their
@@ -65,6 +73,12 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
   message details (`xingularContext`); recording a pack does not mark it delivered.
 - Terminal sessions use `compile` + `render` once, pass it as `--append-system-prompt`, and keep
   that pack for the life of the session.
+- Read-only native file guidance states that absolute and `~` paths work when the operating system
+  permits access, names the configured data root, and describes the working folder as a default
+  location. Edits and commands remain subject to the gate.
+- A side-question launch attributes its fixed no-tool instruction to the `side-questions` plugin.
+  Its launch suppresses tool guidance entirely. The main run's effective prompt and current context
+  update are included in the separately bounded, redacted context message (PROP-0019).
 
 ## Invariants
 
@@ -77,11 +91,17 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
 - **INV-PRM-4** An update carries only changed dynamic sections, so an unchanged turn appends
   nothing. A compaction on the active branch forces the full snapshot again.
 - **INV-PRM-5** The pack only describes tools the caller can call (the frozen capability set).
+  `ask_user` is not part of the compiler's tool-group manifest; its mode-specific availability is
+  resolved with the run's callable tools (page 02).
 - **INV-PRM-6** Each run's pack is recorded beside the run. Failing to record it never fails the
   session.
 - **INV-PRM-7** The compiler is synchronous (`INV-BND-4`).
-- **INV-PRM-8** Whether a prompt change keeps the provider's cache is measured with real requests
-  from the application, only with the account owner's permission. Tests do not stand in for it.
+- **INV-PRM-8** Whether a prompt or callable tool-list change keeps the provider's cache is measured
+  with real requests from the application, only with the account owner's permission. Tests do not
+  stand in for it.
+- **INV-PRM-9** Native file guidance describes the existing OS-permission boundary accurately:
+  absolute and `~` paths are valid for read-only file tools; the working folder is not a sandbox.
+  Side-question runs with no callable tools omit tool guidance.
 
 ## Relation to DESIGN-0001
 

package/docs/architecture/06-plugins-and-capabilities.md

@@ -17,7 +17,8 @@ callable result for one run.
 | `Plugins` (`loading`, `loaded`) | `plugins/plugins.ts` | Chooses the paths a session or terminal loads; records what each extension registered. |
 | discovery | `plugins/discover.ts` | Finds items with Pi's own resolver, which runs no extension code. |
 | attachments (`load`, `save`, `attached`, `decided`, `set`) | `plugins/attachments.ts` | The one store of what is switched on, per scope. |
-| `HARNESS_PLUGINS` | `plugins/builtin.ts` | Descriptors of the harness's own parts: `pi`, `harness`, `subagents`, `wiki`, `history`, `ask-user`, `checklist`, `connected-apps`. |
+| `BuiltinPluginRegistry`, `BuiltinPluginModule` | `plugins/builtinRegistry.ts`, `plugins/builtin.ts` | Registers built-in modules and their descriptors, world parts, server handlers and terminal command metadata. |
+| `HARNESS_PLUGINS` | `plugins/builtin.ts` | Descriptor view of the registered Harness parts and feature plugins. |
 | `FIRST_PARTY_PLUGINS` | `plugins/firstParty.ts` | `output-trim`, `budget-guard`: inline extensions shipped switched off. `lessons`: switched off; its contribution turns on reflection after a run (page 08, PROP-0008) and loads no Pi code. |
 | `Hooks` | `plugins/hooks.ts` | Runs a package's hooks file after a write. |
 | install / trust | `plugins/install.ts`, `plugins/trust.ts` | Install through Pi's package manager with scripts off; trust code by hash. |
@@ -42,7 +43,12 @@ callable result for one run.
   for everyone, and only a tool marked to run without asking.
 - **Capability set** (`CapabilitySet`): `{ version: 1, tools, connectors, contributions }`.
   `capabilities.resolve` returns the set available to a caller; `capabilities.intersect` /
-  `toolIntersection` narrows it for a child.
+  `toolIntersection` narrows it for a child. The required `ask-user` plugin remains attached, but its
+  `ask_user` tool is included only for an attended plan run or a continuation pinned with that
+  capability. Automatic or refinement-triggered continuations with it are rejected rather than
+  weakening the frozen set. The `side-questions` descriptor owns the fixed instruction for the
+  restricted side-question run; it has no tools, providers, connectors, subagents or variant code
+  (PROP-0019).
 
 ## Invariants
 
@@ -70,8 +76,17 @@ callable result for one run.
   each delivery. A working folder's package cannot bring a hook.
 - **INV-PLG-9** Unattended runs load no extension found on disk (`INV-RUN-5`). The harness's own
   parts are required and refuse to be switched off; switching something on grants no permission.
+  A side-question run also has no variant plugin code or tool guidance (PROP-0019).
+- **INV-PLG-10** Every Harness-managed built-in feature is registered by `BuiltinPluginRegistry`.
+  Its descriptor, world tools, server handlers and terminal command metadata share one owner. A
+  module's world part releases resources through the existing session and Harness lifecycle. This
+  registry does not load third-party Pi code or bypass its trust checks.
+- **INV-PLG-11** Built-in plugin categories are a documentation ownership taxonomy. They are not a
+  `PluginDescriptor` field, a public response field or a second attachment scope.
 - **INV-CAP-1** A capability set only narrows. `intersect` never adds access; a run's set is
-  frozen when it starts (`INV-RUN-2`).
+  frozen when it starts (`INV-RUN-2`). An agent profile's `plugins` list keeps only the parent's
+  contributions of those plugins (required plugins always stay) and drops the tools they own; it
+  never adds one (PROP-0029).
 - **INV-CAP-2** The capability contract is generic. It names no application task, role or UI
   concept.
 - **INV-CAP-3** A capability set says what may be called, not whether a call may run. The gate
@@ -91,3 +106,24 @@ callable result for one run.
 ## Source map
 
 `src/plugins/*.ts`, `src/capabilities/*.ts`, `src/core/changes.ts`.
+
+## Built-in ownership taxonomy (PROP-0020)
+
+These categories make ownership visible in docs and source layout. They do not change plugin
+metadata or availability:
+
+| Category | Features | Foundation boundary |
+|---|---|---|
+| Foundation | Accounts, sessions and run recording, prompt and variant validation, gate, plugin loading/trust/attachments, resource browser, server and terminal frameworks | Release-owned infrastructure and security contracts |
+| World | Web search/read tools, browser tools, page annotations | The isolated browser engine and network policy remain Foundation services |
+| Memory | Wiki, history and trajectory | Storage and run records remain Foundation-owned services |
+| Automation | Subagents, ask-user, checklist, lessons and refinement | Run lifecycle, capability narrowing and approval gate remain Foundation-owned |
+| Integrations | Connected apps/MCP and Hub | Connector credentials and plugin installation remain behind Foundation services |
+| Operations | Doctor and worktrees | Diagnostics and repository operations remain Harness-managed services |
+
+## Terminal resource inspection
+
+The unified browser joins saved plugin/contribution metadata with actual session skills and tool
+registration. A saved on/off state does not prove a resource loaded; origins and owners distinguish
+same-name resources. Protected install/remove, settings, attachment and trust actions call the
+existing services. No second discovery or enablement mechanism is introduced (PROP-0013).

package/docs/architecture/07-tools-and-gate.md

@@ -13,18 +13,28 @@ per-call gate that asks the application's policy, then standing approvals, then
 | `HarnessToolDefinition`, `RECALL_TOOLS`, `TRAJECTORY_TOOLS`, `WIKI_READ_TOOLS`, `WIKI_WRITE_TOOLS`, `SKILL_TOOLS`, `DEFAULT_TOOL_NAMES` | `tools/definitions.ts` | The harness's own tools, defined once. |
 | `dispatch` | `tools/dispatch.ts` | One entry point for every History, Wiki and skill call, from a Pi tool, the server or a terminal. |
 | `harnessTools` | `tools/harnessTools.ts` | The definitions as `ToolSpec`s for one session. |
-| `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops the run and asks a question with choices. |
-| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. |
-| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent`, `wait_subagents`. |
+| `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
+| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `checklist` telemetry call. The prompt's Progress group asks the model to keep it current because the user follows work from it. |
+| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030), `wait_subagents`. |
+| `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
 | `Approvals`, `decide`, `grant`, `approvalKey` | `sessions/approvals.ts` | Standing approvals. |
 
 Harness tools: `history_search`, `history_read`, `trajectory_search`, `trajectory_read`,
 `wiki_search`, `wiki_read`, `wiki_list`, `wiki_write` (not in the default set), `skill_load`,
-`ask_user`, `checklist_write`. Broker: `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
+`ask_user` (attended plan runs and pinned continuations only), `checklist_write`. Broker:
+`mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
+## Native file paths
+
+The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
+absolute paths, and `~` paths. The working folder is a default location, not a repository boundary;
+the operating system's access for the Harness process decides what can be read. The compiled file
+guidance names the configured data root. `edit`, `write` and `bash` continue through the existing
+gate and policy. A side-question run has an empty capability set and no tools (PROP-0019).
+
 ## The gate, per call
 
 ```text
@@ -56,12 +66,17 @@ the switch and global tools.
   authorize, then standing approvals, then the person, then authorize again.
 - **INV-GATE-4** Refinement runs (`probe`, `improver`) never ask a person; what would need one is
   refused, never queued (`INV-REF-4`).
-- **INV-GATE-5** A tool is registered only if its name is in the run's frozen capability set, in
-  that order (`INV-CAP-1`).
+- **INV-GATE-5** SDK tools are registered only if their names are in the run's frozen capability
+  set (`INV-CAP-1`). The terminal may retain question-tool definitions in its private Pi inventory,
+  but normal mode deactivates them; a plan request activates only registered questions under its
+  plan-mode gate.
 - **INV-GATE-6** Tool attachment bytes never enter the run-event stream; only references are
   recorded.
 - **INV-GATE-7** Tool descriptions name the product with `{product}` (filled by `describeTool`),
   never an application's name (`INV-BND-2`).
+- **INV-GATE-8** Native read-only file access is bounded by process and operating-system
+  permissions, not by the repository root. Absolute and `~` paths are valid inputs. This does not
+  change the gate or permissions for writes and commands.
 
 ## Data
 

package/docs/architecture/09-accounts-and-connectors.md

@@ -88,3 +88,11 @@ labels this local readiness. A selected live model probe sends one synthetic req
 at 64 tokens, and records usage through the normal run writer. It never substitutes an account.
 MCP live diagnostics connect and list tools on the selected scoped connector, without calling
 connector tools or starting sign-in. Disposable grants and clients are closed afterwards.
+
+## Terminal connection setup
+
+The unified browser exposes existing connection save/test/sign-in/sign-out/remove services through
+private terminal controls (PROP-0013). New definitions are saved disabled. Saving does not connect,
+sign in or approve tools. Secrets use masked fields and the existing secret store; snapshots omit
+saved credential values and scrub connection errors/tool metadata. Hub documents remain inert until
+a person explicitly chooses setup and completes the normal validated connection form.