@xingular/harness 1.2.0 → 1.3.1-unstable.1

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

@@ -40,7 +40,9 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   `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.
@@ -49,15 +51,18 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   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).
+  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 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
+  `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,
@@ -65,6 +70,24 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   relayed in order (INV-RUN-3).
 - Errors carry a stable `code`, a message and an optional hint (`core/errors.ts`).
 
+## Plugin proposals
+
+| Method | Input | Reply |
+|---|---|---|
+| `plugins.proposals.create` | `{ name, description, files }` (path-to-text object) | pending `Proposal` |
+| `plugins.proposals.list` | `{}` | `Proposal[]`, including decided records |
+| `plugins.proposals.preview` | `{ id }` | revalidated `Proposal` with current content hash |
+| `plugins.proposals.accept` | `{ id, hash }` | accepted `Proposal` |
+| `plugins.proposals.reject` | `{ id, hash }` | rejected `Proposal` |
+
+A `Proposal` has `id`, `name`, `description`, `files`, generated `manifest`, `hash`, `createdAt`,
+`status` and optional `decidedAt`. Both decisions require the pending proposal's current preview
+hash; acceptance installs it switched off without trusting code. These methods expose trusted host
+operations, not an assertion that a host has built a review UI. Protected terminal control routes
+`plugins.proposals.list|preview|accept|reject` delegate to the same service when configured; they
+require the terminal control key. The model tool can create only. Validation and trust details are
+on page 06.
+
 ## Usage (PROP-0042)
 
 | Method | Input | Reply |
@@ -183,11 +206,14 @@ from preparation, never from the request.
 | `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.allLimits` | `{ refresh? }` | All-account provider limits; refresh reads providers due under the configured cache interval, without changing the pinned account |
 | `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
-unsupported-operation error. No protocol version or persisted schema changes.
+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)
 
@@ -224,14 +250,18 @@ same service through `terminal.worktrees.*` routes, which need the control key (
 | `annotations.revokeBinding` | `{ binding }` | `{ revoked }` |
 | `annotations.import` | `{ notes }` | `{ imported, skipped }` (ids kept) |
 | `annotations.pageScript` | `{}` | `{ script }`: the page helper, with `__ARGS__` for one operation |
-| `annotations.queue` | `{ id, sessionId, expectedVersion?, autoSend? }` | `Note`, shared with the session and queued (PROP-0018) |
-| `annotations.dequeue` / `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
-| `annotations.queued` | `{ sessionId }` | `{ notes }`, oldest first |
-| `annotations.createAndAct` | `{ note, action: save \| queue \| send, sessionId?, trusted? }` | `{ note, send }`; an untrusted send waits for `confirm` |
-| `annotations.compose` | `{ sessionId, ids? }` | `{ text, ids }`: one instruction for a host's own `sessions.run` |
+| `annotations.markPending` | `{ id, sessionId, expectedVersion? }` | `Note`, shared with the session and unsent (PROP-0018, PROP-0048) |
+| `annotations.confirm` | `{ id, expectedVersion? }` | `Note` |
+| `annotations.confirmAll` | `{ sessionId }` | `{ notes }`: every page-origin note of the session, confirmed |
+| `annotations.pending` | `{ sessionId }` | `{ notes }`, unsent, oldest first |
+| `annotations.clear` | `{ sessionId }` | `{ notes }`: the session's unsent notes, resolved and no longer shared with it |
+| `annotations.createAndAct` | `{ note, action: save \| send, sessionId?, trusted? }` | `{ note, send }`; with a session the note is always shared; `send` sends all unsent notes; an untrusted note waits for `confirm` |
+| `annotations.compose` | `{ sessionId, ids?, prompt? }` | `{ text, ids }`: one message for a host's own `sessions.run`, with the person's request last |
 | `annotations.delivered` | `{ ids, sessionId, runId }` | `{ notes }`, marked sent |
-| `annotations.send` | `{ sessionId, ids? }` | `{ state: sent \| busy \| host \| empty, … }` |
+| `annotations.send` | `{ sessionId, ids?, prompt? }` | `{ state: sent \| busy \| host \| empty, …; empty has unconfirmed }` |
 | `annotations.capture.attach` | `{ key, kind: web \| cdp \| bridge, endpoint?, name? }` | `{ kind, app, windows, bridge? }` |
+| `annotations.capture.discover` | `{}` | `{ apps: [{ endpoint, port, name, browser, electron, windows }] }`: apps on a loopback DevTools port |
+| `annotations.capture.launch` | `{ key, path, args? }` | `{ kind: cdp, app, windows, endpoint }`: starts the app with a DevTools port and attaches |
 | `annotations.capture.target` | `{ key }` | `{ kind, app, inspecting, windows }` |
 | `annotations.capture.selectWindow` | `{ key, window }` | `{}` |
 | `annotations.capture.open` | `{ key, url? }` | `{ url, title }` |
@@ -240,9 +270,31 @@ same service through `terminal.worktrees.*` routes, which need the control key (
 | `annotations.capture.release` | `{ key }` | `{}` |
 | `annotations.bridge.start` | `{}` | `{ port, token, scriptUrl, snippet }` |
 
-Notices: `annotations.changed { sessionId, ids }` after any queue, send or fix;
+Notices: `annotations.changed { sessionId, ids }` after any share, send or clear;
 `annotations.ready { sessionId, ids }` when a host session's waiting notes should be sent now.
 
 Errors: `version_conflict`, `not_found`, `annotation_limit`, `invalid_request`, `invalid_data`. The
 terminal reaches the same store through `terminal.annotations.*`, which shares only with its own
 session and needs the control key (`INV-TUI-4`).
+
+## Links (ADR-0047)
+
+A link a person clicks is a person's action, not a model tool call: nothing here is in
+`HARNESS_TOOLS`, so the gate, standing approvals and redaction never see it. `core/links.ts` holds
+the one allowlist both front ends use, and `openLink` is the only door into the operating system.
+
+| Method | Input | Reply |
+|---|---|---|
+| `links.open` | `{ target, base? }` | `OpenedTarget`: `{ kind: "web", url }`, `{ kind: "mail", address }`, `{ kind: "file", path }` or `{ kind: "directory", path }` |
+
+`target` is what the link says; `base` is the absolute folder a relative target is resolved
+against, and without it a relative target is refused. `linkTarget` classifies without touching the
+filesystem (`http`/`https`, `mailto`, `file`, an absolute path, or a relative path under `base`),
+and `openableTarget` then checks what it names: a regular file or a directory, never an application
+bundle, an installer, or a launchable script, and never a file with an executable bit set, because
+`xdg-open` runs one. The address is passed to `open`/`xdg-open`/`rundll32` as one argument, never
+through a shell.
+
+Errors: `link_not_openable`, with a message a person can read, and `invalid_request` when `target`
+is missing. The opener is `HarnessOptions.linkOpener`, so a host with its own native opener keeps
+the policy and replaces only the spawn.

package/docs/architecture/11-terminal.md

@@ -43,7 +43,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   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). The shared compaction checkpoint extension reintroduces the active
-  request and latest checklist into post-compaction model context until the run settles.
+  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).
@@ -77,14 +77,18 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   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. `/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
+  opens its Limits tab (PROP-0042); `/usage:accounts` opens the All accounts limits tab. These are plugin-owned namespaced routes. All-account refresh reads due providers using their own account credentials without switching the session account. The usage page is a
+  full-screen page with a top tab strip: 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.
 
+The `/plugins` Proposals tab previews the complete stored files and generated manifest before
+confirmation. Accept and reject pass the preview hash through the control-key-protected socket;
+the proposal service checks it again. Acceptance leaves the package switched off and untrusted.
+
 ## Invariants
 
 - **INV-TUI-1** OpenTUI is the only terminal frontend. Pi's `InteractiveMode` is never constructed
@@ -96,7 +100,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   their existing layers. The terminal adds no second path for any of them; its runs are written
   through the controller and the run store.
 - **INV-TUI-4** Changes made through the session socket (`plugins.attach|detach|trust|untrust|configure`,
-  `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
+  `plugins.proposals.*`, `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
   `terminal.annotations.*`, `terminal.sideQuestions.*`) require the control key the trusted terminal process claimed once
   (`control.claim`). The session's shell can read the session token, so the token alone is never
   enough.
@@ -144,6 +148,13 @@ The native `session_info_changed` event invalidates the frontend's cached snapsh
 refreshes the working line. Both the active and retained completion line append
 ` – <name>` after duration and token rate, for example
 `Working (2m, 50 tok/s) – Add web browser integrations`. Unnamed sessions omit the suffix.
+A substantive first turn also receives a provisional name through the terminal policy; a refused
+or failed name leaves the session unnamed.
+
+Each user turn appends a hidden `xingular-session-state` custom message with the current name,
+this run's empty todo, and the previous run's todo as context. The message is request-only and
+never changes the compiled stable pack. A first turn is marked as such; later turns say the todo
+list resets for each run.
 Names use the existing terminal text sanitization, remain outside the verb shimmer, and
 truncate at the right edge. Manual `/name` and existing long names remain supported.
 
@@ -156,19 +167,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`, `/hub` and `/usage:`, 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
@@ -243,39 +264,56 @@ 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.
 
-## Web annotations commands (PROP-0017)
+## Web annotations commands (PROP-0017, PROP-0018, PROP-0048)
 
-`/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`.
+`/annotate:` opens the annotate page, a full-screen page with two tabs. `/annotate:notes` opens it on
+**All annotations**: every annotation in the data root, with search, and reveal, edit, resolve or
+reopen, share with this session or stop sharing, and delete. An annotation is private until shared;
+this session's agent then reads it with `page_notes_list` and `page_notes_read`.
 
-The annotate pane (PROP-0018) is a full-screen page beside the window being inspected.
+The **Annotate** tab is the panel beside the window being inspected.
 
 - **Ways to start it:**
-  - `/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.
+  - `/annotate: [url]`: the capture browser (its own window and profile, separate from the agent's
+    browser). With no address, the page returns to the window that is still open, with its URL and
+    the inspector on, and asks for one in its own inline field only when no window is open.
+  - `/annotate: --app [port | address] [name]`: an app's own windows over its DevTools port. With no
+    port, the page lists the apps answering on one (`annotations.capture.discover`).
+  - `/annotate: --bridge [name]`: app windows that load the page bridge script, which the page shows.
+- **The inspector** (`i`) outlines components on hover. A click or a text drag opens a popover in
+  the page with **Annotate** and **Annotate & send**. Every annotation is shared with this session
+  at once.
+- **Groups:** Unsent (n) and Sent, for this session.
+- **Other keys:** `s` sends every unsent annotation as one run of this session, confirming the
+  page-origin ones once first; `o` types a page address; `a` lists apps with a DevTools port, with
+  *Start an app with a DevTools port*, *Type a DevTools port*, *Use the page bridge*; `t` picks a
+  window; `Tab` switches tab. A key pressed while the page is busy gets a notice, never nothing.
+- **Commands:** `/annotate:submit <request>` sends the unsent annotations with the request after
+  them; `/annotate:clear` resolves the unsent ones and stops sharing them.
+- **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|confirm|confirmAll|send|clear|discover|launch`
+  act only on this terminal's session and need the control key.
+
+A page that opens a dialog as it starts gets it above itself: `PageOverlay` starts its page when the
+host reports the overlay mounted.
+
+## 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: 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
+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`
@@ -288,13 +326,13 @@ boundary at all; it is not persisted, so the next launch without it restores the
 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), counts from the child's own checklist, the pinned account label, effective model and
+(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
-checklist item text never enter the monitor. The latest completed tool name remains visible across
+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.
 
@@ -302,15 +340,26 @@ The live rows sit under the status line, after one blank row, with no heading. E
 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
+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 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.
+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

@@ -23,6 +23,7 @@ index.
   legacy/              an earlier Wiki's data, moved once   (08)
   registry/            skills/, prompts/, rules/: the component library   (03)
   plugins/<name>/      packages kept with the data   (06)
+  plugin-proposals/<id>.json   pending and decided proposal text, hash and status; owned by plugins/proposals.ts   (06)
   trash/plugins/       removed packages   (06)
   hub/                 installed documents and provenance   (09)
   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)

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

@@ -48,19 +48,21 @@ it. A tool returns only notes a person shared with the calling session or agent;
 and element names are marked untrusted. Capture happens in a visible capture browser in the
 terminal, or in a host's own web view running the same page helper (`annotations.pageScript`).
 
-**Inspector, queue and app targets (PROP-0018).**
+**Inspector, sending and app targets (PROP-0018, PROP-0048).**
 
-- **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with three choices: save, queue for the agent, or send now.
-  - 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.
+- **Inspector.** In the page helper's inspector, hovering outlines a component and a click (or a drag over text) opens a comment popover inside the page, with two choices: Annotate and Annotate & send.
+  - With a session, every note is shared with it at once and is pending (unsent) until sent.
+  - `annotations/delivery.ts` sends all of a session's pending notes as one message, with the
+    person's request last when given, and sends notes held back while the session was busy when its
+    run ends, trying again while the session still answers busy.
+  - The page-note tools are read-only. Only the person resolves a note.
 - **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.
+  - **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. `discover` probes loopback ports 9222–9230 and ports used before (a Node inspector is skipped); `launchApp` starts a program (the one inside a macOS `.app`) with `--remote-debugging-port` on a free loopback port and attaches. A started app keeps running.
   - **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 |
@@ -29,6 +29,9 @@ terminal command or page, a host screen.
   tool that passes the gate (page 07). Both front ends use the same methods; neither has a private
   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.

package/docs/architecture/README.md

@@ -1,10 +1,11 @@
 # Harness architecture specification
 
-**Status:** binding. **As of:** 2026-10-26, 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,29 +87,29 @@ 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 |
 |---|---|---|
 | D-1 | `AGENTS.md` (before this spec), `INV-RUN-6` | The old rule said only `sessions/runStore.ts` writes `runs/<id>/`. In code, four other harness modules also write side files there: `prompt/compile.ts` (`context.json`), `sessions/sessions.ts` (`caller.json`), `capabilities/runSnapshot.ts` (`capabilities.json`), `mcp/service.ts` (`mcp-context.json`). The spec states the rule the code keeps (see `INV-RUN-6`); whether to route all of them through `runStore.ts` is open. |
-| D-2 | `README.md` "Plugins" | Describes a `plugin_propose` tool and an Inbox for proposed plugins. No such tool exists in `src/`. |
+| D-2 | Plugin proposal review surfaces | `plugin_propose` and hash-bound proposal APIs now exist; a terminal review UI is pending and no App review UI is claimed. See [PAR-017](../parity.md#gaps). |
 | D-3 | `README.md` "External curation" | Describes `externalMaintenance`, `vaultAccess`, `MAINTENANCE_PLUGIN`, `maintenance.*` methods and tools. None exist in `src/`. |
 | D-4 | `INV-BND-2` | Several names carry an application's name: the context message type `xingular-context`, the approval extension `xagent-approvals`, the MCP client name `xagent`, and the terminal commands `xagent-wiki` / `xagent-mcp`. The default product name `Xingular Agent` is allowed; these are not. |
 | D-5 | `INV-BND-2` | `RunRecord` carries `worktreeId` and `handoffId`, which are application concepts. They are stored and returned, never read, and are documented as the application's fields. Since PROP-0016 (2026-10-23) `worktreeId` has Harness meaning when it names a registered worktree; only `handoffId` remains an application field. |
@@ -124,4 +125,5 @@ proposal, or a correction to the other document).
 | 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-19 | Provider limits layout | Page 09 describes a centered Limits dialog; page 11 and `src/terminal/tui/pages/usagePage.ts` describe and implement a full-screen page. |
 | 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-0018-annotation-queue-and-app-targets.md

@@ -1,14 +1,18 @@
 ---
 id: PROP-0018
 title: Inspector-style page notes, a fix queue to the agent, and app windows as capture targets
-status: Implemented
+status: Implemented; queue, three-button popover and page_notes_mark_fixed superseded by PROP-0048
 created: 2026-10-23
-updated: 2026-10-23
+updated: 2026-10-27
 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]
 ---
 
 # PROP-0018: Inspector, fix queue and app targets for page notes
 
+> The fix queue, its three-button popover and `page_notes_mark_fixed` were replaced by
+> [PROP-0048](PROP-0048-simple-annotate.md): a note is pending or sent, and the popover has Annotate
+> and Annotate & send.
+
 Requested by the owner on 2026-10-23. They chose these four things:
 - the popover's three choices: Save, Queue, Send now
 - the popover drawn inside the page