@xingular/harness 1.1.1 → 1.2.0

package/docs/architecture/proposals/PROP-0042-usage-and-provider-limits.md

@@ -0,0 +1,127 @@
+---
+id: PROP-0042
+title: Usage analytics and provider limits as a built-in capability
+status: Accepted
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-MEM-5, INV-MEM-6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 08-memory-and-history.md, 09-accounts-and-connectors.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity.md]
+---
+
+# PROP-0042: Usage analytics and provider limits as a built-in capability
+
+## Problem
+
+A run already records what each model request used: `usage.updated` carries per-request tokens,
+cost, provider, model, TTFT and duration (`src/sessions/contracts.ts`, emitted in
+`src/sessions/runner.ts`). Nothing aggregates it, and the SQLite `runs` table stores only ids,
+status and timestamps (`src/sessions/runIndex.ts`). A person cannot answer "what did this account
+spend this week, on which model?" without reading run folders.
+
+The account store already has the shape of provider limits — `Limit`, `AccountState.limits`, and
+health derived from `usedPercent`/`resetsAt` (`src/accounts/store.ts`) — and `account.status`
+carries a `limits` array (`src/sessions/contracts.ts`). No producer ever fills it: `Probe.limits`
+is never assigned in `Accounts.probe`, and `runner.ts` only classifies provider error text. A
+person cannot see how close a subscription plan, credit balance or rate window is.
+
+The capability is something a person uses, so it belongs in the Harness with a terminal surface
+before any host screen (`INV-PAR-1`).
+
+## Affected rules
+
+- **INV-MEM-5** Files are the source of truth. `index.sqlite` is derived and can be deleted and
+  rebuilt. The usage ledger is derived data inside that index; it adds no run file.
+- **INV-MEM-6** Index migrations are append-only. Migration 8 appends the usage tables.
+- **INV-STO-2** `index.sqlite` can be deleted and rebuilt; the ledger is rebuilt from run events.
+- **INV-SRV-1** A new `usage` method group is additive. Existing method names, params and result
+  shapes do not change.
+- **INV-PLG-10** The methods and commands are contributed by one built-in feature module, so the
+  public method table remains assembled by `server/methods.ts` and the plugin has one owner.
+- **INV-ACC-3** The harness never writes a secret to its own files. Provider limit reads use the
+  credential Pi already resolved through `Models.getAuth`, send it only to the provider, and store
+  no credential. A refreshed OAuth token is written only through the existing credential store.
+- **INV-RUN-7** The meaning of every usage field is unchanged. The ledger copies them; aggregates
+  are new derived data.
+
+## Proposal
+
+A built-in plugin `usage` owns a **read-only** capability with one full-screen terminal page and
+two commands:
+
+- `/usage:` and `/usage:analysis [today|7d|30d|all]` — token, cost and latency analytics from a
+  derived ledger.
+- `/usage:limit` — what each provider last reported about its plan windows, balances or rate
+  limits.
+
+**Ledger.** Migration 8 adds `usage_requests` (one row per model request) and `usage_indexed` to
+`index.sqlite`. A run's ledger rows are written from its `usage.updated` events when the run ends,
+and repaired by `open`, `rebuildIndex()` and the first analysis call when the ledger is empty. A
+per-request row is used when the event carries `request`; a provider that reported only cumulative
+totals contributes one row from its latest event. Cost uses the provider's own figure; a request
+with no cost may be priced at Pi's catalogue rates for display, and the estimate is marked
+separately, never presented as a provider figure. Aggregates are bounded: one scope, one period,
+top ten rows per breakdown, at most 400 days, with an unpriced-request count.
+
+**Limits.** Three sources, in this order:
+
+1. **Response headers**, captured by wrapping each account runtime's provider streams with
+   `onResponse`; a terminal session's runtime forwards only the limit-bearing headers over its
+   control-key-protected socket. Four families are understood: `anthropic-ratelimit-*`, Anthropic unified plan
+   windows, `x-codex-*` plan windows, and the common `x-ratelimit-*` headers. `Retry-After` on a
+   429 is kept as a reset hint. Raw headers are never stored.
+2. **The provider's own usage endpoint**, read with `Models.getAuth` and a bounded HTTPS GET that
+   refuses redirects and other hosts: OpenRouter `GET /api/v1/key`, DeepSeek
+   `GET /user/balance`, Anthropic's organization `rate_limits` (admin credential only; configured
+   limits, not usage), ChatGPT/Codex `GET /backend-api/wham/usage` (account id from the access
+   token), and OpenCode Go `GET /zen/go/v1/usage`.
+3. **Unavailable**, with a reason. No percentage is ever invented. A provider with no documented
+   endpoint, a custom base URL, an expired sign-in or no support shows local usage only.
+
+Undocumented plan endpoints stay behind the plugin setting `experimentalProbes` (off by
+default). A reading is cached per account and provider for `refreshMinutes` (default 10); a
+page open or `r` refreshes only what is due. Readings live in the account's existing state
+(`limits`, plus a new `providerLimits` readout list) and never create a new file.
+
+**Surfaces.** Public methods `usage.summary`, `usage.limits`, `usage.sync`; protected terminal
+routes `terminal.usage.summary` and `terminal.usage.limits` for the page, all through the same
+service. The App screen is a later host task, tracked as `PAR-016`.
+
+## Alternatives
+
+- **Read every run's `events.jsonl` on demand.** Correct but unbounded: a year of runs is many
+  megabytes per page open. A derived table is what the index is for.
+- **Store analytics in a new data folder.** Violates `INV-STO-3` and duplicates derived data the
+  index can rebuild.
+- **Scrape provider dashboards.** Not stable, not authenticated, and not a provider API.
+- **Show a percentage for every provider by assuming a cap.** Fabrication; rejected.
+- **Make limit reads automatic in the background.** Surprise egress with a person's credential;
+  rejected in favour of page-open and explicit refresh.
+- **Do nothing.** Leaves usage and limits unanswerable in both surfaces.
+
+## Consequences
+
+- Two additive method routes and two terminal commands; no protocol version change.
+- `index.sqlite` gains two tables (migration 8), rebuilt from run files.
+- `AccountState` gains an optional `providerLimits` readout list and `Limit` gains optional
+  absolute fields and `remainingPercent`; old state files load with defaults, and old readers
+  ignore the additions.
+- A page open may make one small read-only request per due provider, using the account's existing
+  credential. No model request, no token spend, no secret written.
+- The harness remains the only writer of the ledger and of limit snapshots.
+
+## Migration
+
+No data rewrite. The index migrates in one transaction with the existing backup/restore path; an
+old index simply indexes existing runs on the next `open` or `usage.sync`. Account state files
+without `providerLimits` read as an empty list. Reverting removes the plugin module and commands;
+the extra index tables are inert.
+
+## Checks
+
+- `npm run typecheck`, `npm test` (`src/usage/*.test.ts`, `src/plugins/usage.test.ts`).
+- `npm run prove` with an injected reader: `usage.summary` after a fake recorded run and
+  `usage.limits` returning an explicit unavailable reason, with no network.
+- Terminal verification of `/usage:`, `/usage:analysis`, `/usage:limit` and the two tabs.
+- App checks (`npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`,
+  `cargo test`) after the Harness change.
+- Real provider header names are confirmed only by a separate owner-authorized request per
+  provider; fixtures keep only redacted header values.

package/docs/architecture/proposals/PROP-0043-read-only-plan-bash.md

@@ -0,0 +1,74 @@
+---
+id: PROP-0043
+title: Read-only Bash in plan mode, enforced by the OS sandbox
+status: Accepted; implemented
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-RUN-8, INV-GATE-3, INV-GATE-8, 02-sessions-and-runs.md, 07-tools-and-gate.md, 11-terminal.md, terminal-tui.md, parity.md, ADR-0038]
+---
+
+# PROP-0043: Read-only Bash in plan mode, enforced by the OS sandbox
+
+## Problem
+
+Plan mode refuses Bash entirely: `planRefusal` (`src/sessions/planMode.ts`) did not list `bash`,
+the terminal dropped it from the plan's active set (`planModeTools`), and a test pinned the refusal.
+A plan therefore could not check its claims with read-only commands such as `git log`, `git diff`,
+`rg` or `node --version`, although the plan instructions ask for evidence-grounded findings.
+
+## Affected rules
+
+- `INV-RUN-8`: "… it has no connectors, user questions, writes, commands or nested subagents." (about
+  plan research children; unchanged) and the plan instruction "Do not change files or remote data, run
+  commands, …".
+- `INV-GATE-3` / `INV-GATE-8`: default Bash writes inside the workspace; `outside` scope and Full
+  Permission can widen it.
+
+## Proposal
+
+A plan run (SDK sessions and the terminal) may call the model's `bash` tool. Every such call runs in
+a new **read-only scope** of the existing workspace sandbox (`core/workspaceSandbox.ts`):
+
+- Reads are as broad as default Bash. Writes are denied everywhere except `/dev/null`, `/dev/tty`,
+  and a private temp folder made for the call; `TMPDIR` points to it and it is removed afterwards.
+- No network. No signals outside the sandbox. On macOS no mach services at all, so a command cannot
+  act through system daemons (preferences, Apple Events, Launch Services). On Linux, `bwrap` adds
+  `--unshare-net --unshare-ipc` and a tmpfs over `/run`.
+- Nothing widens the scope: the Full Permission bypass and `workspaceWriteScope: 'outside'` are never
+  consulted. The gate refuses an `outside` request before approvals. The hard-link scan is skipped,
+  because the scope permits no workspace writes.
+- A missing sandbox fails closed, as for default Bash.
+- As defence in depth, the gate also refuses a short list of system-acting commands
+  (`PLAN_BASH_DENIED`: `sudo`, `osascript`, `open`, `launchctl`, `defaults`, `kill`, `ssh`, …) in any
+  segment of the command. The OS sandbox is the boundary; the list is not.
+
+The plan instruction says read-only shell inspection is allowed, writes and network fail, and the
+model must not work around a failed write. Unchanged: plan research children still have no Bash, a
+user `!` command still exits plan mode, and `!` is still refused while a plan request runs.
+
+## Alternatives
+
+- **Do nothing.** Plans stay unable to verify claims with commands.
+- **A command allowlist without the sandbox.** Easy to get around (`find -exec`, `rg --pre`,
+  `git -c core.pager=…`, `$(…)`, aliases), and every new tool needs a review. Rejected as the
+  boundary; kept only as a small denylist.
+- **Default workspace-scoped Bash in plan mode.** Would let a plan change the workspace.
+
+## Consequences
+
+Hosts need no change; plan mode reaches the runner through `Sessions`. The terminal keeps `bash` in
+its plan active set. No protocol, stored data or prompt prefix changes: the SDK tool list is
+unchanged and the instruction is the dynamic plan section. Builds and tests that write fail in plan
+mode, which is intended.
+
+## Migration
+
+None. It can be undone by removing `bash` from the plan gate.
+
+## Checks
+
+`src/core/workspaceSandbox.test.ts` (real sandbox: reads succeed; workspace, home and link writes
+fail; the temp folder works and is removed; a local TCP connection fails; widening callbacks are
+never called; win32 fails closed), `src/sessions/planMode.test.ts`, `src/sessions/sessions.test.ts`,
+`src/terminal/piExtension.lifecycle.test.ts`, `npm run prove`, and the App's checks. The Linux `bwrap`
+path needs an Ubuntu CI run.

package/docs/architecture/proposals/README.md

@@ -59,6 +59,20 @@ proposal is `Accepted`.
 | [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
 | [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
 | [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+| [PROP-0031](PROP-0031-plugin-command-owner-namespaces.md) | Namespace plugin commands by owner | Implemented; Harness and App checks passed | INV-TUI-7, 06, 11, 14, terminal-tui.md, README.md, ADR-0021, ADR-0031 | 2026-10-25 |
+| [PROP-0032](PROP-0032-planning-quality.md) | Evidence-grounded planning with read-only research delegation | Implemented; live model pilot pending authorization | INV-RUN-8, INV-GATE-3, INV-CAP-1, 02, 06, 07, 14, parity, ADR-0033 | 2026-10-25 |
+| [PROP-0033](PROP-0033-compaction-plan-checkpoints.md) | Rehydrate bounded run checkpoints after compaction | Accepted; implemented | INV-PRM-1/4/10, INV-RUN-8/12, 02, 04, 11, 14, ADR-0032 | 2026-10-25 |
+| [PROP-0034](PROP-0034-conversation-fast-mode.md) | Conversation-scoped provider fast mode | Proposed | INV-RUN-1/3, INV-PAR-1/2, 02, 09, 10, 11, 12, 14, parity, App thread runtime settings | 2026-10-25 |
+| [PROP-0035](PROP-0035-retain-subagent-status.md) | Retain terminal subagent status until the next run | Implemented; initial PTY failure resolved; full verifier passed at three sizes (2026-11-19) | 11-terminal.md, terminal-tui.md | 2026-10-25 |
+| [PROP-0036](PROP-0036-first-class-harness-commands.md) | First-class Harness terminal commands | Implemented | INV-PLG-10, INV-TUI-7, 06, 11, 14, terminal-tui.md, parity, ADR-0034 | 2026-10-25 |
+| [PROP-0037](PROP-0037-workspace-write-boundary.md) | Default filesystem writes to the active project workspace | Implemented | INV-GATE-1/3/8, INV-RUN-1, INV-TUI-8, 02, 04, 07, 10, 11, 12, 14, parity | 2026-11-19 |
+| [PROP-0038](PROP-0038-annotate-open-shadow-roots.md) | Annotate inside open shadow roots | Implemented | 13-world-tools.md, note target, PROP-0017, PROP-0018, parity | 2026-10-25 |
+| [PROP-0039](PROP-0039-workspace-boundary-hardening.md) | Harden workspace writes against inode escapes and unverified retries | Accepted; implementation validated on macOS, Linux validation pending | INV-GATE-3/8, INV-TUI-8, 02, 07, 11, 14, parity | 2026-10-26 |
+
+| [PROP-0040](PROP-0040-one-launch-path.md) | One launch path and command contract across front ends | Accepted; implementation in progress | 01–04, 06–07, 10–14, parity | 2026-11-19 |
+| [PROP-0041](PROP-0041-bounded-work-slices.md) | Bounded work slices, a durable checkpoint, and a stall guard for long replies | Implemented; terminal card, App presentation and /slices open (PAR-004) | INV-RUN-2/3/4/12, INV-PRM-1/2/4/5/10, INV-GATE-2, INV-STO-3, INV-PAR-1/2, 02, 04, 07, 10–12, 14, parity | 2026-10-26 |
+| [PROP-0042](PROP-0042-usage-and-provider-limits.md) | Usage analytics and provider limits as a built-in capability | Accepted; implemented | INV-MEM-5/6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02, 06, 08–12, 14, parity, ADR-0037 | 2026-10-26 |
+| [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
 
 Numbers are four digits, start at `0001`, and are never reused.
 

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -34,7 +34,7 @@ Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatibl
 socket/controller bridge and its final gate. Keep the private control claim in process memory
 across native session replacement, revalidate prepared resource trust before every load, and
 scope native resume/import to the terminal's original working folder. Put unavoidable Pi
-implementation imports in one adapter checked against the pinned 1.2.0 version.
+implementation imports in one adapter checked against the pinned Pi version.
 
 Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
 commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and

package/docs/decisions/ADR-0021-required-command-namespaces.md

@@ -1,6 +1,6 @@
 # ADR-0021 — Required built-in commands use the bare namespace
 
-Status: Accepted (owner requested implementation of PROP-0021, 2026-10-24).
+Status: Superseded by [ADR-0031](ADR-0031-plugin-command-owner-namespaces.md).
 Supersedes: The command-namespace portion of [ADR-0018](ADR-0018-builtin-feature-plugins.md).
 Related: [PROP-0021](../architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md),
 [11 Terminal](../architecture/11-terminal.md),

package/docs/decisions/ADR-0031-plugin-command-owner-namespaces.md

@@ -0,0 +1,37 @@
+# ADR-0031 — Plugin commands use owner-qualified namespaces
+
+Status: Accepted (PROP-0031, 2026-10-25).
+Supersedes: The command-namespace decision in [ADR-0021](ADR-0021-required-command-namespaces.md).
+Related: [PROP-0031](../architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md).
+
+## Context
+
+The generic `/plugin:<command>` form hid command ownership for optional built-ins and Pi extensions,
+while required built-ins used a separate bare-command rule. Both forms left a global collision surface
+and made help, completion and invocation inconsistent across owners. Annotation routes also used the
+generic plugin prefix despite the plugin's annotation-focused purpose.
+
+## Decision
+
+Every plugin-owned terminal command is invoked as `/<owner-prefix>:<command>`, regardless of whether
+the owner is a required built-in, optional built-in or Pi extension. Core terminal commands remain
+unprefixed, and `/skill:<name>` remains reserved for skill invocation. Built-in plugins use stable
+prefixes; Pi packages may set `harness.commandPrefix` and otherwise derive the prefix from normalized
+package identity, while loose extensions use normalized extension names. Prefixes identify owners and
+must be unique; duplicate commands within an owner and owner-prefix collisions are rejected with
+source diagnostics.
+
+A built-in plugin module may choose a default command for its namespace root. Web annotations uses `/annotate:` for
+capture, `/annotate:annotate` as an equivalent alias, and `/annotate:notes` for saved annotations.
+For one release, the previous `/plugin:<command>` and bare required-plugin forms remain hidden
+compatibility aliases when unambiguous. They are omitted from help and completion.
+
+## Consequences
+
+The namespace rule applies uniformly to completion, help, highlighting and dispatch. Plugin packages
+may opt into a stable custom prefix with `harness.commandPrefix`. The compatibility aliases expire
+after one release and should not be used for new scripts or keybindings. This changes no server method,
+capability identifier, account data or annotation storage format.

package/docs/decisions/ADR-0032-compaction-run-checkpoints.md

@@ -0,0 +1,33 @@
+# ADR-0032 — Rehydrate bounded run checkpoints after compaction
+
+Status: Accepted (PROP-0033, 2026-10-25).
+Related: [PROP-0033](../architecture/proposals/PROP-0033-compaction-plan-checkpoints.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[04 Prompt](../architecture/04-prompt.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Pi preserves the native conversation transcript when compacting, but subsequent model requests use a
+summary and recent messages. The Harness already records the latest checklist as a run event and
+restores it when a stopped run is continued; an active run lacked equivalent rehydration after
+compaction. SDK plan instructions are dynamic context and may also be included in the summarized
+span.
+
+## Decision
+
+After compaction, each model request in the still-active run receives one bounded, ephemeral context
+message when a checklist or applicable plan instructions exist to restore. It contains the current
+request and available state. The prompt compiler assembles this content, and one Harness-owned
+extension provides the same behavior to embedded sessions and the terminal. The extension state is run-scoped and clears on
+settlement or branch navigation. The context message is not persisted to the native transcript or
+run-event stream; existing session history, checklist events and continuation records remain the
+sources of durable state. Hidden reasoning is never captured.
+
+## Consequences
+
+Post-compaction requests carry a small additional context block until the active run settles. The
+feature adds no storage, event, server method, tool, permission or stable-system-prompt change. Plan
+mode's existing gate remains authoritative. Runs without an explicit checklist or active plan state
+receive no checkpoint.

package/docs/decisions/ADR-0033-plan-mode-research-delegation.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0033
+title: Keep delegation selective and research-only in plan mode
+status: accepted
+created: 2026-10-25
+updated: 2026-10-25
+related: [PROP-0032, INV-RUN-8, INV-GATE-3, INV-CAP-1]
+---
+
+# ADR-0033 — Keep delegation selective and research-only in plan mode
+
+## Context
+
+Subagents can reduce the cost of substantial independent work, but a child starts without the
+parent's conversation and parallel edits create integration risk. Plan mode must remain read-only;
+allowing every profile would let profile overrides expand its effective tools or plugins. Ordinary
+subagent guidance also belongs in request context, not the stable system prompt.
+
+## Decision
+
+- In normal mode, recommend delegation only for substantial, bounded, independent work. Prefer a
+  fitting specialist, give each child a self-contained brief, parallelize only independent tasks,
+  and keep integration and verification with the parent. Simple lookups, tiny edits and tightly
+  coupled work stay with the parent.
+- In plan mode, allow only a named profile whose resolved tool and plugin allowlists are explicit
+  and confined to read-only research. The tool gate checks each spawn's arguments before approvals;
+  the subagent service checks again before launch.
+- A research child inherits plan mode and can use only the intersection of its profile, the parent's
+  frozen capabilities and the plan research set. It has no connectors, user questions, writes,
+  commands or nested subagents. Its evidence returns to the parent, which verifies and synthesizes it.
+- Put normal delegation guidance in the generated Subagents prompt section and the spawn tool's
+  description. Keep plan instructions request-scoped. Do not expand the stable system prompt or add
+  a second capability, approval, storage or plan-file mechanism.
+
+## Consequences
+
+Normal runs receive concise advice at the point where profile choices are listed. Plan runs expose
+only eligible profiles and enforce the same restriction at both the gate and launch service. The
+terminal and hosts share the Harness behavior. Plan outcomes remain in the existing run history and
+PlanCard handoff; no protocol or stored-data migration is introduced.
+
+## Verification
+
+Harness tests cover normal prompt guidance, plan-mode profile eligibility and overrides, pre-approval
+refusals, child tool/plugin narrowing, plan inheritance and non-nesting. The versioned Evaluation
+suite adds one case where research delegation helps and one small case where it should be skipped.
+Live model comparisons require explicit authorization and credentials.

package/docs/decisions/ADR-0034-first-class-harness-terminal-commands.md

@@ -0,0 +1,25 @@
+# ADR-0034 — First-class Harness terminal commands
+
+Status: Accepted (PROP-0036, 2026-10-25).
+Supersedes: The plugin-command ownership rule of ADR-0031 only for the Harness terminal commands listed below.
+Related: [PROP-0036](../architecture/proposals/PROP-0036-first-class-harness-commands.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md),
+[ADR-0031](ADR-0031-plugin-command-owner-namespaces.md).
+
+## Context
+
+The required `subagents`, `history`, `doctor` and `worktrees` feature modules currently contribute terminal commands through `BuiltinPluginRegistry`. These features are not optional plugin toggles, and their terminal pages are first-class Harness surfaces. `/history` already means session-branch navigation, while `/mcp` already opens the Connections browser as a core command.
+
+## Decision
+
+The terminal's core command registry owns these canonical routes: `/doctor`, `/worktree`, `/trajectory [run-id]`, `/subagents` and `/agents`. `/history` and `/tree` continue to navigate session branches. `/mcp` and `/connections` continue to open Connections.
+
+The underlying required feature descriptors, tools, server methods and services remain registered by `BuiltinPluginRegistry`; they no longer own the terminal command metadata for these routes. Other plugin-owned built-in and Pi extension commands remain `/<owner-prefix>:<command>`, including the annotations namespace.
+
+For one release, the prior owner-qualified and `/plugin:<command>` routes for the promoted commands remain accepted as hidden compatibility aliases. They are omitted from help and completion. Core command names remain reserved under the normal collision policy.
+
+## Consequences
+
+The core terminal command table owns help, completion, highlighting and dispatch for the promoted routes. Plugin namespace collision checks and extension command ownership are unchanged. No server method, capability contract or stored data changes.

package/docs/decisions/ADR-0035-one-launch-path.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0035
+title: One launch and command contract for every front end
+status: Accepted
+created: 2026-11-19
+proposal: PROP-0040
+---
+
+# ADR-0035: One launch and command contract for every front end
+
+## Decision
+
+The owner approved Complete App parity and Solo tabs; accepted
+[PROP-0040](../architecture/proposals/PROP-0040-one-launch-path.md) records the Harness contract.
+The foundation owns one interactive launch policy, not a policy per renderer:
+
+- `Launch.standard` supplies shared role, working-folder and connection guidance. Hosts add only
+  attributed context, policy and declared add-ons through existing extension points.
+- `commands/registry.ts` defines core commands; `commands.list` adds effective plugin commands,
+  prompts and skills. Session history controls use `sessions.*`; live-session operations use
+  `SessionRunInput.command` and the normal run lifecycle.
+- Both surfaces load Harness-selected trusted resources and first-party hooks. Pi CLI built-ins
+  and the terminal-only question alias are excluded; attended planning uses `ask_user`.
+- Interactive defaults (roots, neutral variant scope and credential backend), shared session
+  references, browser schemas and frozen capability discovery belong to Harness. Explicit choices
+  and historical pins win. Existing profiles are never silently merged or credentials copied.
+- Optional `surfaces` metadata describes a host preference and a terminal fallback or unavailability;
+  it neither creates a plugin category nor grants permission.
+
+## Consequences and alternatives
+
+Separate front-end defaults and command implementations make identical labels promise different
+behavior. A shared contract permits richer presentation without a second loader, gate or state owner.
+Host-backed tools must refuse unsupported semantics honestly. Matching roots alone does not share
+credentials when the backends differ.
+
+This is an accepted design, not release or acceptance evidence. Shared-default adoption, actual
+runtime pins, native browser behavior, actionable command pages and cross-surface session discovery
+remain subject to implementation and both-surface acceptance. The [parity register](../parity.md)
+tracks source status and gaps; compiler-only equality tests do not establish runtime parity.

package/docs/decisions/ADR-0036-workspace-write-operation-boundary.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0036
+title: Enforce workspace writes at the filesystem operation
+status: Accepted
+created: 2026-10-26
+proposal: PROP-0039
+---
+
+# ADR-0036: Enforce workspace writes at the filesystem operation
+
+## Decision
+
+The Harness owns one filesystem-effect boundary shared by SDK sessions and the terminal. Each run
+pins a non-root `workspaceRoot`; model-controlled native writes and default-scope Bash are confined
+to that root by operating-system enforcement, not by prompt guidance or pathname checks alone.
+
+- Native `write` and `edit` calls revalidate the authorized canonical target at mutation and use
+  atomic replacement under an OS-enforced write scope. Outside file targets need a one-call
+  approval; replacing a directory entry rather than truncating an inode prevents an outside
+  hard-link alias from being changed.
+- Before default-scope Bash, Harness scans the workspace for regular-file inodes with links outside
+  it and blocks the command if the scan is incomplete or an external alias may exist. The OS
+  sandbox prevents the command from creating a cross-boundary hard link. On macOS it denies
+  hard-link creation entirely, including within the workspace.
+- Bash outside scope is an explicit `workspaceWriteScope: 'outside'` request, or terminal
+  `!outside <command>`. The complete quoted command is shown in approval details. Approval happens
+  before execution, is human-only and nonrememberable, and runs the exact command once. An
+  undersized terminal denies the request. stdout/stderr never proves a sandbox denial and never
+  triggers approval or replay.
+- Full Permission remains the existing explicit boundary bypass for eligible interactive runs; it
+  remains subject to hard policy, authorization, read-only, plan, unattended and refinement rules.
+- The filesystem root is not a valid workspace. A same-user peer process outside Harness remains
+  outside this boundary. Atomic replacement preserves ordinary file mode where possible but does
+  not guarantee ACL or extended-attribute preservation.
+
+## Rationale
+
+Canonical path checks alone do not contain effects through hard links and are vulnerable to
+pathname changes between authorization and mutation. Atomic replacement avoids writing through a
+shared inode, while an OS scope constrains the helper if a path changes. Shell output is controlled
+by the command and cannot authenticate a denial event; explicit pre-execution scope requests avoid
+replaying partial side effects and make broad writes an intentional decision.
+
+## Consequences and alternatives
+
+Workspaces with external hard-link aliases cannot use default Bash until repaired. Unsupported or
+incomplete sandbox enforcement fails closed. Outside writes remain possible through the explicit
+one-call approval path. A private copy-on-write workspace would also isolate against same-user peer
+processes, but changes visibility, writeback, conflict handling, metadata and performance; it remains
+out of scope unless that threat must be covered.
+
+This decision is not release evidence. See [PROP-0039](../architecture/proposals/PROP-0039-workspace-boundary-hardening.md),
+[the gate contract](../architecture/07-tools-and-gate.md), [terminal parity](../architecture/11-terminal.md)
+and [the release note](../releases/1.2.0.md) for implementation and validation status.

package/docs/decisions/ADR-0037-usage-ledger-and-provider-limits.md

@@ -0,0 +1,44 @@
+# ADR-0037: Usage analytics read a derived ledger; provider limits are read, never guessed
+
+**Status:** Accepted (2026-10-26)
+
+## Context
+
+Token and cost figures already reach the harness per model request, but only inside run events,
+and the index stores no usage. Provider limits have a schema and health rules but no producer.
+A person needs both answers without reading run folders, and a subscription's plan window must
+not be presented as a made-up percentage.
+
+## Decision
+
+- **The usage ledger is derived.** `usage_requests` and `usage_indexed` live in `index.sqlite`,
+  are written from `usage.updated` events, and are rebuilt from `runs/` like recall. No run file,
+  folder or schema changes.
+- **Analytics are bounded and scope-first.** One scope, one period, top-ten breakdowns, an
+  unpriced-request count, and cost estimates marked separately from provider figures.
+- **Limits have a stated source.** Response headers first (free and fresh), then a small registry
+  of documented provider endpoints read with the credential `Models.getAuth` resolves, then an
+  explicit unavailable reason. Undocumented endpoints are off unless `experimentalProbes` is on.
+- **Freshness is a person's choice.** Readings are cached for a configurable interval and
+  refreshed on page open or `r`, never by a background timer.
+- **One built-in plugin owns the capability.** `usage` contributes the methods and the two
+  namespaced terminal commands; the public method table still comes from `server/methods.ts`.
+
+## Consequences
+
+The index carries one more derived table set, with an append-only migration. `AccountState`
+gains an optional readout list and `Limit` optional absolute fields, both additive. A page open
+may make a read-only provider request with the account's existing credential; nothing is written
+to a credential file and no model request is made. Hosts can present the same methods later; the
+terminal is the reference surface.
+
+## Alternatives rejected
+
+Reading raw run logs per page (unbounded), a new data folder (duplicates derived data), scraping
+dashboards (no stable API), inventing percentages (misleading), background polling (surprise
+egress).
+
+## References
+
+[PROP-0042](../architecture/proposals/PROP-0042-usage-and-provider-limits.md), architecture pages
+02, 06, 08, 09, 10, 11, 12 and 14.

package/docs/decisions/ADR-0038-plan-bash-os-read-only.md

@@ -0,0 +1,29 @@
+---
+id: ADR-0038
+title: Plan-mode Bash is read-only by OS sandbox, not by command parsing
+status: Accepted
+created: 2026-10-26
+proposal: PROP-0043
+---
+
+# ADR-0038: Plan-mode Bash is read-only by OS sandbox, not by command parsing
+
+## Decision
+
+Plan runs may use Bash, and each call runs in the workspace sandbox's `read-only` scope: no writes
+except a discarded per-call temp folder, no network, no signals outside the sandbox, and (macOS) no
+mach services. Nothing widens that scope in plan mode. A small denylist of system-acting commands is
+checked by the gate as defence in depth only.
+
+## Rationale
+
+Whether a shell command writes cannot be decided reliably from its text; many read-looking commands
+can run others or write through flags. The Harness already depends on `sandbox-exec` and `bwrap` for
+the workspace boundary (ADR-0036), so the same mechanism with no write roots gives a kernel-enforced
+read-only guarantee at little cost.
+
+## Consequences
+
+Plans can inspect with real commands. Commands that need to write, such as most builds and tests,
+fail in plan mode. Platforms without a sandbox refuse plan Bash. See
+[PROP-0043](../architecture/proposals/PROP-0043-read-only-plan-bash.md).