@xingular/harness 1.1.1 → 1.3.1-unstable.0

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

@@ -4,7 +4,9 @@
 
 A run's tools come from four places: the harness's own tools, the connected-apps broker,
 subagent tools, and the application's tool providers. Every call, whatever its source, passes one
-per-call gate that asks the application's policy, then standing approvals, then the person.
+per-call gate. Native writes also obey the run's pinned workspace boundary, with shell writes
+contained by an OS sandbox; the gate then applies application policy, standing approvals and the
+person without letting remembered per-tool grants widen that boundary.
 
 ## Components
 
@@ -14,39 +16,102 @@ per-call gate that asks the application's policy, then standing approvals, then
 | `dispatch` | `tools/dispatch.ts` | One entry point for every History, Wiki and skill call, from a Pi tool, the server or a terminal. |
 | `harnessTools` | `tools/harnessTools.ts` | The definitions as `ToolSpec`s for one session. |
 | `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
-| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `checklist` telemetry call. The prompt's Progress group asks the model to keep it current because the user follows work from it. |
-| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030), `wait_subagents`. |
+| `todoTool` (`todo_write`) | `tools/todo.ts` | Writes the run's whole todo list as a `todo.updated` event (PROP-0006, renamed by PROP-0045). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `todo` telemetry call. The prompt's Progress group asks the model to call it before the first other tool call when work has several steps, keep it current, and write one final update before replying; unfinished work is not automatically marked complete. The pre-rename `checklist.updated` event is still read, never written. |
+| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
 | `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
 | `Approvals`, `decide`, `grant`, `approvalKey` | `sessions/approvals.ts` | Standing approvals. |
 
-Harness tools: `history_search`, `history_read`, `trajectory_search`, `trajectory_read`,
-`wiki_search`, `wiki_read`, `wiki_list`, `wiki_write` (not in the default set), `skill_load`,
-`ask_user` (attended plan runs and pinned continuations only), `checklist_write`. Broker:
+Harness tools: `get_capabilities` (read-only current-run discovery), `history_search`, `history_read`,
+`trajectory_search`, `trajectory_read`, `wiki_search`, `wiki_read`, `wiki_list`, `wiki_write`
+(not in the default set), `skill_load`, `ask_user` (attended plan runs and pinned continuations only),
+`todo_write`. Broker:
 `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
+## Cross-surface registration (PROP-0040)
+
+The terminal registers Harness History/trajectory, Wiki-read and skill tools through
+`Terminals.ownTools` and dispatches them over the session socket; they are model tools, not merely
+shell commands. Enabled first-party hooks load through the protected `firstParty.list` bridge and
+`terminal/piExtension.ts`. Attended planning uses the shared `ask_user`; the terminal-only question
+alias is removed.
+
+`get_capabilities` is implemented as a read-only Harness tool. Structured sessions register it from
+the current run's frozen capability snapshot and live Pi tool/schema inventory. The terminal
+extension (`terminal/piExtension.ts`) registers the same schema from Pi's active and registered tools;
+when plan mode is active it reports the plan's allowed tool set. `sessions/planMode.ts` includes it in
+the shared read-only allowlist. Host sessions use this Harness tool rather than defining a duplicate.
+It reports availability, never permission, and every call remains subject to the gate.
+
 ## Native file paths
 
 The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
-absolute paths, and `~` paths. The working folder is a default location, not a repository boundary;
-the operating system's access for the Harness process decides what can be read. The compiled file
-guidance names the configured data root. `edit`, `write` and `bash` continue through the existing
-gate and policy. A side-question run has an empty capability set and no tools (PROP-0019).
+absolute paths, and `~` paths. The working folder is a default location, not a read boundary; the
+operating system's access for the Harness process decides what can be read. The compiled file
+guidance names the configured data root. Each run pins `workspaceRoot`: the nearest Git root or
+worktree above its effective working directory, or the canonical working directory when there is no
+repository. The filesystem root itself is rejected because it would collapse the write boundary.
+`edit` and `write` resolve targets canonically, revalidate the pinned target at mutation,
+and atomically replace the directory entry in a helper process constrained by the OS sandbox. This
+prevents hard-link writes from changing another alias; normal file mode is retained where possible,
+but ACLs and extended attributes are not guaranteed to survive replacement. An outside target
+requires a human-only one-call approval (or an eligible Full Permission answer) and is not covered by
+remembered tool grants.
+
+Bash, including an initial `!` command, runs in an OS-enforced sandbox that permits broad reads but
+writes only inside the root. Before default-scope Bash, Harness scans the workspace for regular-file
+inodes with links outside it; an incomplete scan or possible external alias blocks the command, which
+must be repaired or copied. The sandbox also prevents its own processes from creating cross-boundary
+hard links; macOS denies hard-link creation entirely, including within the workspace. A local process
+outside Harness running as the same user is outside this protection.
+The Bash tool's optional `workspaceWriteScope` defaults to `workspace`; `outside` requests a
+human-only one-call approval before the exact command runs once with broader filesystem access. The
+approval shows the full escaped command in scrollable details and fails closed if the terminal
+cannot show both the details and the choices. The terminal uses `!outside <command>` for the same
+explicit request on a direct initial command.
+stdout/stderr never proves a sandbox denial: denial text cannot request approval, and a command is
+never replayed after partial effects. Full Permission is the explicit eligible-run bypass.
+Unsupported or unavailable sandbox enforcement fails closed. A side-question run has an empty
+capability set and no tools (PROP-0019).
+
+**Windows** has no write-boundary sandbox the harness can use, so the Bash tool treats every
+command there as an outside request: a human-only one-call approval (or an eligible Full
+Permission answer), then the command runs once without a sandbox. Plan-mode Bash is refused,
+because a read-only scope cannot be enforced. Commands run in Git Bash when it is installed
+(`%ProgramFiles%\Git\bin\bash.exe`, then `bash.exe` on `PATH`, never the WSL launcher in
+`System32`), otherwise in PowerShell (`pwsh.exe`, then Windows PowerShell). The tool keeps the name
+`bash`; its description names the shell. Native `edit` and `write` run their atomic helper with
+Node directly, without an OS guard: the target is still canonicalized, authorized, revalidated and
+replaced by rename, and outside targets still need their approval, but a junction or symlink swap
+between the check and the rename is not prevented
+([ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md)).
 
 ## The gate, per call
 
+For native `edit` and `write`, the canonical target check is added to policy scope before approval;
+the registered tool can mutate only through the policy-bound atomic helper. Bash workspace scope
+scans for external hard links and then runs under the OS sandbox. An explicit outside scope is
+approved before execution and runs once; stdout/stderr never triggers approval or retry. The
+eligible Full Permission switch may answer the explicit request under its existing restrictions, but
+a remembered tool grant cannot.
+
 ```text
 child run and tool outside its snapshot ─► refuse
-plan mode and tool not research-safe    ─► refuse (before approvals)
+plan mode and tool/call not research-safe ─► refuse (including ineligible spawn profiles, outside-scope or denied Bash; before approvals)
+plan-mode Bash                          ─► read-only OS sandbox, never widened, run once
+canonicalize native write target / verify pinned root
 policy.scope(call)
   not allowed and (automatic or no approval possible) ─► refuse with reason
 policy.authorize(call) throws           ─► refuse
-allowed, not humanOnly, (automatic or not gated) ─► run
-trigger probe or improver               ─► refuse (nobody to ask)
-run.requestApproval(...)                ─► standing approvals may answer, else the person
-  denied                                ─► refuse
+outside native file target              ─► human-only one-call approval; eligible Full Permission may answer
+Bash workspace scope                    ─► hard-link scan, OS sandbox, run once
+Bash outside scope                      ─► pre-execution human-only approval, then run once unconfined
+Bash on Windows (no sandbox)            ─► as outside scope; plan-mode Bash refused
+trigger probe, improver, reflection or unattended ─► refuse anything requiring a person
+run.requestApproval(...)                ─► standing approvals may answer where eligible, else the person
+  denied                                ─► refuse; never replay a command
 policy.authorize(call) again            ─► run or refuse
 ```
 
@@ -60,23 +125,52 @@ the switch and global tools.
 
 - **INV-GATE-1** Every tool call of every run passes the gate. No tool source bypasses it,
   including extension-registered tools (which ask before every call) and the initial Bash command.
+- **INV-TOOL-9** `checkpoint_write` records one bounded handoff for the active run and is read-only
+  and plan-safe: no field changes files, and the record is the `checkpoint` run event (PROP-0041).
+- **INV-TOOL-10** Bash keeps one command budget on every surface: 120 seconds when the call says
+  nothing, 300 seconds as the ceiling without a `reason`, 900 seconds as the maximum, and a timeout
+  returns the partial output with a narrowing instruction instead of blocking the reply.
 - **INV-GATE-2** The gate is the last extension loaded, after disk, variant and inline extensions, so
   it sees the final input of every call.
-- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, then the policy's scope and
-  authorize, then standing approvals, then the person, then authorize again.
+- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, canonicalize native file-write
+  targets, consult the policy's scope and authorize, combine mandatory outside-write approval with
+  that scope, then eligible standing approvals or the person, then authorize again. Native mutations
+  revalidate the authorized target and use atomic replacement inside an OS-enforced write scope.
+  Default Bash scans for external hard links, then runs only inside the OS sandbox. `workspaceWriteScope:
+  'outside'` requests human-only approval before running that exact command once with broader access.
+  Command output never proves a sandbox denial and never triggers approval or replay; earlier
+  side-effects are not repeated. The policy may tighten or deny a call, but cannot waive the boundary.
+  Outside file writes and broad Bash calls cannot use remembered per-tool approval; only the eligible
+  Full Permission switch can answer automatically under its existing restrictions. In plan mode, Bash
+  runs only in the read-only scope (PROP-0043): no writes but a discarded temp folder, no network,
+  no signals outside the sandbox, no macOS mach services; Full Permission and `outside` never apply.
+  On Windows, which has no sandbox, every Bash call takes the `outside` path and plan-mode Bash is
+  refused (ADR-0042).
 - **INV-GATE-4** Refinement runs (`probe`, `improver`) never ask a person; what would need one is
   refused, never queued (`INV-REF-4`).
 - **INV-GATE-5** SDK tools are registered only if their names are in the run's frozen capability
-  set (`INV-CAP-1`). The terminal may retain question-tool definitions in its private Pi inventory,
-  but normal mode deactivates them; a plan request activates only registered questions under its
-  plan-mode gate.
+  set (`INV-CAP-1`). `get_capabilities` is a read-only Harness tool on structured and terminal
+  surfaces; it reports the frozen callable set and does not grant access. The terminal may retain
+  question-tool definitions in its private Pi inventory, but normal mode deactivates them; a plan
+  request activates only registered questions under its plan-mode gate.
 - **INV-GATE-6** Tool attachment bytes never enter the run-event stream; only references are
   recorded.
 - **INV-GATE-7** Tool descriptions name the product with `{product}` (filled by `describeTool`),
   never an application's name (`INV-BND-2`).
-- **INV-GATE-8** Native read-only file access is bounded by process and operating-system
-  permissions, not by the repository root. Absolute and `~` paths are valid inputs. This does not
-  change the gate or permissions for writes and commands.
+- **INV-GATE-8** Native reads are bounded by process and operating-system permissions, not by the
+  workspace root; absolute and `~` paths are valid. Every run pins its canonical `workspaceRoot`.
+  Native `edit` and `write` mutations revalidate the authorized canonical target and atomically
+  replace it under an OS-enforced scope; outside targets require human-only one-call approval and
+  cannot use remembered tool grants. Default Bash scans the workspace for possible outside hard-link
+  aliases and is OS-sandboxed to write only inside the root while retaining broad reads; the sandbox
+  prevents its own processes from creating cross-boundary hard links, and macOS denies all hard-link
+  creation in the sandbox. An incomplete scan or missing
+  enforcement fails closed. An explicit `workspaceWriteScope: 'outside'` request is approved before
+  execution and runs once; command output never triggers approval or retry. The terminal exposes the
+  same choice as `!outside <command>`. Full Permission is the only standing boundary bypass and
+  remains subject to host policy, authorization, read-only, plan, unattended, probe, improver and
+  reflection restrictions. The rule does not protect against a peer process running as the same user.
+  On Windows the atomic replacement runs without an OS-enforced scope (ADR-0042).
 
 ## Data
 
@@ -85,13 +179,18 @@ the switch and global tools.
 ## Source map
 
 `src/tools/*.ts`, `src/web/*.ts`, `src/sessions/sessions.ts`, `src/sessions/runner.ts`,
-`src/sessions/approvals.ts`, `src/sessions/policy.ts`.
+`src/sessions/workspaceBoundary.ts`, `src/sessions/initialBash.ts`, `src/core/workspaceBashTool.ts`,
+`src/core/shell.ts`, `src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`,
+`src/sessions/approvals.ts`, `src/sessions/policy.ts`. Decisions:
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md),
+[ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md).
 
 ## Session naming (PROP-0010)
 
 `session_name` (`tools/sessionName.ts`) binds to the current native session. It maintains
 only Pi session metadata and is explicitly plan-safe, while still subject to capability
-selection and the host policy. The terminal registers the same definition through its Pi
+selection and the host policy. The prompt asks for it once before the first other tool call when
+a request needs tools or changes state. The terminal registers the same definition through its Pi
 bridge; standalone policy permits naming without approval. See page 02 for validation and
 persistence. It is a foundation tool, not mutable variant data.
 
@@ -101,3 +200,10 @@ persistence. It is a foundation tool, not mutable variant data.
 intersect current capabilities, and execute tool calls through the existing gate. Calls that
 require an additional per-call approval report blocked; batch diagnostic consent does not grant
 standing permission. No raw tool inputs, results, or screenshots enter diagnostic findings.
+
+A live check may also run one command the harness wrote itself, when the capability it diagnoses is
+a native Pi tool rather than a harness tool: the shell check runs `printf` through the same
+workspace root, hard-link scan and write-boundary sandbox as a Bash call, and reports only the exit
+status. It passes the gate first, and a diagnostic never widens the boundary — Full Permission,
+an outside-workspace request and a host bypass are all refused for it — so a boundary that stops
+the command before the shell starts is reported as blocked with the boundary's own reason.

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

@@ -38,7 +38,10 @@ skills, prompts, rules and Pi packages.
 - **`apps.expose(tools)`** offers the application's own tools through the broker, which is how a
   terminal session reaches them.
 - **Hub.** `hub.list`, `get`, `preview`, `install`, `uninstall`, `readDocument`. Pi packages need
-  an exact npm version or a full Git commit. Documents are saved as inert JSON.
+  an exact npm version or a full Git commit. Documents are saved as inert JSON. The `/hub` Catalog
+  view filters Community entries for display; the service and other callers retain the full catalog.
+  Installed shows receipts from every channel. On page entry, cached/bundled content is shown before
+  a remote refresh, and origin, refresh time and failure status remain visible (PROP-0047).
 
 ## Invariants
 
@@ -62,12 +65,15 @@ skills, prompts, rules and Pi packages.
   nothing of it is stored.
 - **INV-MCP-4** Hub installation grants no attachment, trust, credential or permission. Writes
   are serialized; existing registry files are never overwritten; uninstall removes only the exact
-  receipt's resources and revokes its attachment choices.
+  receipt's resources and revokes its attachment choices. Every removal route for a Hub-owned Pi
+  package, including `plugins.remove`, goes through Hub's receipt-owning uninstall operation. A
+  floating plugin-package update must not change a Hub-owned package; replacement uses an explicit
+  exact catalog version (PROP-0047).
 
 ## 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 +95,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,24 +33,82 @@ 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
   `plugins.describe`.
 - `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).
+- `runs.todo { runId }` returns the run's latest todo list, `[]` when it wrote none (PROP-0006,
+  renamed by PROP-0045). `runs.checklist` is the deprecated pre-rename alias.
+- `runs.continuation` returns `todo`; `checklist` remains a deprecated mirror of it for one release.
+- 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`.
+  the first line of its brief (PROP-0030). With `continue: <runId>` it continues a stopped child of
+  this conversation instead (no `agent` or `tools`; `brief` and `title` optional) and returns
+  `continued`, the run it continued (ADR-0043).
+- `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 320 calls, 60 minutes, no new-token cap, 8 slices and
+  automatic continuation. A token cap, when set, counts new input, cache writes and output, never the
+  cached prefix (PROP-0044). `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,10 +187,14 @@ 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 |
-
-Protected `plugins.install { source }` and `plugins.remove { pluginId }` delegate to the package
-service. Optional matching callbacks extend `PluginControl`; hosts without them receive a clear
-unsupported-operation error. No protocol version or persisted schema changes.
+| `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 }`, `plugins.update { pluginId? }` and
+`plugins.remove { pluginId }` delegate to the package service. Removing a Hub-owned package routes
+through Hub's receipt-aware uninstall; a floating update refuses Hub-owned packages, while an
+update-all skips them. Optional matching callbacks extend `PluginControl`; hosts without them
+receive a clear unsupported-operation error. No protocol version or persisted schema changes.
 
 ## Worktrees (PROP-0016)