@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.4

package/docs/architecture/02-sessions-and-runs.md

@@ -97,6 +97,15 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
 - **Subagents.** `spawn_subagent` / `wait_subagents` for the model; `subagents.spawn`, `wait`,
   `results` for the host (`sessions.spawnSubagent` is a compatibility alias). Child runs have
   `relation: 'subagent'` and `parentRunId`. Nesting defaults to 1, at most 3 (`subagentDepth`).
+  A run also starts only a few children: by default at most four distinct child conversations, at
+  most two `worker`, three `explorer`, one of any other named profile and one with no profile. The
+  parent's `subagents` option overrides them (`maxChildren`, `maxByProfile`, `maxOther`,
+  `maxUnprofiled`), clamped to 0–50. The count covers this run and the runs it was continued from
+  (`resumedFromRunId`), so a work-slice continuation keeps the budget; it counts distinct
+  conversations, so continuing a stopped child uses no new slot, while a child whose startup
+  failed still counts. A concurrent spawn reserves its slot before it launches. A refused spawn is
+  an `invalid_request` whose message tells the model to do the work itself; no child run is
+  created.
   The child's record carries `title`, the short name the parent gave it (PROP-0030).
   `spawn_subagent { continue: <runId> }` (`subagents.spawn { continue }`) continues a child that
   stopped before finishing as a new child run with `continueFrom`. It reopens the first link's
@@ -132,7 +141,29 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   steps and verification. A small fix stays concise without omitting its
   outcome or check; cross-cutting work uses ordered steps. It uses alternatives only when requested
   or materially useful; contextual `uiSketch` questions clarify real choices.
-  The reply ends with one `<proposed_plan>` block.
+  **Outcome contract (ADR-0058, superseding the clarification portion of ADR-0057).** Classify a
+  new final reply as exactly one of `plan_ready`, `blocked`, or `invalid`. `plan_ready` uses the
+  existing complete `<proposed_plan>` block and is the only outcome that offers a plan card and
+  Implement. When a required user decision cannot be obtained because `ask_user` is unavailable,
+  `blocked` uses a nonempty `<plan_blocked>` block to report the blocker without asking a free-text
+  question or inventing the decision; it
+  is not a plan and never offers Implement. New final replies must not use `<plan_clarification>`
+  or free-text questions as a clarification channel. Missing, incomplete, conflicting or otherwise
+  malformed outcomes are `invalid`, not a guessed plan. When clarification is needed and `ask_user`
+  is available, it blocks the active run for the answer, then that same run continues research and
+  planning.
+
+  Server and terminal use the same outcome classification and one bounded, hidden repair turn
+  in the same eligible attended top-level plan run, only for `invalid`. The repair requests a valid
+  outcome without inventing decisions or changing the substance; it may call `ask_user` when
+  available, blocking the active run for the answer, and may return either valid outcome.
+  It is not a new user request, does not bypass the plan gate, and is never attempted for a
+  plan-research child, command, probe, improver, reflection, other unattended run, interruption,
+  error or work-slice termination. A second invalid result ends repair: retain the original reply,
+  complete the run with a warning and no Implement choice. Preserve the existing plan tag, card,
+  run events, tool permissions and cached prompt boundary; old transcripts, including legacy
+  clarification blocks and untagged replies, remain intact and visible, not silently promoted to
+  plans. Do not require clients to understand a new event type.
 - **Compaction checkpoint** (PROP-0033, ADR-0032). After compaction, an active run's model context
   receives a bounded, ephemeral checkpoint with the current user request and the latest validated
   todo list or applicable plan instructions, when either is available to restore. It is re-added to
@@ -274,28 +305,28 @@ is approved but remains in progress; no completed cross-surface catalog is impli
   checkpoint and leaves handoff calls callable; otherwise a plan-research child must stop with a
   concise partial research report, and the runner derives a checkpoint from run evidence. A
   non-handoff tool call after the refusal ends the reply. A budget-ended reply is `interrupted` with
-  terminal reason `slice_complete`; a reply ended by a stall guard is `stalled`.
-  The targeted stall guard identifies calls by name and every argument; three identical calls cause
-  one refusal, and a repeated trigger ends the reply. A Bash check that fails twice is a trigger. The
-  guard counts only successful native `edit`/`write` results (`isError === false`) with a path toward
-  the four-edit per-path churn limit; the next edit is refused, and a repeated trigger ends the
-  reply. Failed or blocked edits do not count. A successful edit/write clears failed-check counts,
-  identical Bash-check repeat counts and the pending nudge, but leaves edit counts and other
-  repeated-call counts intact. A passing check clears edit counts. The general 25-call file/check
-  no-progress trigger is removed. `todo_write` is bookkeeping: it is exempt from repeated-call
-  detection and does not reset loop state, but counts toward the tool-call budget. Third-compaction
-  thrash detection remains. Plan-research children without `checkpoint_write` receive the configured
-  bound without a new capability and do not auto-continue. A new run continues it only up to the
-  policy's slice cap, only after a slice that changed a file, passed a check or recorded a finished
-  item, and never after a checkpoint that is `blocked`. A run may turn the guard off with
-  `workSlice.enabled: false`, and a launch may set `XINGULAR_WORK_SLICE=off` for every run in that
-  process; with it off a reply has no boundary — no checkpoint, no continuation, no stall notes — and
-  ends only when the model stops or a person interrupts.
+  terminal reason `slice_complete` (ADR-0053).
+  No call is refused for repeating: identical calls, a Bash check that keeps failing and repeated
+  `edit`/`write` results on one path are allowed as often as the work needs, because a distinct read
+  or another edit is not evidence of a loop. `todo_write` counts toward the tool-call budget and is
+  otherwise unconstrained. Third-compaction thrash detection remains: three context compactions in
+  one reply end it with the same handoff request. Plan-research children without `checkpoint_write`
+  receive the configured bound without a new capability and do not auto-continue. A new run
+  continues it only up to the policy's slice cap, only after a slice that changed a file, passed a
+  check or recorded a finished item, and never after a checkpoint that is `blocked`. A run may turn
+  the guard off with `workSlice.enabled: false`, and a launch may set `XINGULAR_WORK_SLICE=off` for
+  every run in that process; with it off a reply has no boundary — no checkpoint, no continuation —
+  and ends only when the model stops or a person interrupts.
 - **INV-RUN-14** A run event stream carries `checkpoint` (the handoff `checkpoint_write` records or
   the harness derives from the run's own evidence when the model wrote none) and `heartbeat`
-  (steps, elapsed time, last tool, compactions, slice, and the call budget). A heartbeat older than
-  five minutes while the owner process lives marks the run `interrupted` with reason `stalled`; a
-  run that never emitted one keeps the 30-minute silence rule. The watchdog never restarts work.
+  (steps, elapsed time, last tool, compactions, slice, and the call budget). Every live reply emits a
+  heartbeat every 30 seconds, terminal replies included. A heartbeat older than five minutes while
+  the owner process lives marks the run `interrupted` with reason `stalled`; a run that never emitted
+  one keeps the 30-minute silence rule. A reply whose heartbeat keeps arriving but which produces no
+  other event for fifteen minutes is a wedged turn, not a busy one: the terminal ends it through the
+  native abort and records `interrupted` with reason `stalled`, and grants a reply whose oldest
+  running tool has run for thirty minutes the same ending. An unanswered approval or question is
+  never cut short. The watchdog never restarts work (ADR-0054).
 - **INV-RUN-12** A post-compaction checkpoint is a bounded context projection of the active request,
   the latest validated todo list and applicable plan instructions. It is compiled by
   `prompt/compile.ts`, supplied only to model requests in the active run, and never persists hidden
@@ -322,7 +353,9 @@ Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (super
 [ADR-0023](../decisions/ADR-0023-contextual-side-question-runs.md),
 [ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md),
 [ADR-0033](../decisions/ADR-0033-plan-mode-research-delegation.md),
-[ADR-0039](../decisions/ADR-0039-progress-aware-stall-guards.md).
+[ADR-0039](../decisions/ADR-0039-progress-aware-stall-guards.md),
+[ADR-0053](../decisions/ADR-0053-no-repeated-work-guard.md),
+[ADR-0054](../decisions/ADR-0054-terminal-reply-heartbeat-and-stall.md).
 
 ## Native session names (PROP-0010)
 

package/docs/architecture/04-prompt.md

@@ -14,6 +14,7 @@ keeps provider caching effective across turns.
 |---|---|
 | `compile(env, caller, launch, variant)` → `ContextPack` | Builds the ordered, budgeted sections, including the configured data-root path in native file guidance. |
 | `render(env, pack)` → `string` | One string for a session that takes a single prompt. |
+| `renderSized(env, pack)` → `{ text, sizes, framing }` | The same string, plus the characters each section occupied and the framing around them. |
 | `sessionLaunch(env, caller, launch, historyFile, variant)` → `{ system, update, pack }` | SDK sessions: stable prefix plus an update with only the dynamic sections that changed since the last delivered snapshot. |
 | `deliveredSnapshot(sessionFile)` | Reads the last delivered snapshot on the active history branch; a compaction forces a fresh one. |
 | `renderCompactionCheckpoint` | Compiles a bounded current-request, todo list and plan-state message for post-compaction model requests. |
@@ -26,9 +27,16 @@ A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
 `body`, `sources`, `budget`, `size`, `cut`), `toolGroups`, `harness` (scope and fingerprint),
 `profile`, `compiledAt` and `delivery` (`systemSectionIds`, `updatedSectionIds`).
 
+`delivery.sizes` records what each delivered section occupied when it was rendered — `system` and
+`update` maps by section id, plus the framing characters that belong to no section (the product
+heading, the section headings, the context-update guidance). It is what lets a surface attribute the
+context window without re-parsing a prompt whose bodies may contain their own headings. A pack
+recorded before the compiler measured them has no `sizes`, and a reader then falls back to
+`Section.size` and says the split is approximate.
+
 ## Section order
 
-`SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `sessionState` 30, `guardrails` 40, `memory` 45, `references` 50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
+`SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `sessionState` 30, `guardrails` 40, `memory` 45, `references` 50, `requiredSkills` 52, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
 sit among them by their `order`; plan mode uses `plan` at 25. Ties keep insertion order.
 When a run may spawn, the dynamic `subagents` section lists every profile it can start (built-in,
 global, project and variant c5 names) and replaces the variant's own list (PROP-0029). Normal-mode
@@ -49,6 +57,15 @@ in the frozen set: the name line appears only with `session_name`, and the todo
 `sessionLaunch` and the changed-section rule; the terminal appends the same text as a request-time
 custom message.
 
+`required-skills` is a built-in dynamic section at order 52 when `Launch.requiredSkills` names any
+skill. Named in a message as `$name`, a skill is required for that request: the compiler reads its
+`SKILL.md` from the pinned variant (the built-in `plugin-authoring` skill fills in when the variant
+has none) through `readSkillFile`, and the section carries the skill's text and the directive to
+follow it. It is bounded like `references`, names an unavailable skill honestly, and changes no tool
+or permission. Structured sessions deliver it through `sessionLaunch`; the terminal builds the same
+text with `requiredSkillsText` from Pi's loaded skills and appends it as a hidden request-time custom
+message. The section belongs to the request, so an identical one is delivered again.
+
 The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
 `env.productName` (default `Xingular Agent`). `Launch.standard: { cwd, project?: { name } | null }` requests shared role and working-folder
 sections from `prompt/standard.ts`; the compiler supplies common connections, file and annotation
@@ -83,10 +100,12 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
                                                                               type xingular-context
 ```
 
-- Dynamic sections are the built-in `references` and `wiki`, plus every application section with
+- Dynamic sections are the built-in `references`, `required-skills` and `wiki`, plus every application section with
   `dynamic: true`.
+- The rendered sizes of both halves are recorded with the pack (`delivery.sizes`), so the context a run
+  was given can be attributed after the fact without replaying the compiler.
 - An update lists only the dynamic sections that changed, and announces a withdrawn one.
-  `references` is always resent when present, because it belongs to the current request.
+  `references` and `required-skills` are always resent when present, because they belong to the current request.
 - After successful compaction, the foundation checkpoint extension detects the compacted context and
   uses `renderCompactionCheckpoint` to append one hidden, ephemeral context message to each model
   request while the active run continues, when a todo list or applicable plan instructions exist.
@@ -121,7 +140,7 @@ file SecretStore with a host Keychain. See [parity](../parity.md).
   instructions. SDK sessions use `sessionLaunch`; terminal sessions use `compile` + `render`.
 - **INV-PRM-2** The system prompt holds only stable text: identity, role, the variant's sections, the
   harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it.
-- **INV-PRM-3** `session-state`, `references`, `wiki`, and every section the application marks
+- **INV-PRM-3** `session-state`, `references`, `required-skills`, `wiki`, and every section the application marks
   `dynamic` are delivered as context updates in native history, never in the system prompt.
 - **INV-PRM-4** An update carries only changed dynamic sections, so an unchanged turn appends
   nothing. A compaction on the active branch forces the full snapshot again.

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

@@ -17,7 +17,7 @@ person without letting remembered per-tool grants widen that boundary.
 | `harnessTools` | `tools/harnessTools.ts` | The definitions as `ToolSpec`s for one session. |
 | `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
 | `todoTool` (`todo_write`) | `tools/todo.ts` | Writes the run's whole todo list as a `todo.updated` event (PROP-0006, renamed by PROP-0045). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `todo` telemetry call. The prompt's Progress group asks the model to call it before the first other tool call when work has several steps, keep it current, and write one final update before replying; unfinished work is not automatically marked complete. The pre-rename `checklist.updated` event is still read, never written. |
-| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
+| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. The description states the run's budget, and `Subagents.spawn` refuses a child past its per-profile or total limit (ADR-0052). |
 | `annotationsPart` (`page_notes_list`, `page_notes_read`) | `annotations/part.ts` | Read-only world tools over the page notes a person shared with the session or agent (PROP-0017, PROP-0048). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
@@ -130,7 +130,9 @@ Standing approvals (`approvals.json`): an always-approve switch per key (`chat`,
 `harness`), tools allowed across the state directory per key, and targets remembered per
 session. `humanOnly` calls are never answered by remembered tools, and by the switch only when
 `allowGlobalApproval`. `ApprovalFacts.unattended` disables standing answers; `readOnly` disables
-the switch and global tools.
+the switch and global tools. A person answering through a phone paired by `/remote-control` answers
+the same terminal request through the same controller call, with its complete action text shown
+beside the choices (INV-RC-3, INV-RC-4).
 
 ## Invariants
 

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

@@ -88,6 +88,21 @@ operations, not an assertion that a host has built a review UI. Protected termin
 require the terminal control key. The model tool can create only. Validation and trust details are
 on page 06.
 
+## Context attribution (PROP-0049)
+
+| Method | Input | Reply |
+|---|---|---|
+| `context.attribution` | `{ runId }` | `ContextAttribution`: the model and window, the measured `used` and its `share`, `source` (`measured` or `estimate`), the request index, the compaction reserve and `free`, one row per contributor (`tokens`, share, owner group, `always`, `estimated`, budget, cut, tool breakdown, note), `history` of the window at each request, `compactions`, `onDemand` variant components, group totals and the reconciliation `note` |
+| `terminal.context` | `{ section? }` | `{ attribution, text }` for this terminal's latest run: the same attribution, and one row's text when `section` names it |
+
+The rows are read from what the run recorded — `runs/<id>/context.json` for the sections and their
+rendered sizes, `context.snapshot` for the prompt, the update and every tool schema, `usage.updated`
+for the provider's own figure. Nothing is written. A row is estimated at four characters per token;
+the conversation row is the measured total less the rows above it, so the rows add up to the figure
+the provider reported rather than to an estimate of their own. When the pack carries no rendered
+sizes, or the snapshot was truncated, the reply says the split is approximate. `terminal.context`
+resolves the run from the terminal session, never from the request.
+
 ## Usage (PROP-0042)
 
 | Method | Input | Reply |
@@ -209,6 +224,15 @@ from preparation, never from the request.
 | `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 |
 
+Remote control (page 15, ADR-0056) adds these protected controls:
+
+| Method | Input | Reply |
+|---|---|---|
+| `terminal.remoteControl.start` | `{ interface?: 'auto' \| 'tailscale' \| 'lan' }` | `RemoteStatus`; listening on one Tailscale or private address |
+| `terminal.remoteControl.stop` \| `rotate` | `{}` | `RemoteStatus`; stopped, or a new link with every device unpaired |
+| `terminal.remoteControl.confirm` | `{ requestId, allow }` | `RemoteStatus`; the person's answer to a pair request |
+| `terminal.remoteControl.status` \| `status.wait` | `{}` / `{ revision }` | `RemoteStatus`; the wait returns at once for a changed revision, otherwise within 20 seconds |
+
 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

package/docs/architecture/11-terminal.md

@@ -46,12 +46,20 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   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).
+  interruption. The question blocks until answered, then planning continues in the same run. There
+  is no terminal-only question alias (PROP-0040).
+- The approved plan outcome contract on page 02 applies equally to the terminal and server:
+  only `plan_ready` offers a plan card and Implement; `blocked` reports unavailable required input
+  without Implement; `invalid` gets at most one shared bounded repair and, if still invalid, a
+  warning and the retained original text. New final replies do not ask free-text questions or use
+  `<plan_clarification>`: clarification uses `ask_user`, which blocks the active run. Repair at
+  Pi's settlement boundary is in the same run and may call `ask_user`. Existing `<proposed_plan>`
+  cards and old transcripts, including clarification blocks, remain intact; see ADR-0058.
 - A plan request keeps `bash` in its active set; each call runs in the sandbox's read-only scope
   (PROP-0043). A user `!` command submitted during a plan request waits as a separate turn; it
   cannot run inside the plan's read-only request.
-- The terminal message-delivery contract is Enter to send or steer an active reply, and
-  Cmd/Ctrl/Alt+Enter to queue a follow-up. Pending steering, follow-up and deferred plan/Bash
+- The terminal message-delivery contract is Enter to send or queue a follow-up, and
+  Cmd/Ctrl/Alt+Enter to steer an active reply. Pending steering, follow-up and deferred plan/Bash
   inputs are projected above the working line from Pi's queues and the deferred barrier. Pi's
   projection may briefly include an item already taken for delivery. A queued plan or Bash command
   runs separately after the active reply, and later inputs cannot bypass it through Pi's native
@@ -65,12 +73,22 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   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`.
+- `$name` is a skill invocation at any word start in the composer: the palette opens at the caret
+  and inserts the chosen skill there, keeping the rest of the draft, and every `$name` naming a
+  loaded skill is required for that request. The terminal builds the request-scoped text with
+  `requiredSkillsText` from Pi's loaded skills and appends it as a hidden `xingular-required-skills`
+  custom message. A required skill changes no tool or permission, and the person's message reaches
+  the model unchanged.
   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.
+- `/remote-control` (`/rc`) lets a phone or iPad continue this session: a page with the pairing
+  link and its QR code, paired devices, and the person's answer to a pair request; `rc` / `rc ●` in
+  the status bar while it is on. `xagent --remote-control` (`--rc`) turns it on at start. The
+  binding rules are page 15.
 - `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` opens the worktree page; selecting
@@ -83,7 +101,12 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   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. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
+  entry. `/context` opens the context attribution page: what the latest request was made of, one row
+  per contributor with its tokens and share of the window, grouped by owner (foundation, variant,
+  application, conversation) with the compaction reserve and free space below it. `/context growth`
+  opens its second tab, the window at each measured request with its compaction markers. The page
+  reads `terminal.context`, never computes a figure of its own, and says `?` where nothing measured a
+  window. `/usage:` and `/usage:analysis` open the usage page's Analysis tab, and `/usage:limit`
   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`
@@ -108,9 +131,14 @@ the proposal service checks it again. Acceptance leaves the package switched off
   through the controller and the run store.
 - **INV-TUI-4** Changes made through the session socket (`plugins.attach|detach|trust|untrust|configure`,
   `plugins.proposals.*`, `accounts.*`, Hub installs, `terminal.browser.*`, `terminal.worktrees.*`,
-  `terminal.annotations.*`, `terminal.sideQuestions.*`) require the control key the trusted terminal process claimed once
+  `terminal.annotations.*`, `terminal.sideQuestions.*`, `terminal.remoteControl.*`) 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.
+  enough. A phone paired through `/remote-control` is the one other party that answers decisions;
+  only the control-key holder can start remote control or allow a device (INV-RC-3, INV-RC-7).
+- The terminal watches decisions through the control-key-protected `terminal.pending.wait` revision
+  snapshot. It returns immediately for a changed revision and otherwise waits at most 20 seconds;
+  additions, removals and disposal wake waiters. `terminal.pending` remains available. The terminal
+  reconnects and resynchronizes after errors, and cancels its outstanding request on shutdown.
 - **INV-TUI-5** Every resource reload revalidates the original trusted selection; changed or
   revoked code needs review and a fresh terminal.
 - **INV-TUI-6** `sessions.run` stays the embedding and unattended path. The terminal keeps a
@@ -194,7 +222,7 @@ The browser uses the full terminal with persistent section tabs (PROP-0014); wid
 inventory beside details, actions and content, while compact screens keep inline details under
 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
+command pages remain centered except `/settings`, `/accounts`, `/plugins`, `/hub`, `/context` 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
@@ -323,11 +351,25 @@ extension registers the shared tool and sends it as `checkpoint` telemetry, whic
 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
+already does. The run record says `interrupted` with terminal reason `slice_complete`, 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.
 
+## Liveness and a reply that stops working (INV-RUN-14, ADR-0054)
+
+While a reply is live the extension sends `heartbeat` telemetry every 30 seconds, carrying the work
+slice counters it already keeps (steps, elapsed time, last tool, compactions, slice and the call
+budget); the controller records it as `heartbeat` on the active run, so the run sweep settles a
+terminal reply that stopped reporting by the same five-minute rule as a structured one.
+
+A heartbeat proves the turn is alive, not that it is working. A reply that produces no event other
+than a heartbeat for fifteen minutes — the state a model request that never returns leaves it in —
+is ended: the controller queues the same `interrupt` command the person's Esc queues, the native turn
+aborts, and the run records `interrupted` with reason `stalled`. A reply whose oldest running tool
+has run for thirty minutes ends the same way, and a reply waiting on an approval or question is never
+cut short.
+
 ## Subagent activity monitor
 
 During an active parent run, the terminal polls a private read-only monitor once per second. It

package/docs/architecture/12-storage.md

@@ -27,8 +27,8 @@ index.
   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)
-  # `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).
+  # `checkpoint` and `heartbeat` are run events in the same events.jsonl; every live reply emits one
+  # heartbeat per 30 seconds (about 60 KB an hour) and no side file (PROP-0041, ADR-0054).
   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, recall, usage ledger)   (08, PROP-0042)
@@ -51,6 +51,9 @@ index.
   harness.log          standalone terminal diagnostics
 ```
 
+`/remote-control` (page 15) stores nothing here: its pairing and device keys live in memory and end
+with the session (INV-RC-2).
+
 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

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

@@ -18,14 +18,28 @@ 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.
 
+## Approved-window screenshot contract
+
+`computer/screenshot.ts` defines an opt-in host provider adapter for `computer_screenshot`.
+The backend must capture exactly one currently approved window, excluding the desktop, other windows
+and overlays even when they overlap, and refuse if it cannot guarantee that scope. It must not
+fall back to a display capture. Coordinates supplied to a host's related interaction tools, if any,
+are relative to the returned image pixels. The tool goes through the ordinary provider and gate,
+returns an image to the model, and is not plan-mode safe by default. Image content is untrusted.
+The contract itself does not prove that a host implements these requirements. In particular, the
+existing macOS host capture has not yet adopted this contract and captures a display; it must not
+be represented as approved-window-only capture. The standalone terminal has no capture backend.
+
+
 ## 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.
+supports navigation, tab management, visible-text reads, page screenshots and page-level scrolling
+without a ref. It does not support accessibility snapshots, snapshot refs or ref-based
+click/type/select/scroll/screenshot, browser waits or keyboard presses. Native page screenshot
+implementation and authorization checks are present, but live host capture acceptance remains open.
 
 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

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

@@ -97,14 +97,18 @@ terminal command or page, a host screen.
   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).
+  lacks accessibility snapshots and snapshot-ref interactions, waits and keyboard input; it supports
+  page screenshots without refs in source, with live acceptance pending. 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.
+- Remote control (page 15) is a third Harness-owned surface of a terminal session: a phone page the
+  harness serves. It is not a host and owns no capability. A paired device acts through the same
+  `Terminals` and controller paths as the terminal, and reaches no command, shell, link, plugin or
+  account control.
 - 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.

package/docs/architecture/15-remote-control.md

@@ -0,0 +1,118 @@
+# 15 Remote control
+
+## Purpose
+
+Remote control lets a person continue a live terminal session from a phone or iPad. The session
+keeps running in `xagent` on the computer. A paired device sends messages, watches the reply as it
+streams, stops it, and answers approvals and questions. It works without a cloud relay: the
+harness serves a small web page on the computer's Tailscale address, or its private Wi-Fi or LAN
+address, and the device opens it from a QR code. Remote control ends when the terminal session
+ends ([ADR-0056](../decisions/ADR-0056-remote-control.md)).
+
+A paired device is a second person at the terminal. It reaches the same controller and `Terminals`
+methods the terminal uses and nothing else, so remote control adds a surface, not a capability
+path.
+
+## Components
+
+| Type / module | Role |
+|---|---|
+| `remote/addresses.ts` | Bind candidates from `networkInterfaces()`: Tailscale (100.64.0.0/10, fd7a:115c:a1e0::/48) first, then RFC 1918 IPv4. `pickRemoteAddress(auto\|tailscale\|lan)`. |
+| `remote/seal.ts` | Sealed frames: NaCl `secretbox` (XSalsa20-Poly1305, `tweetnacl`) with a random 24-byte nonce; a counter inside each frame, checked by `ReplayGuard` (a 256-counter window). |
+| `remote/pairing.ts` | `Pairing`: the pairing link (id and key), one waiting pair request, paired devices (`RemoteDevice`), limits, rotation. |
+| `remote/server.ts` | `listenRemote`: `node:http` on one address; the page assets, `POST /rc/hello`, `POST /rc/call`, `GET /rc/events` (server-sent events). Host and Origin checks, body caps, no-store and CSP headers. |
+| `remote/service.ts` | `RemoteControl` for one terminal session over a `RemoteSessionPort`: start, stop, rotate, confirm, status and `waitStatus`; projects run events and decisions for the phone. |
+| `remote/webClient.ts` | The phone page: HTML, CSS and script, served as is. |
+| `terminal/tui/pages/remoteControlPage.ts`, `terminal/tui/qr.ts` | The `/remote-control` page and its half-block QR code (`uqr`). |
+
+```text
+Phone browser ── http://<tailscale or LAN address>:<port> ──> RemoteControl (xagent parent)
+   sealed hello / calls / events                                  │ RemoteSessionPort
+                                                                   ├─ Terminals.send
+                                                                   ├─ TerminalController.control (interrupt, approve, answer, pending.wait)
+                                                                   └─ RunRegistry.listen (this session's own runs)
+```
+
+## Contracts
+
+- **Terminal surface.** `/remote-control` (alias `/rc`) starts remote control for the current
+  session and opens its page: the link, the QR code (space hides it), the address kind, paired
+  devices, and a waiting pair request. Keys: `c` copy the link, `n` a new link (every device is
+  unpaired), `t` switch between Tailscale and Wi-Fi when both exist, `x` stop, `a`/`d` allow or
+  deny a request. Esc closes the page; remote control keeps running. `/rc off` stops it;
+  `/rc tailscale` and `/rc lan` choose the address kind. `xagent --remote-control` (`--rc`) runs
+  `/remote-control` as the terminal opens. The status bar shows `rc` while it is on and `rc ●`
+  while a device is connected. When the page is closed, the terminal asks about a pair request
+  in a confirmation dialog.
+- **Methods.** `terminal.remoteControl.start { interface? }`, `.stop`, `.rotate`,
+  `.confirm { requestId, allow }`, `.status`, `.status.wait { revision }` (returns at once for a
+  changed revision, otherwise within 20 seconds). Each returns a `RemoteStatus`
+  `{ running, revision, url, kind, kinds, devices, request, warning }`. All of them go through the
+  session socket's control key (INV-TUI-4).
+- **Pairing.** The link is `http://<address>:<port>/#<pairingId>.<key>`. A browser never sends the
+  fragment. The phone says hello with a frame sealed by the link key. The request waits up to 50
+  seconds for the person at the terminal to allow it; the reply, sealed by the link key, carries
+  the device's id and its own key. A link pairs one device and is then replaced, so the QR code on
+  screen pairs the next one. At most 3 devices; at most 10 hello attempts a minute; 20 failed
+  attempts replace the link and show a warning.
+- **Calls.** `POST /rc/call { d: deviceId, f: frame }`. The frame holds `{ id, method, params }`;
+  the reply frame holds `{ id, result }` or `{ id, error }`. Methods: `snapshot` (title, the
+  session's own runs as phone events, pending decisions, state), `send { text }`, `interrupt`,
+  `approve { requestId, decision, alwaysAllow? }`, `answer { requestId, answer }`,
+  `answers { batchId, answers }`, `unpair`. Anything else is refused.
+- **Events.** `GET /rc/events?d=&f=` opens a stream of sealed frames:
+  `{ type: 'event', event }`, `{ type: 'pending', requests }`, `{ type: 'ended' }`,
+  `{ type: 'unpaired' }`. A phone event is one of `delta`, `message`, `tool`, `run`, `todo`, with
+  only the fields the page shows: no tool input or output, no context snapshot, no native evidence.
+  An approval's `action` text is sent whole.
+- **Streaming.** The terminal extension batches assistant text deltas (150 ms) into a `delta`
+  telemetry event; the controller records it as `message.delta` under the id the completed
+  `message` then carries. It is not host telemetry.
+
+## Invariants
+
+- **INV-RC-1** Remote control listens on exactly one Tailscale or private LAN address, never on a
+  public address or on all interfaces. With no such address it refuses with the reason. (Tests
+  inject a loopback address through `RemoteControlOptions.bindHost`.)
+- **INV-RC-2** Every remote-control key lives in memory only. Nothing about pairing is written to
+  the data root or the state directory; a phone keeps its own device key in its browser storage.
+- **INV-RC-3** A paired device acts only through the terminal's existing paths: `Terminals.send`,
+  and `TerminalController.control` for `terminal.interrupt`, `terminal.approve`,
+  `terminal.answer`, `terminal.answers` and `terminal.pending.wait`. The validation those paths
+  apply (a busy session, a terminal draft, the rememberable check on "always allow", the policy
+  recheck of a direct approval) applies unchanged.
+- **INV-RC-4** A decision is shown on the phone with its complete action text, never shortened,
+  beside its choices. The first answer from either surface wins; the other surface's card goes
+  away on the next pending revision.
+- **INV-RC-5** Remote control ends with its terminal session (`Terminals.dispose`): the server
+  closes, connected phones are told, and every device key is forgotten. `stop` does the same
+  without ending the session.
+- **INV-RC-6** A paired device runs no slash command, no `!` shell command and no link, and reaches
+  no plugin, account, Hub, worktree or browser control. A message starting with `/` or `!` is
+  refused.
+- **INV-RC-7** Starting remote control and allowing a device are decisions of the person at the
+  terminal: both are control-key calls, and no phone can pair without that confirmation.
+- **INV-RC-8** Every body between the phone and the harness, except the static page, is sealed.
+  A frame that does not open, or whose counter was seen, is refused the same way.
+
+## Threat notes
+
+Sealing defeats a passive listener on the network and replays. It does not defeat an attacker who
+can change traffic on the LAN (for example by ARP spoofing): the page itself is served over plain
+HTTP, so such an attacker could serve a changed page to the phone. The terminal confirmation is the
+remaining check. The `/rc` page tells the person to use Tailscale, whose traffic is end-to-end
+encrypted, on a network they do not trust.
+
+## Data
+
+None stored. The phone's browser keeps `{ deviceId, deviceKey, label }` under
+`remote-control:<host:port>` in its own storage; it is useless once the session ends.
+
+## Source map
+
+`src/remote/`, `src/terminal/terminals.ts` (`remote`, `remotePort`, `remoteCall`, dispose),
+`src/terminal/controller.ts` (`delta`), `src/terminal/piExtension.ts` (`message_update`),
+`src/terminal/tui/pages/remoteControlPage.ts`, `src/terminal/tui/qr.ts`,
+`src/terminal/opentui/app.ts` (`watchRemoteControl`), `src/terminal/opentui/statusBar.ts`,
+`src/terminal/standalone.ts` (`--remote-control`). Decision:
+[ADR-0056](../decisions/ADR-0056-remote-control.md).

package/docs/architecture/README.md

@@ -43,6 +43,7 @@ not one class (a set of functions in one module, say), it says so.
 | [12 Storage](12-storage.md) | The data root and state directory, and who writes what | `INV-STO` |
 | [13 World tools](13-world-tools.md) | Generic web and isolated browser backends, host boundary and diagnostics | — |
 | [14 Surfaces and parity](14-surfaces-and-parity.md) | Every capability is a Harness capability with a terminal surface; host-backed capabilities; host-only surfaces | `INV-PAR` |
+| [15 Remote control](15-remote-control.md) | Continuing a terminal session from a phone or iPad: pairing, sealed frames, the bind policy | `INV-RC` |
 | [Proposals](proposals/README.md) | Architecture change proposals and their status | — |
 
 Related records, not binding by themselves:
@@ -128,3 +129,5 @@ resolve relevant drift by updating the implementation and specification together
 | D-20 | Terminal pending queues, page 11 — resolved | The terminal now projects native and deferred pending messages above the working line. |
 | 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. |
+| D-21 | `terminal-tui.md`, per-mode model and effort | The terminal page says the App reads and writes the per-mode choices through `accounts.choices` and `accounts.choose`. The App's source calls neither method: its account, model and effort are saved on the App Thread (App ADR-0023), and plan mode shares that Thread's tuple. Whether the App should adopt the Harness's per-mode store is an owner decision. |
+| D-22 | Plan outcomes, pages 02 and 11; ADR-0055 — resolved | Page 02 previously described a missing-block repair without distinguishing paths: the runner repaired but the terminal only warned, and neither classified clarification. ADR-0057 adds shared outcome classification and a bounded repair in both paths. |