@xingular/harness 1.0.0 → 1.2.0

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

@@ -13,10 +13,12 @@ records everything the run does as validated events.
 |---|---|---|
 | `Sessions` | `sessions/sessions.ts` | Starts a turn: `run(input: SessionRunInput)`, `provide(provider)`. Builds the gate. |
 | `runTurn`, `piSessionFactory`, `loadResources` | `sessions/runner.ts` | Opens the Pi session, loads resources in a fixed order, streams events, settles the run. |
+| compaction checkpoint | `sessions/compactionCheckpoint.ts` | Restores the active request's bounded goal, checklist and plan instructions to model context after compaction. |
 | `RunRegistry`, `ActiveRun` | `sessions/registry.ts` | Live runs: `emit`, `requestApproval`, `requestAnswer(s)`, `onInterrupt`, `onSteer`, `finish`; `listen` for observers. |
 | 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. |
@@ -26,15 +28,18 @@ records everything the run does as validated events.
 
 1. Validate the input (`run.id`, `sessionId`, `text`; an `initialBashCommand` only on a new
    interactive user turn).
-2. Select the native history (`selectHistory`) and resolve the account (`accounts.resolve`).
+2. Resolve a continuation when requested; reuse its pinned root or derive one from its recorded
+   working directory. For a new run, resolve and pin the root from the effective `cwd` (after
+   worktree selection). Select the native history (`selectHistory`) and resolve the account
+   (`accounts.resolve`).
 3. Resolve the caller's capabilities, intersect with any narrower requested set, and **freeze**
    them for the run (`capabilities/runSnapshot.ts::freezeRun`).
 4. **Pin** the variant once (`variant/materialise.ts::materialise`).
 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 including read-only
+   `get_capabilities`, 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 +58,24 @@ 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`.
+- **Workspace root** (`RunRecord.workspaceRoot`) is the canonical root whose filesystem effects
+  native writes and default-scope Bash may modify: the nearest Git repository or worktree above its
+  effective working directory, otherwise that canonical directory. New runs pin it; continuations
+  reuse it. Older records may omit it, in which case a continuation derives it from the recorded
+  `workingDirectory`. The filesystem root itself cannot be selected as a workspace, because it
+  would collapse the write boundary. Native writes revalidate the target and atomically replace it
+  inside an OS write scope; Bash scans for external hard-link aliases and runs in the same pinned
+  boundary (page 07).
+- **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 +84,49 @@ 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` and `spawn_subagent` / `wait_subagents`, subject to the caller's frozen
+  capabilities. Delegation is limited to named profiles whose effective tool and plugin allowlists
+  qualify for read-only research; the child inherits plan mode and cannot write, run commands, ask
+  the user, use connectors or spawn children. The gate refuses unsafe calls before approvals and the
+  subagent service rechecks profile eligibility before launch. Other calls must be in
+  `PLAN_READ_ONLY_TOOLS` (including `get_capabilities` when frozen for the run), be provider tools
+  marked `readOnly`, or be explicitly classified by `planModeSafe`. Model-issued `bash` is allowed
+  and runs in the sandbox's read-only scope: no writes except a discarded temp folder, no network,
+  nothing that widens the scope; the gate refuses `outside` requests and `PLAN_BASH_DENIED` commands
+  (PROP-0043). The dynamic plan instruction
+  requires an opening `Goal` or `Summary`, evidence-grounded findings when useful, and task-scaled
+  steps and verification. A small fix stays concise without omitting its
+  outcome or check; cross-cutting work uses ordered steps. It uses alternatives only when requested
+  or materially useful; contextual `uiSketch` questions clarify real choices.
+  The reply ends with one `<proposed_plan>` block.
+- **Compaction checkpoint** (PROP-0033, ADR-0032). After compaction, an active run's model context
+  receives a bounded, ephemeral checkpoint with the current user request and the latest validated
+  checklist or applicable plan instructions, when either is available to restore. It is re-added to
+  each request while that run continues;
+  its state is cleared when the run settles or the session branch changes. The message changes no
+  tools, permissions, run events or native history. An interrupted run still uses the durable
+  checklist and normal continuation path.
 - **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,33 +135,84 @@ 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.
+  The derived usage ledger (`usage_requests`, page 08) copies these requests for
+  `/usage:analysis`; run events remain the only source of truth.
+- **Limit snapshots** (`account.status.limits`). A provider reading carries a window or balance,
+  its reset, and its source. It is produced by the usage limits service from provider response
+  headers or a documented provider endpoint (page 09), stored in the account's state, and never
+  inferred from a made-up cap.
+- **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.
+
+## Session controls and command runs (PROP-0040)
+
+`commands/registry.ts` is the browser-safe core command catalogue, shared by front ends.
+`commands.list` combines it with effective plugin, extension, prompt and skill routes (page 10).
+A listed route is not proof that its surface passes acceptance.
+
+`sessions/control.ts` owns saved-history operations: tree, navigation without a summary, fork,
+clone, rename, last reply and JSONL export. A `SessionRef` names `sessionDir`, optional
+`sessionFile` and optional `cwd`; the resolved JSONL must be inside that directory. Navigation
+records a `xingular-navigation` entry; choosing a user message returns its text for editing and
+moves before it. Fork and clone create history in an absolute `targetDir`.
+
+`SessionRunInput.command` (also `TurnParams.command`) is one of:
+
+- `{ name: 'compact', instructions? }`
+- `{ name: 'navigate', entryId, summarize: boolean, instructions? }`
+- `{ name: 'export', path }` (absolute `.html` path)
+
+It replaces prompt submission and skips the normal context update. It requires saved history and
+cannot combine with plan mode, continuation, automatic execution, initial Bash or images. It uses
+normal account/variant/capability pins, events and cancellation. Front ends must fence history
+mutations against active work; the current raw saved-history helpers do not themselves establish
+that fence. Stable native entry IDs must connect host transcript projection to navigation/fork,
+not positional message counts. A host can route `/history` to Harness `sessions.navigate` and
+navigate the same saved session; it must not substitute a fork. Shared session catalog registration
+is approved but remains in progress; no completed cross-surface catalog is implied (PAR-008).
 
 ## 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`).
+- **INV-RUN-1** A run pins one account, one variant version, one capability set and one canonical
+  `workspaceRoot` when it starts. None changes during the run. A continuation reuses the prior
+  root, deriving one from `workingDirectory` only for a legacy record without the field. A pinned
+  account that cannot be used fails the 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.
 - **INV-RUN-4** A restarted harness never restarts model work. On `open`, runs left active are
   marked `interrupted` unless another live process owns them (`owner.json`). Recovery of a
   subagent needs the same account, caller, working folder and history branch. Continuing is always
-  a new run the application asks for with `continueFrom`; it pins the earlier run's account, variant
-  version and capability set, and the earlier run's record is never reopened.
+  a new run with `continueFrom`; it pins the earlier run's account, variant version and capability
+  set, and the earlier run's record is never reopened. The application asks for it, or the earlier
+  run's work-slice policy does when the reply stopped at its budget (PROP-0041); a run started
+  without a person (`automatic`), a plan, a subagent, a session command or a worktree never
+  continues itself.
 - **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 +221,76 @@ 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`, `spawn_subagent` and `wait_subagents`, subject to the frozen caller
+  capabilities; newly resolved normal, automatic, probe, improver and reflection runs omit
+  `ask_user`. Plan-mode spawning requires a named profile whose effective explicit tool and plugin
+  allowlists qualify for read-only research. The child inherits plan mode and is narrowed to the
+  intersection of the parent's frozen capabilities, the profile and the plan research set; it has no
+  connectors, user questions, writes, commands or nested subagents. The plan run itself may run
+  Bash only in the OS-enforced read-only scope (PROP-0043, ADR-0038). The gate refuses unsafe calls
+  before approvals, and the service rechecks before launch. The terminal activates plan-eligible
+  tools only for a plan request, then restores its normal set. 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.
+  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. It is workspace-scoped by
+  default; the explicit terminal syntax `!outside <command>` requests the same human-only,
+  pre-execution outside-scope approval as the Bash tool and runs the command at most once.
+- **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).
+- **INV-RUN-13** A reply is a bounded work slice (PROP-0041). The foundation defaults are 160 tool
+  calls, 40 minutes and 320 000 new tokens, whichever comes first. The token count covers new input,
+  cache writes and output, never the cached prefix: a few large reads pass any small cap before
+  useful work, so the cap is a safety net, not the bound. At the limit the guard ends the slice and
+  refuses the next tool call with a request for `checkpoint_write`; a handoff call is never refused,
+  including when it is the first call past the limit, and another tool ends the reply. A reply that ends this way is `interrupted` with terminal reason `slice_complete`, and one
+  the stall guard ends is `stalled`. The stall guard identifies a call by its name and every
+  argument, names a repeated call once and ends the reply on the next repeat, and counts afresh in
+  each reply, so a checklist a reply rewrites as its steps complete is not a repeat. A new run
+  continues it only up to the policy's slice cap, only
+  after a slice that changed a file, passed a check or recorded a finished item, and never after a
+  checkpoint that is `blocked`. A run may turn the guard off with `workSlice.enabled: false`, and a
+  launch may set `XINGULAR_WORK_SLICE=off` for every run in that process; with it off a reply has no
+  boundary — no checkpoint, no continuation, no stall notes — and ends only when the model stops or a
+  person interrupts.
+- **INV-RUN-14** A run event stream carries `checkpoint` (the handoff `checkpoint_write` records or
+  the harness derives from the run's own evidence when the model wrote none) and `heartbeat`
+  (steps, elapsed time, last tool, compactions, slice, and the call budget). A heartbeat older than
+  five minutes while the owner process lives marks the run `interrupted` with reason `stalled`; a
+  run that never emitted one keeps the 30-minute silence rule. The watchdog never restarts work.
+- **INV-RUN-12** A post-compaction checkpoint is a bounded context projection of the active request,
+  the latest validated checklist and applicable plan instructions. It is compiled by
+  `prompt/compile.ts`, supplied only to model requests in the active run, and never persists hidden
+  reasoning or changes permissions, stable prompt text, native history or run-event schemas. Its
+  in-memory state is cleared when the run settles or the active session branch changes
+  (PROP-0033, ADR-0032).
 
 ## 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.
+`<data root>/runs/<id>/`: `run.json` (including the optional, legacy-compatible `workspaceRoot`),
+`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. 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`.
+`src/sessions/*.ts`, `src/capabilities/runSnapshot.ts`, `src/core/workspaceBashTool.ts`,
+`src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.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),
+[ADR-0033](../decisions/ADR-0033-plan-mode-research-delegation.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,23 +12,41 @@ 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. |
+| `renderCompactionCheckpoint` | Compiles a bounded current-request, checklist and plan-state message for post-compaction model requests. |
 | `saveForSession`, `copyToRun` | Terminal sessions keep the pack they started with and copy it to each run. |
 | `record`, `load`, `packPath` | The pack each run was given, at `runs/<id>/context.json`. |
 | `toolGroups`, `fit`, `clip` | The tool manifest by group; cutting text to a budget at a paragraph boundary. |
 
-All in `prompt/compile.ts`. A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
+Assembly is in `prompt/compile.ts`; shared standard-section data is in `prompt/standard.ts`.
+A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
 `body`, `sources`, `budget`, `size`, `cut`), `toolGroups`, `harness` (scope and fingerprint),
 `profile`, `compiledAt` and `delivery` (`systemSectionIds`, `updatedSectionIds`).
 
 ## 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, the dynamic `subagents` section lists every profile it can start (built-in,
+global, project and variant c5 names) and replaces the variant's own list (PROP-0029). Normal-mode
+guidance in that section explains when delegation is worth its overhead, profile selection,
+self-contained briefs, independent parallel work, and parent ownership of integration. Plan mode
+lists only effective profiles eligible for read-only research and requires a named profile; keeping
+this section dynamic leaves the stable system prompt unchanged across modes. The `tools`
+section has a Progress paragraph whenever `checklist_write` is available: it asks for a checklist
+early and kept current, then requests a final update before the reply. Only fully completed work is
+marked completed; unfinished or blocked steps remain accurate (PROP-0006).
+
+The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
+`env.productName` (default `Xingular Agent`). `Launch.standard: { cwd, project?: { name } | null }` requests shared role and working-folder
+sections from `prompt/standard.ts`; the compiler supplies common connections, file and annotation
+guidance for the effective tools. Terminal preparation defaults to standard sections (explicit
+`standard: null` opts out); the host interactive path requests the same sections. Hosts may add
+attributed add-on and task context, not a duplicate standard role or connection policy (PROP-0040).
 
 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
@@ -61,10 +79,33 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
   `dynamic: true`.
 - An update lists only the dynamic sections that changed, and announces a withdrawn one.
   `references` is always resent when present, because it belongs to the current request.
+- After successful compaction, the foundation checkpoint extension detects the compacted context and
+  uses `renderCompactionCheckpoint` to append one hidden, ephemeral context message to each model
+  request while the active run continues, when a checklist or applicable plan instructions exist.
+  It contains only the current request and available state. It is not written to native history, and its state is
+  discarded when the run settles or the branch changes.
 - The session appends the update as a hidden custom message and saves its snapshot in the
   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.
+- Native file guidance states that absolute and `~` paths work for reads when the operating
+  system permits access, names the configured data root, and describes the working folder as a
+  default location. Native writes and Bash filesystem effects default to the run's pinned project
+  or worktree root; outside file targets require one-call approval, and Bash is sandboxed unless
+  the eligible user explicitly enables Full Permission. 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).
+
+## Launch parity status (2026-11-19)
+
+Shared section generation is present in source; `surfaceParity.test.ts` checks compiler equality.
+That does not verify actual prepared launches, registered schemas, credentials, variant pins or
+provider-cache reuse. PROP-0040 also requires one Harness-owned interactive default for roots,
+variant scope and credential backend. Adoption and runtime acceptance remain in progress; explicit
+roots/scopes and continuation pins take precedence. Matching `--data` alone cannot reconcile a
+file SecretStore with a host Keychain. See [parity](../parity.md).
 
 ## Invariants
 
@@ -77,11 +118,28 @@ 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 boundary accurately: absolute and `~` paths
+  are valid for read-only file tools, which remain bounded by OS permissions rather than the
+  workspace root. Native file writes and Bash filesystem effects are workspace-scoped by default;
+  the working folder itself is not the boundary. Side-question runs with no callable tools omit
+  tool guidance.
+- **INV-PRM-10** Compaction checkpoints are assembled by this compiler, bounded, and delivered only
+  as ephemeral context while their active run continues. They do not change the stable system prompt
+  or native history, and do not carry hidden reasoning (PROP-0033, ADR-0032). A work-slice handoff is
+  the same kind of bounded projection: the `checkpoint` event is rendered into the continuation
+  section by `continuationBody`, never into the system prompt (PROP-0041).
+- **INV-PRM-11** The Progress group names `checkpoint_write` when it is in the frozen capability
+  set, with the same budget as the other tool guidance, and says only that a bounded reply records a
+  handoff when its budget is reached. It does not describe the limits themselves, which the guard
+  states at the boundary.
 
 ## Relation to DESIGN-0001