@xingular/harness 1.1.1 → 1.3.1-unstable.0

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 todo list 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)
@@ -115,19 +156,29 @@ on close. No command text is sent to the conversation model. See [Doctor](../doc
 
 ## Resource browser (PROP-0013)
 
-`/harness` owns shared navigation for Foundation, Variant, Skills, Plugins, Connections, Tools
-and Library. `/skills`, `/plugins`, `/connections` (`/mcp`), `/tools`, `/hub` and `/components`
-are shortcuts into that browser. Current availability comes from the live resource loader and
-active tool registry, independently of saved configuration and the latest variant head.
+`/harness` owns broad navigation for Foundation, Variant, Skills, Plugins, Connections, Tools and
+Library. `/skills`, `/connections` (`/mcp`), `/tools` and `/components` are shortcuts into that
+browser. `/plugins` opens the focused local plugin manager (Plugins, Trust and Packages tabs); `/hub`
+opens the separate Community catalog (Catalog and Installed tabs). The Hub Catalog shows Community
+entries across supported types; Installed retains receipts from every channel with its channel
+visible. Registry/document entries offer bounded payload Preview; Pi packages do not. Current
+availability in `/harness` comes from the live resource loader and active tool registry,
+independently of saved configuration and the latest variant head.
 
 Every `terminal.browser.*` call requires the private control key, including bounded resource
-inspection, local imports, connection management and browser settings. Package install/remove use protected
-`plugins.install|remove`. These are adapters to the existing services, not another loader,
-attachment store, gate or secret store. Browsing neither executes plugin code nor connects MCP.
+inspection, local imports, connection management and browser settings. Direct plugin package
+install/update/remove and attachment/trust/settings actions use protected `plugins.*`; Hub catalog
+list/install/uninstall use protected `hub.*`. Hub-owned package removal keeps the receipt and
+resource ownership in the Hub service. These routes are adapters to the existing services, not
+another loader, attachment store, gate or secret store. Browsing neither executes plugin code nor
+connects MCP.
 The browser uses the full terminal with persistent section tabs (PROP-0014); wide screens keep
 inventory beside details, actions and content, while compact screens keep inline details under
-the same tabs. Other command pages remain centered except `/settings` and `/accounts`, which use
-full-screen page layouts. Accounts keeps Accounts/Pools tabs, search and account-service operations.
+the same tabs. The separate `/plugins` and `/hub` pages also use full-screen layouts with persistent
+section tabs, responsive inventory/details panes and their existing protected operations. Other
+command pages remain centered except `/settings`, `/accounts`, `/plugins` and `/hub`, which use
+full-screen page layouts.
+Accounts keeps Accounts/Pools tabs, search and account-service operations.
 Wide terminals show selected-account details beside the list; Enter or a primary click opens grouped
 actions in that inspector. Compact terminals replace the list with a full-page account detail view
 and its grouped actions. Enter opens the selected account; Escape returns to the list while
@@ -166,7 +217,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,54 +253,89 @@ 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.
 - **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|queue|dequeue|confirm|send` act only on this terminal's session and need the control key.
 
-## Checklist (PROP-0006, PAR-001)
-
-Terminal sessions register the shared `checklist_write` tool. The extension validates each list
-with the same tool code and sends it as `checklist` telemetry; the controller emits it as
-`checklist.updated` on the active run, so `runs.checklist` and continuation read terminal runs too.
-The gate treats it as read-only, plan mode allows it, and terminal children inherit it. The
-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.
+## Todo list (PROP-0006, PROP-0045, PAR-001)
+
+Terminal sessions register the shared `todo_write` tool. The extension validates each list with
+the same tool code and sends it as `todo` telemetry; the controller emits it as `todo.updated` on the
+active run, so `runs.todo` and continuation read terminal runs too. The gate treats it as read-only,
+plan mode allows it, and terminal children inherit it. The transcript shows each write as a todo
+block (`✓` done, `●` in progress (warning yellow), `○` pending) under a `Todo · n of m done` header
+instead of a tool row; a failed or malformed call stays a tool row. `/todo` reads the latest
+non-side-question run of this terminal's native session and appends the same card as a snapshot,
+without a model request; an empty list is a one-line notice. `/checklist` remains its alias for one
+release.
+
+## Work-slice checkpoint (PROP-0041)
+
+Terminal replies carry the same work-slice guard as structured runs: 320 tool calls or 60 minutes,
+with no new-token limit by default (PROP-0044), 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 todo list, 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
+todo 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.
+keeps a todo list. 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 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 monitor also projects the parent run itself as a `main` row (profile `main`, a reserved name,
+in the theme's primary colour) with the same account, model, effort, usage, activity and todo
+fields. The `/subagents` page pins it first and counts only children in its header; the rows under
+the status line omit it, since the status line already describes the main agent.
+
+Every turn marks its run on the native branch (`xingular-subagent-owner`), and `ready` sends those
+owners. When a conversation opens or is switched to with no run active, the monitor is rebuilt from
+the branch's latest top-level run in this folder and its descendants, by folding their saved events
+with their final status. Runs a stopped process left active were already marked `interrupted`.
+The rows show under the status line and on the page until the next parent run starts (ADR-0043).
+The projection remains read-only and scoped to one parent run; a switch to a conversation with no
+such run clears it, as does 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

@@ -17,7 +17,7 @@ terminal command or page, a host screen.
 |---|---|---|
 | Foundation service | A member of `Harness` with server methods | `sessions`, `accounts`, `apps`, `worktrees` (PROP-0016), agent profiles (`agents.*`, PROP-0029) |
 | Built-in feature plugin | A module in `BuiltinPluginRegistry` (`plugins/builtin.ts`) that may supply a `WorldPart`, server methods and terminal commands | web tools, browser tools, annotations, worktrees |
-| First-party plugin | A descriptor in the registry (`plugins/builtin.ts`) | lessons, checklist |
+| First-party plugin | A descriptor in the registry (`plugins/builtin.ts`) | lessons, todo |
 | Terminal surface | A command, page or dialog in `terminal/` | `/plan`, `/doctor`, the resource browser |
 | Host surface | A host screen built on the same methods and tools | the App's chat, Capability and Harness screens |
 | Host-backed backend | An operating-system object only a host has, behind a generic Harness contract | the App's WebKit tabs, macOS computer bridge, keychain |
@@ -27,14 +27,42 @@ 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.
+  The direct `/plugins` page manages local plugin state and package lifecycle; `/hub` presents the
+  Community catalog and all installed Hub receipts. These are distinct presentations of existing
+  Harness services, not host-only capabilities. The broad `/harness` browser remains available.
+- 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 +84,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 +135,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,10 +1,11 @@
 # 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-27, 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
-[Changing the architecture](#changing-the-architecture)).
+that alters what it says must update the affected pages in the same change (see
+[Changing the architecture](#changing-the-architecture)). Proposals are optional design records,
+not prerequisites or approval gates.
 
 Other documents explain and record; this folder decides. Where another document disagrees with a
 page here, this page wins, and the disagreement is listed under [Known drift](#known-drift).
@@ -64,7 +65,7 @@ current behavior.
 
 | Word | Meaning |
 |---|---|
-| **Foundation** | The fixed half of the harness: code and invariants that no edit, improver or adoption can change. Changes by release, and by proposal when a contract moves. |
+| **Foundation** | The fixed half of the harness: code and invariants that no edit, improver or adoption can change. Changes by release; contract changes update the specification and may use an optional proposal as a design record. |
 | **Agent Mode** | A planned foundation-level work style, with at most one mode active at a time. Plugins remain independently stackable contributions. This is distinct from plan mode and existing `mode` fields; it is not a runtime contract ([FW-0001](../future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode)). |
 | **Variant** | The mutating half: one tree of eight components (c1–c8) for one scope. Formerly "harness tree". |
 | **Component** | One of c1–c8 inside a variant (system prompt, guardrails, memory, tool guidance, subagents, skills, scripts, plugins). |
@@ -86,24 +87,24 @@ Every coding agent and contributor follows these steps.
 2. **Within the spec: just do it.** If the change fits every contract and invariant, make it. If it
    adds detail without changing a rule (a new server method in an existing group, a new optional
    field), update the page in the same commit.
-3. **Outside the spec: propose and stop.** If the change would alter a contract, an invariant, a
-   layer boundary, an extension point, or the storage layout, do not change code or pages yet.
-   Write `proposals/PROP-NNNN-<slug>.md` from the [template](proposals/README.md#template) with
-   status `Proposed`, add it to the proposals index, and ask the user to review it.
-4. **After approval.** The user sets or confirms status `Accepted`. Then implement it, update the
-   affected pages in the same change, and add an ADR in `../decisions/` when the choice is a
-   lasting one. A rejected proposal keeps its file with status `Rejected`.
+3. **Outside the spec: implement and update.** If the change alters a contract, an invariant, a
+   layer boundary, an extension point, or the storage layout, implement the requested change and
+   update affected pages in the same change. A proposal may document the design, but is optional
+   and does not gate implementation.
+4. **Record lasting decisions.** Add an ADR in `../decisions/` when the choice is a lasting one.
+   Proposals may be added to the index when useful; no `Accepted` status is required before work.
 5. **Drift is reported, not fixed silently.** If code and a page already disagree, add the item to
-   [Known drift](#known-drift) and tell the user. Do not change either side to match without
-   asking; resolving drift that changes a rule is itself a proposal.
+   [Known drift](#known-drift) and tell the user. When resolving drift within the requested scope,
+   update the code and spec together and record the rationale; do not silently change unrelated
+   behavior.
 
-When unsure whether a change alters the architecture, treat it as if it does and write the
-proposal.
+When unsure whether a change alters the architecture, read the affected pages and update them in
+the same change. Use a proposal only when it helps explain the design.
 
 ## Known drift
 
-Disagreements found while writing this specification. Each needs a decision from the user (a
-proposal, or a correction to the other document).
+Disagreements found while writing this specification. Record their evidence here and report them;
+resolve relevant drift by updating the implementation and specification together in the same change.
 
 | ID | Where | What disagrees |
 |---|---|---|
@@ -123,3 +124,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-0006-run-checklist.md

@@ -9,6 +9,8 @@ affects: [02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 07-tools-and-
 
 # PROP-0006: A run checklist the model writes, recorded as a run event
 
+> Renamed to todo by [PROP-0045](PROP-0045-rename-checklist-to-todo.md). The names below are historical.
+
 ## Problem
 
 A run has no structured record of progress. `goal` on a run is opaque text, and plan mode ends

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.