@xingular/harness 1.1.1 → 1.2.0

package/docs/architecture/08-memory-and-history.md

@@ -55,7 +55,9 @@ rebuildable SQLite index.
     lessons; nothing is evicted.
   - The `wiki` pointer section says how many lessons there are when there are any.
 - **Index.** Every finished run is indexed when it ends; `open` and `rebuildIndex()` sync from
-  `runs/`.
+  `runs/`. The same pass writes the **usage ledger**: one `usage_requests` row per model request
+  from the run's `usage.updated` events, and one `usage_indexed` marker per run (PROP-0042).
+  `/usage:analysis` queries only that ledger; it is derived and rebuilt from run events.
 
 ## Invariants
 
@@ -84,7 +86,7 @@ rebuildable SQLite index.
 <data root>/wiki/            home.md, library/, projects/<slug>/
 <data root>/wiki-history/    earlier versions of notes
 <data root>/legacy/          an earlier Wiki's memory blocks, facts, revisions, Inbox (moved once)
-<data root>/index.sqlite     derived: pages, links, runs, recall passages (FTS5)
+<data root>/index.sqlite     derived: pages, links, runs, recall passages (FTS5), usage rows
 <data root>/projects.json    read only: the application owns it
 ```
 

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

@@ -67,7 +67,7 @@ skills, prompts, rules and Pi packages.
 ## Data
 
 ```text
-<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log
+<state dir>/accounts/         registry, per-account Pi agent folders, _shared/pi/, audit log, per-account state (health, plan, limits)
 <state dir>/secrets.json      default SecretStore (owner-only)
 <state dir>/connections.json  connected apps, no secrets
 <state dir>/hub/catalog.json  catalog cache
@@ -89,6 +89,36 @@ at 64 tokens, and records usage through the normal run writer. It never substitu
 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.
 
+## Provider limits (PROP-0042)
+
+A limit reading says what a provider itself reported: a plan window, a credit balance, a rate
+limit, or a configured organization limit. Three sources are used, in order:
+
+1. **Response headers** on the account's own model requests. Each account runtime's providers are
+   wrapped so `onResponse` sees status and headers; a terminal session's own runtime forwards only
+   the limit-bearing headers to the parent over the control-key-protected session socket.
+   `usage/limits/normalize.ts` understands `anthropic-ratelimit-*`, Anthropic unified plan windows,
+   `x-codex-*` and `x-ratelimit-*`, plus `Retry-After` on a 429. Raw headers are never stored.
+2. **The provider's own usage endpoint**, read with `Models.getAuth(provider)` so OAuth refresh
+   stays in Pi's serialized credential path: OpenRouter `GET /api/v1/key`, DeepSeek
+   `GET /user/balance`, Anthropic's organization `rate_limits` for an admin API key (configured
+   limits, not usage), ChatGPT/Codex `GET https://chatgpt.com/backend-api/wham/usage`, and
+   OpenCode Go `GET https://opencode.ai/zen/go/v1/usage`. A Codex request carries the account id
+   from the access token's JWT claim; an OpenCode Go request carries the account's API key.
+   The request is a bounded HTTPS GET that refuses redirects, caps its body, and never puts a
+   credential in an error. An endpoint reading replaces every limit for that provider; a header
+   reading only merges the windows it saw.
+3. **Unavailable**, with a reason. No percentage is invented; local usage is shown instead.
+
+Undocumented endpoints require the usage plugin's `experimentalProbes` setting. Readings are
+cached for `refreshMinutes` (default 10) and refreshed on a page open or an explicit refresh, never
+by a background timer. They are stored in the account's existing state (`limits`,
+`providerLimits`), never in a new file, and no credential is written. A reading carries both `usedPercent` and the additive
+`remainingPercent`. The Limits page is a centered dialog: each window is a label and reset line
+above a quota-left bar, green at 50% or more left, amber from 20–49%, and red below 20%. It adds
+the local seven-day ledger without a label, so a provider's zero reading and this app's own use
+are not confused.
+
 ## Terminal connection setup
 
 The unified browser exposes existing connection save/test/sign-in/sign-out/remove services through

package/docs/architecture/10-server-protocol.md

@@ -33,7 +33,7 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 - `harness.methods` lists every method. Groups in the table: `accounts`, `harnesses`, `runs`,
   `connections`, `plugins`, `wiki`, `refine`, `capabilities`, `hub`, `terminal`, `approvals`,
   `harness`, `subagents`, `agents`, `sessions`, `sideQuestions`, `library`, `recall`, `context`,
-  `worktrees`, `annotations`.
+  `worktrees`, `annotations`, `commands`, `usage`.
 - Host calls (only with the matching `--host-*` flag): `secrets.get|set|delete`,
   `policy.scope|authorize|approval|connections`, `tools.call`. The host registers tools with
   `tools.register` and names with `directory.set`, and describes its parts with
@@ -41,16 +41,69 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
 - `refine.start` takes `{ task, k?, mode?, improver?, executor?, baseVersion?, retainWorkspaces?, id? }`;
   `refine.candidates` returns each execution with `workspace: string | null` (page 05, PROP-0002, PROP-0003).
 - `runs.checklist { runId }` returns the run's latest checklist, `[]` when it wrote none (PROP-0006).
+- Run records include optional nullable `workspaceRoot`, the canonical root whose files a run may
+  modify by default (page 02). New Harness runs set it; older records may omit it. Hosts must
+  tolerate the additive field and must not nominate or widen the root.
 - `agents.list { cwd? }` returns `{ profiles, problems }`; `agents.get { cwd?, name }` one profile;
   `agents.create { cwd?, name, scope: 'global' | 'project', from? }` writes the template or a copy
   and refuses an existing file; `agents.remove { cwd?, name, scope }` deletes a person's own file.
   `subagents.spawn` takes `agent` as a profile name and returns `agent` and `unavailableTools`
   (PROP-0029). It takes an optional `title` (at most six words); without one the child's title is
   the first line of its brief (PROP-0030).
-- `runs.continuation { runId, sessionDir? }` returns a `Continuation`, and `sessions.run` accepts
-  `continueFrom` (page 02, PROP-0007). `harness.status` reports `recovery.interruptedRunIds`.
+- `runs.continuation { runId, sessionDir? }` returns a `Continuation` (its `checkpoint` is the last
+  work-slice handoff), and `sessions.run` accepts `continueFrom` (page 02, PROP-0007) and `workSlice`
+  (PROP-0041). `harness.status` reports `recovery.interruptedRunIds`.
+- `workSlice { enabled?, maxToolCalls?, maxMinutes?, maxNewTokens?, maxSlices?, continue? }` on
+  `sessions.run` bounds that reply; absent uses 160 calls, 40 minutes, 320 000 new tokens, 8 slices and
+  automatic continuation. A token cap counts new input, cache writes and output, never the cached
+  prefix. `enabled: false` turns the guard off for that run; `XINGULAR_WORK_SLICE=off` in the
+  launching process turns it off for every run in it, and nothing is persisted. The policy is
+  carried into the continuation. A value outside its range is refused with `invalid_request` before
+  the run record is written.
+- The run-event stream adds `checkpoint` (the bounded handoff) and `heartbeat` (steps, elapsed time,
+  last tool, compactions, slice, call budget). Hosts must accept both; an unknown event type is still
+  relayed in order (INV-RUN-3).
 - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
 
+## Usage (PROP-0042)
+
+| Method | Input | Reply |
+|---|---|---|
+| `usage.summary` | `{ scope?: "session" \| "account" \| "project" \| "all", sessionId?, accountId?, projectId?, period?: "today" \| "7d" \| "30d" \| "all", timezoneOffsetMinutes? }` | `UsageSummary`: totals, cache hit rate, latency, day/model/provider/account/session breakdowns, unpriced count, ledger time |
+| `usage.limits` | `{ accountId?, refresh?: boolean }` | `UsageLimitsReport`: per account and provider, the reading source, reason, observed time and limits |
+| `usage.sync` | `{}` | `{ runs, indexed, lastIndexedAt }` |
+
+The methods are contributed by the built-in `usage` plugin module and read only derived or stored
+data; `refresh: true` is the only form that may contact a provider, once per due provider. The
+terminal reaches the same service through protected `terminal.usage.summary|limits`, whose scope
+comes from the terminal session, never from the request.
+
+## Commands and session controls (PROP-0040)
+
+`commands.list { cwd?, accountId?, agentId?, projectId? }` returns `ListedCommand[]`: `name`,
+optional `aliases`, `args`, `description`, `owner`, plus `group`, `source`
+(`core | plugin | extension | prompt | skill`) and optional core `kind` (`session | page | local`).
+Core metadata comes from `commands/registry.ts`; effective plugin contributions supply other routes.
+Namespace/collision rules are shared; discovery neither runs a command nor proves surface acceptance.
+
+For the methods below, `ref` means `{ sessionDir, sessionFile?, cwd? }`.
+
+| Method | Input | Reply |
+|---|---|---|
+| `sessions.tree` | `ref` | `SessionTree`: file, leaf, entries and user-message fork points |
+| `sessions.navigate` | `ref + { entryId }` | `{ leafId, editorText? }`; no summary/model request |
+| `sessions.fork` | `ref + { entryId, targetDir }` | `{ sessionFile, editorText }` |
+| `sessions.clone` | `ref + { targetDir }` | `{ sessionFile }` |
+| `sessions.rename` | `ref + { name }` | `{ name }` |
+| `sessions.lastReply` | `ref` | `{ text: string | null }` |
+| `sessions.export` | `ref + { path }` | `{ path }`; absolute `.jsonl` branch export |
+| `sessions.reload` | `{}` | `{ reloaded: true }`; reloads persistent hooks; structured turns load resources fresh |
+
+`sessions.run` also accepts `command` for compact, navigation with optional summary, or HTML
+export instead of prompt submission (page 02). These retain tracked run lifecycle and pins.
+Saved-history helpers currently validate file scope but do not themselves fence active work;
+host adapters must not infer concurrency safety from method availability.
+
 ## Invariants
 
 - **INV-SRV-1** `src/server/methods.ts` is the contract for every non-Node host. Adding a method
@@ -129,6 +182,8 @@ from preparation, never from the request.
 | `terminal.browser.connections.appClients` | `{}` | Existing available application OAuth catalog IDs |
 | `terminal.browser.connections.save` | `{ input: ConnectionInput }` | Existing safe `Connection` record |
 | `terminal.browser.connections.test\|signIn\|signOut\|remove` | `{ id }` | Existing connection service result |
+| `terminal.usage.summary\|limits` | `{ scope, period, timezoneOffsetMinutes }` / `{ refresh? }` | Existing usage service result, scoped to this terminal's account and project |
+| `terminal.usage.headers` | `{ provider, status, headers }` | `{}`; only limit-bearing headers, throttled, stored as an account limit reading |
 
 Protected `plugins.install { source }` and `plugins.remove { pluginId }` delegate to the package
 service. Optional matching callbacks extend `PluginControl`; hosts without them receive a clear

package/docs/architecture/11-terminal.md

@@ -34,32 +34,56 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   `--conditions=browser` and `dist/terminal-opentui.js`; no global `pi` is needed.
 - The `piExtension` path is the final prepared extension argument; the runtime loads it as the
   final trusted inline factory.
+- Each terminal `begin` returns the run's pinned `workspaceRoot` to that extension. Native file
+  writes use the same revalidated atomic helper and OS write scope as SDK sessions. Terminal Bash,
+  including initial `!` commands, defaults to the workspace sandbox and external-hard-link scan;
+  `!outside <command>` requests human-only approval before that exact command runs once; its full
+  escaped command is available in scrollable approval details, and an undersized terminal denies
+  the request. The eligible Full Permission switch is the only standing boundary bypass; remembered
+  per-tool grants do not widen it, and command output never triggers approval or replay.
 - The terminal compiles its prompt once (`compile` + `render`) and keeps that pack; each run
-  records a copy (page 04).
-- Normal mode keeps `ask_user` and `ask_user_question` out of the active tool set. A plan request
-  enables the registered question tools alongside its read-only set and restores the normal set on
-  success, failure or interruption. See page 02 and the [terminal guide](../terminal-tui.md).
-- Standalone defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
-  `~/.xingular-harness-dev/{data,state}`.
+  records a copy (page 04). The shared compaction checkpoint extension reintroduces the active
+  request and latest checklist into post-compaction model context until the run settles.
+- Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
+  shared tool alongside its read-only set and restores the normal set on success, failure or
+  interruption. There is no terminal-only question alias (PROP-0040).
+- A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
+  (PROP-0043). A user `!` command is refused while a plan request runs.
+- Current standalone source defaults: `~/.xingular-harness/{data,state}`; `npm run dev` uses
+  `~/.xingular-harness-dev/{data,state}`. The standalone development launch uses a file SecretStore
+  under its resolved development state directory, even when its profile names a host backend; it
+  does not use or alter host credentials. `--variant <scope>` explicitly selects a variant head.
+  PROP-0040 approves a shared Harness-owned interactive profile, neutral default scope and
+  credential backend; adoption and runtime verification remain in progress. Until that lands,
+  matching roots/scopes is explicit and matching roots alone does not share host Keychain secrets.
+- `Launch.standard` supplies the shared role and folder text. History, Wiki and skill model tools
+  use the session socket; enabled output-trim/budget-guard hooks load through `firstParty.list`.
+  Pi CLI built-ins (llama.cpp, codemode, tool-search and MCP) are not loaded as a terminal-only
+  resource path. Harness MCP remains available.
 - An empty conversation shows a centered welcome using `env.productName` (default `Xingular Agent`):
   the first letter of a multiword name is the orange block mark and its remaining words are letter-spaced
   in blue. The welcome adds a greeting, tagline and `/help` hint without replacing the composer or
   status bar. Explicit host product names use the same generic formatting.
 - `xagent --worktree [name]` (`-w`) starts in a new managed worktree of the current repository,
   or in the named one, and prunes older managed worktrees (PROP-0016). A session that names a
-  worktree holds it for its whole life. `/worktree` switches folders by asking the host to restart
-  the frontend there (`TerminalRelaunch.cwd`), as a new conversation: Pi keeps one history per
-  working folder.
-- Slash-command aliases share one registry entry: `/session (resume)` switches saved sessions,
-  `/history (tree)` navigates branches in the current session, and `/btw (side)` asks a side
+  worktree holds it for its whole life. `/worktree` opens the worktree page; selecting
+  one switches folders by asking the host to restart the frontend there (`TerminalRelaunch.cwd`),
+  as a new conversation: Pi keeps one history per working folder.
+- Slash-command aliases share one registry entry: `/session (resume)` opens the full-screen, searchable
+  saved-session page with unnumbered title and metadata rows; `/history (tree)` navigates branches in
+  the current session, and `/btw (side)` asks a side
   question through the Harness `SideQuestions` service. It uses the same account/model/effort,
   mirrors the main run's redacted prompt and public evidence, starts a separate tool-free run, and
   leaves the main conversation untouched. The dock streams, scrolls and copies the complete answer.
   Aliases remain callable and searchable, but help and palette show only the canonical
-  entry. Commands owned by required built-in plugins and core terminal commands are unprefixed.
-  Optional built-in plugin and Pi extension commands use `/plugin:<command>`. A bare command or
-  prompt owns its name; a colliding `/plugin:<command>` is omitted and rejected with a hint to use
-  the bare command. Prompt templates and `/skill:<name>` otherwise keep their existing forms.
+  entry. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
+  opens its Limits tab (PROP-0042); both are plugin-owned namespaced routes. The usage page is a
+  centered dialog: each window is a label and reset line above a quota-left bar coloured green at
+  50% or more left, amber from 20–49%, and red below 20%. `commands.list`
+  publishes the effective routes; the browser-safe core catalogue is `commands/registry.ts`. First-class Harness commands are unprefixed and live in that registry,
+  independently of plugin command metadata. Every plugin-owned command uses
+  `/<owner-prefix>:<command>`; the namespace root is offered only by plugins that declare a default
+  command. Prompt templates and `/skill:<name>` keep their existing forms.
 
 ## Invariants
 
@@ -80,20 +104,37 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   revoked code needs review and a fresh terminal.
 - **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The terminal keeps a
   persistent child instead of opening a session per turn.
-- **INV-TUI-7** Required built-in plugin commands use their unprefixed names; optional built-in
-  plugin commands and Pi extension commands use `/plugin:<command>`. Completions and help show each
-  command in its canonical namespace. Bare core commands, aliases, required built-in commands and
-  loaded prompts reserve their names; a colliding prefixed command is hidden and rejected with a hint
-  to use the bare command. Duplicate extension names are rejected with owner diagnostics. Old
-  prefixed forms of required built-in commands are not aliases.
+- **INV-TUI-7** Harness core commands use unprefixed names and are registered independently of
+  feature-plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents`
+  and `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections
+  shortcut. Every plugin-owned terminal command uses `/<owner-prefix>:<command>`, for required and
+  optional built-ins and Pi extensions alike. Completions, help and dispatch use the same stable
+  owner prefix. Prefixes are unique to an owner; a prefix collision or duplicate command within an
+  owner is rejected with owner diagnostics. `/skill:<name>` remains reserved for skill invocation.
+  For one release, the former owner-qualified and `/plugin:<command>` forms of promoted Harness
+  commands remain hidden compatibility aliases; aliases are not listed in help or completion.
+- **INV-TUI-8** Terminal sessions use the Harness-pinned workspace root and the same write
+  boundary as SDK sessions. Native file mutations use revalidated atomic replacement under an OS
+  scope; default Bash scans for external hard-link aliases and runs inside the sandbox. The terminal
+  cannot widen the boundary through its socket or native extension. `!outside <command>` requests
+  human-only approval before one execution; the terminal shows the complete escaped command and
+  denies the request if it cannot display details and choices together. stdout/stderr cannot trigger
+  approval or replay. Missing enforcement fails closed. Full Permission bypasses the boundary only
+  for eligible interactive
+  user runs and does not override hard policy denials, read-only or plan mode, unattended work, or
+  refinement restrictions.
 
 ## Source map
 
 `src/terminal/**`. Decisions: ADR-0001, [ADR-0004](../decisions/ADR-0004-fullscreen-terminal-layout.md)
-(superseded), ADR-0006, [ADR-0021](../decisions/ADR-0021-required-command-namespaces.md),
+(superseded), ADR-0006, [ADR-0021](../decisions/ADR-0021-required-command-namespaces.md)
+(superseded by [ADR-0031](../decisions/ADR-0031-plugin-command-owner-namespaces.md)),
 [ADR-0024](../decisions/ADR-0024-xagent-command.md),
 [ADR-0027](../decisions/ADR-0027-connected-sketch-display.md),
-[ADR-0028](../decisions/ADR-0028-xingular-agent-product-identity.md). Experiments:
+[ADR-0028](../decisions/ADR-0028-xingular-agent-product-identity.md),
+[ADR-0031](../decisions/ADR-0031-plugin-command-owner-namespaces.md),
+[ADR-0034](../decisions/ADR-0034-first-class-harness-terminal-commands.md),
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md). Experiments:
 EXP-0001, EXP-0002 in `../experiments/`.
 
 ## Session name in the working line (PROP-0010)
@@ -166,7 +207,9 @@ Every choice uses one shared measured layout: a marker gutter, a one-third label
 gap, and the remaining description cell. Column boundaries align across all rows at every terminal
 width, including compact widths. Text wraps within its cell; a missing description keeps its cell
 and columns never stack. Recommendation text uses `(Rec.)` when the label column is fewer than 14
-cells. Below 60 terminal columns, the dock uses a compact hint.
+cells. Below 60 terminal columns, the dock uses a compact hint. Multi-select choices use `✓`
+when selected and `○` when unselected, matching checklist glyphs; single-choice options remain
+numbered.
 
 The dock body has bounded height and vertical scrolling; question tabs and answer/action controls
 stay outside that scrolling region. PageUp/PageDown scroll the body and Ctrl+Home/End jump to its
@@ -200,21 +243,20 @@ contract is unchanged. See [PROP-0025](proposals/PROP-0025-contextual-question-w
 PTY verification is retained in `docs/evidence/terminal-wireframe-normalization/`; it establishes
 cell topology for bounded fixtures, not every emulator/font or live-model sketch quality.
 
-## Page notes commands (PROP-0017)
+## Web annotations commands (PROP-0017)
 
-`/plugin:notes` lists the page notes kept in the data root, with search, and offers reveal, edit, resolve or
-reopen, share with this session or stop sharing, and delete. `/plugin:annotate [url]` starts a new note: it
-opens a visible capture browser (its own window and profile, separate from the agent's browser), and
-the person notes the whole page, selects text, or clicks an element there, then confirms in the
-terminal. A note is private until shared; this session's agent then reads it with `page_notes_list`
+`/annotate:notes` lists the Web annotations kept in the data root, with search, and offers reveal, edit, resolve or
+reopen, share with this session or stop sharing, and delete. `/annotate:` opens the default capture pane;
+`/annotate:annotate [url]` is its explicit command form. It opens a visible capture browser (its own window and profile, separate from the agent's browser), where the person can annotate the whole page,
+select text, or click an element there. An annotation is private until shared; this session's agent then reads it with `page_notes_list`
 and `page_notes_read`.
 
-`/plugin:annotate` is the annotate pane (PROP-0018): a full-screen page beside the window being inspected.
+The annotate pane (PROP-0018) is a full-screen page beside the window being inspected.
 
 - **Ways to start it:**
-  - `/plugin:annotate [url]`: the browser window
-  - `/plugin:annotate --app <DevTools address | port> [name]`: an app's own windows over its DevTools port
-  - `/plugin:annotate --bridge [name]`: app windows that load the page bridge script, which the pane shows
+  - `/annotate:` or `/annotate:annotate [url]`: the capture browser
+  - `/annotate:annotate --app <DevTools address | port> [name]`: an app's own windows over its DevTools port
+  - `/annotate:annotate --bridge [name]`: app windows that load the page bridge script, which the pane shows
 - **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in the page with Create annotation, Ask agent to fix, and Proceed now.
 - **Sections:** Queue, Sent and fixed (with the agent's summary), and Saved.
 - **Other keys:** `s` sends the queue as one run of this session, confirming notes that came from a page-world script first; `x` takes a note out of the queue; `t` picks a window.
@@ -229,25 +271,46 @@ The gate treats it as read-only, plan mode allows it, and terminal children inhe
 transcript shows each write as a checklist block (`✓` done, `●` in progress (warning yellow), `○` pending) under a
 `Checklist · n of m done` header instead of a tool row; a failed or malformed call stays a tool row.
 
+## Work-slice checkpoint (PROP-0041)
+
+Terminal replies carry the same work-slice guard as structured runs: 160 tool calls, 40 minutes or
+320 000 new tokens, then a refusal that asks for `checkpoint_write`. The extension registers the shared
+tool and sends it as `checkpoint` telemetry, which the controller records as `checkpoint` on the
+active run, so an App reading the same session sees the handoff. Terminal replies are not
+auto-continued: at the boundary the person decides, which is what the terminal's own turn model
+already does. The run record says `interrupted` with terminal reason `slice_complete` (or `stalled`
+when the guard ended it), so a host can continue it; a checkpoint card in the transcript is not built
+yet (PAR-004). Start the terminal with `XINGULAR_WORK_SLICE=off` to launch a reply with no
+boundary at all; it is not persisted, so the next launch without it restores the guard.
+
 ## Subagent activity monitor
 
 During an active parent run, the terminal polls a private read-only monitor once per second. It
 projects the flat set of child and nested-child runs with task, status, elapsed time, the latest
 tool name, the child's agent profile (name and colour, PROP-0029), the title the parent gave it
-(PROP-0030), and counts from the child's own checklist. The child's own `session_name` is not
-projected; it names the child's session, not its row. Tool summaries, other
-arguments, output and checklist item text never enter the monitor. The latest completed tool name
-remains visible across one-second snapshots until new tool or response activity replaces it. The
-monitor exposes no controls to steer or stop children.
+(PROP-0030), counts from the child's own checklist, the pinned account label, effective model and
+effort, and cumulative usage totals. Model and effort come from the volatile launch selection; the
+latest provider-reported model supersedes the launch model when usage is available. Usage is an
+explicit projection of token, cache, cost, request-count and context-window totals. Per-request
+payloads and reasoning summaries do not enter the monitor. The child's own `session_name` is not
+projected; it names the child's session, not its row. Tool summaries, other arguments, output and
+checklist item text never enter the monitor. The latest completed tool name remains visible across
+one-second snapshots until new tool or response activity replaces it. The monitor exposes no
+controls to steer or stop children.
 
 The live rows sit under the status line, after one blank row, with no heading. Each row reads, in
 order: the status mark (`○` queued, a running row that shows the working spinner's frame in the profile's colour (warning for a copy of the parent), `●` waiting in the accent,
 `✓` done, `✕` failed, `!` stopped), the profile name in its colour (`subagent`, muted, for a copy
 of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` when the child
 keeps a checklist. Active rows come first, at most three, then `+N more · /subagents`; a narrow
-terminal cuts the title first. `/subagents` opens the searchable full roster with the same fields.
-Finished rows remain until the parent run settles. The projection is volatile and scoped to that
-parent run; it is not a persisted event or public server method.
+terminal cuts the title first. `/subagents` opens the searchable full roster, with a colored
+profile and normal-color title on its first line, then muted account, model, effort and usage
+metadata on its second line. One blank row separates each two-line entry. Narrow rows truncate this
+lower-priority summary without hiding the title.
+At parent settlement, the terminal makes a final monitor read and keeps the latest parent's rows
+visible until the next parent run starts. The projection remains volatile and read-only, is scoped to
+the latest parent run in the terminal session, and is cleared on session replacement or terminal
+disposal. It is not a persisted event or public server method.
 
 ## Agent profiles (PROP-0029)
 

package/docs/architecture/12-storage.md

@@ -25,10 +25,12 @@ index.
   plugins/<name>/      packages kept with the data   (06)
   trash/plugins/       removed packages   (06)
   hub/                 installed documents and provenance   (09)
-  runs/<id>/           run.json, events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json   (02)
+  runs/<id>/           run.json (including optional legacy-compatible workspaceRoot), events.jsonl, owner.json, subagents.json, context.json, caller.json, capabilities.json, mcp-context.json   (02)
+  # `checkpoint` and `heartbeat` are run events in the same events.jsonl; a bounded reply emits one
+  # heartbeat per 30 seconds (about 60 KB an hour) and no side file (PROP-0041).
   config/              plugin-attachments.json and settings the harness reads   (06)
   agents/<name>.md     a person's global agent profiles; agents/profiles.ts owns it   (02, PROP-0029)
-  index.sqlite         derived index (FTS5)   (08)
+  index.sqlite         derived index (FTS5, recall, usage ledger)   (08, PROP-0042)
   projects.json        read only: the application owns it
 
 <state dir>/
@@ -48,6 +50,25 @@ index.
   harness.log          standalone terminal diagnostics
 ```
 
+The interactive profile is a credential-free, versioned selection file at
+`~/.xingular-harness/profile.json`, owned by `src/core/interactiveProfile.ts`. It selects the
+interactive defaults: data root, state directory, default variant scope, and a credential-backend
+descriptor. With no selected profile, the defaults are `~/.xingular-harness/data`,
+`~/.xingular-harness/state`, scope `default`, and the state directory's owner-only file secret
+store. A host may provide a stable host-backed secret adapter instead; the profile stores only its
+identifier, never credentials. If that adapter is unavailable, startup fails rather than falling
+back to a different store.
+
+Explicit roots or variant scopes take precedence over the selected profile; the selected profile
+precedes caller-supplied legacy defaults. Explicit adoption creates the profile file without
+replacing an existing selection and does not create, copy, merge, or migrate data roots or
+credentials. Existing account, variant, and session pins remain authoritative for their saved
+runs; the profile selects defaults for new interactive work. `scripts/dev.mjs` and a development
+interactive profile use `~/.xingular-harness-dev/{data,state}` and a separate profile file, not the
+production defaults. The standalone development launch always selects a file SecretStore under its
+resolved development state directory, even if that profile names a host backend; it does not use or
+alter host credentials.
+
 Side-question runs use the ordinary `runs/<id>/` records. Their temporary Pi native history is
 created under the operating system temporary directory and removed when the run ends; it is not
 retained in the data root or state directory.
@@ -68,6 +89,13 @@ retained in the data root or state directory.
   as it was when a migration fails, and the failure is reported in `Recovery.migrationError`.
 - **INV-STO-6** Writes of shared JSON files are atomic (`core/fs.ts::atomicWrite`, `writeJson`).
 - **INV-STO-7** Files holding trust or secrets are owner-only (`0600`).
+- **INV-STO-8** `core/interactiveProfile.ts` owns the credential-free selection of interactive
+  roots, default variant scope, and credential-backend descriptor. Explicit roots/scopes win; a
+  selected profile wins over legacy defaults. Adoption never replaces a selection or merges roots,
+  and a missing host credential adapter never silently downgrades to a file store. The standalone
+  development launch explicitly selects its isolated file store; this is not a fallback for normal
+  interactive profiles. Profile defaults do not replace the account, variant, or other pins on saved
+  runs.
 
 ## Source map
 

package/docs/architecture/13-world-tools.md

@@ -18,6 +18,21 @@ synthetic page. Their input runs only after live-check confirmation, and their r
 released on completion, timeout or cancellation. Computer interaction needs a host-provided
 isolated surface; without one it is blocked.
 
+## Shared browser contract and native WebKit limits (PROP-0040)
+
+`browser/contracts.ts` owns the backend-neutral names and input schemas for `browser_*` tools;
+providers adapt those definitions rather than inventing host-specific selectors. The isolated Harness
+backend supports accessibility snapshots and snapshot-scoped refs. A native WebKit host backend
+currently supports navigation, tab management, visible-text reads and page-level scrolling without a
+ref. It does not support accessibility snapshots, snapshot refs or ref-based click/type/select/scroll,
+browser screenshots, browser waits or keyboard presses.
+
+For an unsupported operation the native provider returns an explicit `browser_unsupported` refusal
+with “Nothing was done”; it never treats a snapshot ref as a selector and never silently switches to
+the isolated browser. The isolated Harness browser is an independent backend, not an automatic
+fallback for the native provider. A host plugin's `surfaces` description labels that fallback and its
+limits; it does not assert full browser parity.
+
 Plugin ownership and the Foundation boundary are recorded in PROP-0012, ADR-0014 and PROP-0020.
 World providers are assembled through `BuiltinPluginRegistry`; no eighth extension point is added.
 
@@ -39,7 +54,13 @@ terminal, or in a host's own web view running the same page helper (`annotations
   - A queued note is shared with its session.
   - `annotations/delivery.ts` sends a batch as one instruction, and sends notes the person asked for while the session was busy when its run ends.
   - The agent reports a fix with `page_notes_mark_fixed`, the only page-note tool that writes. It never resolves a note or changes grants.
-- **Targets.** Besides the browser window, capture can use an app's own windows:
+- **Targets.** Element targets prefer semantic role/name/text. A visually empty element may still be
+  annotated when it has a specific CSS selector (ID, test ID, classes, and a structural path when
+  needed); bare tag selectors are not enough. Reveal checks for one live match and preserves any
+  captured semantic/context evidence, otherwise reporting ambiguous or unresolved. Text annotations
+  continue to use quote plus context, not screen coordinates.
+- Besides the browser window, capture can use an app's own windows:
   - **DevTools port:** an app started with a DevTools port, on a loopback address only. It uses the app's existing windows, routes nothing, and never closes the app.
   - **Page bridge:** a loopback server whose script an app loads while it is developed (`annotations/bridge.ts`), for web views without a DevTools port.
+- **Web components (PROP-0038).** The helper walks the composed tree: open shadow roots and slotted content can be picked, selected and revealed, and such targets carry `tree: 'composed'`. Targets without it resolve by the document-only rules as before. Closed shadow roots and frames stay out of reach, and the inspector says why it refuses something.
 - **Trust.** In Chromium targets the helper runs in an isolated script world, so the page cannot forge a comment. A send from the bridge, or from a host web view without isolation, waits for the person to confirm it.

package/docs/architecture/14-surfaces-and-parity.md

@@ -27,14 +27,39 @@ terminal command or page, a host screen.
 
 - A capability is reachable through server methods (page 10) and, where a model uses it, through a
   tool that passes the gate (page 07). Both front ends use the same methods; neither has a private
-  path to Harness state.
-- Required built-in plugin commands and Foundation commands use unprefixed names. Optional built-in
-  plugin commands and Pi extension commands use `/plugin:<command>`. A bare command, alias or loaded
-  prompt owns its name; a colliding prefixed command is hidden and rejected. Built-in plugin
-  categories are documented in page 06 and are not public plugin metadata.
+  path to Harness state. Foundation context behavior, including bounded checkpoint restoration after
+  compaction (PROP-0033), is shared by terminal and embedded sessions; a host does not reimplement it.
+- Workspace write scope is Harness-owned on both surfaces. Each run pins a canonical root after
+  worktree selection; reads retain OS-permission scope, while native file writes and shell
+  filesystem effects default to that root; the filesystem root itself is not a valid workspace.
+  Native mutations revalidate their canonical target and atomically replace the file under an OS
+  write scope. Default Bash scans for external hard-link
+  aliases and runs under an OS sandbox that prevents its own processes from creating cross-boundary
+  hard links; on macOS the sandbox denies hard-link creation entirely, including within the
+  workspace. `workspaceWriteScope: 'outside'` (terminal `!outside <command>`) requests a human-only
+  approval before one execution, showing the complete escaped command in scrollable terminal details
+  and denying if the terminal is too small. Output never triggers approval or retry. Hosts may
+  tighten or deny policy but cannot silently waive the boundary. Only the eligible Full Permission
+  switch may answer automatically under its existing restrictions. A same-user peer process outside
+  Harness is not controlled by this rule. `workspaceRoot` is additive and legacy run records may
+  omit it.
+- Harness core terminal commands use unprefixed names and are registered independently of feature
+  plugin command metadata. This includes `/doctor`, `/worktree`, `/trajectory`, `/subagents` and
+  `/agents`; `/history` remains session-branch navigation, and `/mcp` remains a Connections shortcut.
+  Every plugin-owned terminal command uses `/<owner-prefix>:<command>`, for required and optional
+  built-ins and Pi extensions alike. Built-in prefixes are stable registry metadata; Pi package
+  extensions use a normalized package name or the package's `harness.commandPrefix`, and loose
+  extensions use their normalized extension name. Prefix collisions and duplicate commands within
+  one owner are rejected with owner diagnostics. Built-in plugin modules may declare a default
+  command for their namespace root. The former owner-qualified and `/plugin:<command>` forms of
+  promoted Harness commands remain hidden compatibility aliases for one release. Prompt templates
+  and `/skill:<name>` keep their existing forms. Built-in plugin categories remain documented in
+  page 06, not public metadata.
 - A capability may be limited to a run mode when Harness resolves the callable set; the register
   records that restriction for both surfaces. `ask_user` is available only in attended plan runs,
-  and the terminal's `ask_user_question` alias follows the same restriction.
+  with no terminal-only question alias (PROP-0040). Plan-mode delegation
+  is limited to named profiles whose effective tool and plugin allowlists qualify for read-only
+  research; both terminal and host use the same gate and child-capability narrowing.
 - Question choice sketches use one optional validated event contract: up to 80 printable ASCII
   columns by 24 LF-separated lines (1,943 bytes maximum; page 02). Both surfaces use the same
   literal ASCII source, persisted unchanged, in one shared preview with access to overflow; neither
@@ -56,6 +81,27 @@ terminal command or page, a host screen.
 - Side questions use one Harness service on both surfaces. Each caller supplies its visible
   transcript projection; Harness adds the parent run's effective prompt and public events, then
   starts an independent tool-free run.
+- PROP-0040 defines one shared launch/command contract: `Launch.standard`, `commands.list`,
+  saved-history controls and tracked `SessionRunInput.command` runs. Hosts present these rather
+  than approximating navigation with a fork. A listed command or handler is not proof of acceptance.
+  The current host `/session` picker reads a host-owned session catalog rather than a shared Harness
+  catalog (PAR-008), and read-only command pages do not stand in for unsupported management methods.
+  The register records command routes individually; parity remains open until each route passes
+  acceptance.
+- Read-only `get_capabilities` is implemented in structured sessions and the terminal. Structured
+  sessions report tools filtered by the run's frozen capability set and actual registered schemas;
+  the terminal reports Pi's active tools and schemas, applying its plan-mode allowed set when active.
+  It is in the shared plan-mode allowlist and grants no permission. Hosts use this Harness tool rather
+  than defining a duplicate.
+- `browser/contracts.ts` owns shared backend-neutral browser schemas. A native WebKit host backend
+  still lacks accessibility snapshots and snapshot-ref interactions, browser screenshots, waits and
+  keyboard input; unsupported calls return an explicit refusal before effects and do not trigger an
+  automatic backend switch (page 13, PAR-015).
+- Shared interactive defaults, profile adoption, credentials and a cross-surface session catalog
+  remain in progress under PROP-0040. Existing pins and explicit profile choices win; adoption must
+  not merge stores, copy credentials or silently downgrade the secret backend.
+- `PluginDescriptor.surfaces` / `Plugin.surfaces` optionally describe a host preference, terminal
+  fallback/unavailability and reason. This labels add-ons, not plugin categories or permissions.
 - The register of capabilities and their surfaces is [`docs/parity.md`](../parity.md). It is
   descriptive; the invariants below are binding.
 - A host keeps its own register of host-only surfaces. The Harness names no host surface.
@@ -86,4 +132,5 @@ None of its own. Each capability stores its data as its own page says.
 `src/harness.ts` (services), `src/world/world.ts` (world parts), `src/plugins/builtin.ts`
 (first-party descriptors), `src/terminal/` (terminal surfaces), `src/server/methods.ts` (methods).
 Decision: [PROP-0015](proposals/PROP-0015-one-capability-surface.md),
-[ADR-0017](../decisions/ADR-0017-one-capability-surface.md).
+[ADR-0017](../decisions/ADR-0017-one-capability-surface.md),
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md).

package/docs/architecture/README.md

@@ -1,6 +1,6 @@
 # Harness architecture specification
 
-**Status:** binding. **As of:** 2026-10-24, checked against `src/` on branch `release/1.0.0`.
+**Status:** binding. **As of:** 2026-10-26, checked against `src/` on branch `release/1.0.0`.
 
 This folder is the core specification of `@xingular/harness`. Code must conform to it. A change
 that would alter what it says needs a proposal the user approves first (see
@@ -123,3 +123,5 @@ proposal, or a correction to the other document).
 | D-14 | 12-storage layout | Page 12 lists browser settings under `<state dir>/browser/`, while `browser/config.ts` stores configuration in `<state dir>/browser.json`; browser profiles and downloads use the `browser/` directory. The layout needs an owner decision before either side is changed. |
 | D-15 | Terminal sketch verification status — resolved 2026-10-24 by PROP-0028 | Pages 11 and 14 and `terminal-tui.md` said connected-sketch implementation verification was pending, while retained PTY evidence and PAR-014 recorded it as verified. Updated the docs to distinguish deterministic fixture verification from owner visual acceptance, every-emulator rendering and live-model sketch quality. |
 | D-16 | Terminal slash-command highlighting — resolved 2026-10-24 | `terminal-tui.md` specified accent coloring for recognized leading commands while typing, but the OpenTUI composer only styled attachment labels. User-message bubbles also lacked command-token styling. The renderer now uses the active command registry for both surfaces. |
+| D-17 | `PROP-0039`, `ADR-0036`, `INV-GATE-3/8` | Implementation is in progress in the 1.2.0 worktree: native writes revalidate canonical targets and atomically replace files under an OS write scope; default Bash fails closed on external hard-link aliases and runs in a sandbox that prevents new cross-boundary links; outside-scope Bash requires approval before one execution and command output never triggers approval or replay. The filesystem root is rejected as a workspace, and approval details expose the complete command. Launcher selection uses fixed system paths. Same-user peer processes remain outside this boundary. Focused macOS tests, full Harness CI, App compatibility checks, and PTY verification at 40x20, 80x24, and 100x30 pass. Linux sandbox integration remains unverified locally because this Darwin host has no `bwrap` and Colima is stopped; both CI workflows now install bubblewrap and `scripts/ci.sh` fails if it is absent, but an Ubuntu run is still required. No candidate, tag, or publication exists. |
+| D-18 | `core/index.ts` migration 5 | The `run_stats` table has no writer in the Harness. PROP-0042's `usage_requests` ledger is the analytics source; whether to drop the older table is open. |

package/docs/architecture/proposals/PROP-0017-page-annotations.md

@@ -3,7 +3,7 @@ id: PROP-0017
 title: Page annotations as a Harness capability, captured in the headed browser or a host's web view
 status: Implemented
 created: 2026-10-23
-updated: 2026-10-23
+updated: 2026-10-25
 affects: [INV-STO-3, INV-SRV-1, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
 ---
 
@@ -41,7 +41,11 @@ grants, history }`, the format of the App store, so existing notes import unchan
 - `source`: `{ url, title, capturedAt }` plus an optional opaque `surface` string from the capturing
   front end.
 - `target`: `page`, `text { exact, prefix, suffix, start, end }` (Unicode code points over
-  normalised page text), or `element { tag, role, name, text, context, selector }`.
+  normalised page text), or `element { tag, role, name, text, context, selector }`. Element capture
+  prefers role/name/text; when an otherwise empty visual element has no semantic label, it may use
+  a specific CSS selector (ID, test ID, classes, and a structural path when needed), never a bare
+  tag. Resolution uses that selector only when it identifies one allowed element and the captured
+  semantics/context still agree; stale or duplicate targets remain unresolved or ambiguous.
 - `status`: `open` or `resolved`. `version` increases on every change; update and delete name the
   version they expect (compare-and-swap). The last 100 change receipts are kept, without earlier
   bodies. At most 10,000 notes.

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

@@ -51,7 +51,7 @@ A note gains an optional `delivery`:
 - ⌘/Ctrl+Enter is Proceed now; with Shift it is queue.
 - Everything is drawn in a closed shadow root.
 - The page never receives the press or click on what is inspected, nor anything typed in the popover.
-- Inputs, secrets, `[data-sensitive]` elements, frames, shadow roots and custom elements are never picked, as in PROP-0017.
+- Inputs, secrets, `[data-sensitive]` elements, frames, shadow roots and custom elements are never picked, as in PROP-0017. (Open shadow roots and readable custom elements became pickable in [PROP-0038](PROP-0038-annotate-open-shadow-roots.md).)
 - The inspector stays on after each comment.
 - A new operation, `next`, returns `{ active, documentId, url, title, result }`, one comment at a time.
 - `toast` shows a short status in the page.