@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/decisions/ADR-0048-required-skills-from-a-message.md

@@ -0,0 +1,42 @@
+---
+id: ADR-0048
+title: A skill named anywhere in a message is required for that request
+status: Accepted
+created: 2026-11-20
+---
+
+# ADR-0048: A skill named anywhere in a message is required for that request
+
+## Decision
+
+- `$name` is a skill invocation at any word start in a message, not only as its first token. The
+  composer's palette opens at the caret and replaces only the token being typed; the rest of the
+  draft and its caret stay in place.
+- Every `$name` that names a skill the session can load makes that skill required for the request.
+  The named skills travel as `Launch.requiredSkills`, and the prompt compiler renders them as the
+  dynamic `required-skills` section: the skill's text from the pinned variant, the directive to
+  follow it, and an honest line for a name the variant does not have. The shipped
+  `plugin-authoring` skill fills in when the variant has none.
+- The section belongs to the request. `sessionLaunch` resends it like `references`, even when it is
+  identical to the previous snapshot.
+- The terminal builds the same text with `requiredSkillsText` from Pi's loaded skills and appends it
+  as a hidden `xingular-required-skills` custom message. It no longer rewrites a leading `$name` to
+  `/skill:name`; the person's message reaches the model unchanged and the requirement is enforced at
+  every position.
+- A required skill changes no tool and no permission: the run's callable set and the gate are
+  untouched. It is a prompt-level requirement, not a capability narrowing.
+
+## Rationale
+
+Pi expands only a leading `/skill:name`, so a mid-message skill was plain text and had no effect.
+Moving the requirement into the request-scoped prompt text makes the same promise at every position,
+keeps the stable prefix (and therefore the provider cache) intact, and gives the terminal and a host
+one shared wording through `requiredSkillsText`.
+
+## Consequences
+
+A leading `$name` no longer depends on Pi's `/skill:name` expansion. The skill's text is delivered
+once per request that names it, so repeating the same skill in several turns repeats its text in
+native history; the model sees the most recent copy. The App's composer already inserts `$` chips
+anywhere; its reference path now sends skills as `requiredSkills` rather than as pinned notes.
+Skills that a variant does not contain are reported as unavailable rather than silently dropped.

package/docs/decisions/ADR-0050-approved-window-screenshots.md

@@ -0,0 +1,19 @@
+# ADR-0050: Approved-window screenshot contract
+
+## Decision
+
+A host may supply `computer_screenshot` through the existing tool-provider extension point using
+the Harness contract in `src/computer/screenshot.ts`. The backend must capture one currently
+approved window and exclude the desktop, other windows and overlays, including overlapping ones.
+If it cannot guarantee that scope it refuses without returning pixels; it never silently captures a
+display instead. The adapter is opt-in, goes through the ordinary tool gate, and does not make
+capture plan-mode safe. A host that also offers coordinate-based interactions interprets their
+coordinates relative to the returned image pixels.
+
+## Consequences
+
+Browser screenshots remain a separate capability with their own tab isolation. The contract cannot
+verify native backend isolation; each host must implement and test it. The existing macOS display
+capture has not adopted this contract and is not evidence of approved-window isolation. The
+standalone terminal has no such backend. The contract adds no automatic provider registration or
+new extension point.

package/docs/decisions/ADR-0051-terminal-decision-wait.md

@@ -0,0 +1,10 @@
+# ADR-0051: Revisioned terminal decision waits
+
+The terminal needs timely approval and question updates while avoiding a control request every
+100 ms in every idle session. The controller owns the pending inbox, so it exposes a private,
+control-key-protected revisioned snapshot with a bounded wait. Every inbox mutation wakes waiters;
+the frontend resynchronizes on reconnect. The existing immediate snapshot remains available.
+
+The wait uses a separate socket request, so it does not block other terminal control calls.
+Waits time out after 20 seconds and are woken on controller disposal. Client shutdown cancels its
+request. No persisted state or public server protocol changes.

package/docs/decisions/ADR-0052-per-profile-subagent-budgets.md

@@ -0,0 +1,25 @@
+# ADR-0052: Per-profile and total subagent budgets
+
+A run could start any number of children: `maxDepth` bounded nesting only. Run `90906235`
+("Implement the plan: Safe screenshot capability", 2026-10-28) started 11 children in nine
+minutes for a five-step plan — three spawns before the parent had read a file, five children that
+returned no change, and two tasks retried as fresh children. The shape of delegation was left to
+the prompt.
+
+A run now starts only a bounded number of distinct child conversations. Foundation defaults: four
+children in total, two `worker`, three `explorer`, one of any other named profile and one with no
+profile. A host overrides them through `SessionRunInput.subagents` (`maxChildren`, `maxByProfile`,
+`maxOther`, `maxUnprofiled`), so the terminal and the App receive the same defaults; every value
+is an integer clamped to 0–50.
+
+`Subagents.spawn` counts the run's recorded children in `subagents.json`, the children of the
+parent runs it was continued from (`resumedFromRunId`), and slots reserved by concurrent calls. It
+deduplicates a continuation to its first link, so continuing a stopped child uses no new slot,
+while a child whose startup failed still counts. A refused spawn returns an `invalid_request`
+tool result telling the model to do the work itself; it creates no run. `continue` bypasses the
+check because it is the same child.
+
+The budget is per run, not per conversation, so a long chat is not starved. It lives in the
+foundation because it bounds what every application built on the harness may spend, and changing
+it needs a release. A host that legitimately needs more children raises the limits for its
+session; the spawn tool's description states the effective numbers.

package/docs/decisions/ADR-0053-no-repeated-work-guard.md

@@ -0,0 +1,45 @@
+---
+id: ADR-0053
+title: No repeated-work guard in the work slice
+status: Accepted
+created: 2026-10-28
+supersedes: ADR-0039 (targeted protections only)
+---
+
+# ADR-0053: No repeated-work guard in the work slice
+
+## Decision
+
+Remove the repeated-work rules from the shared work-slice guard (`src/sessions/workSlice.ts`). A
+reply is no longer refused for calling the same tool with the same arguments three times, for
+running a Bash check that failed twice, or for more than four successful `edit`/`write` results on
+one path. Nothing ends a reply as `stuck`.
+
+The bounds that remain are the configured tool-call, minute and new-token budget and the
+third-compaction thrash rule, both of which still ask for a checkpoint handoff and end the reply on
+further calls. A budget-ended reply is `interrupted` with terminal reason `slice_complete` in both
+surfaces. Slice continuation, the plan-research child bound and the model-written `blocked`
+checkpoint gate are unchanged.
+
+`checkpointReasonSchema` keeps `stuck` so stored `checkpoint` events stay readable and the
+`checkpoint_write` argument set does not change; nothing produces it any more.
+
+## Rationale
+
+The rules fired on calls that are ordinary work. Reading a file again, editing one file several
+times, or re-running a check after a partial fix are not loops, and a refusal there costs a reply
+plus the checkpoint and continuation round trip. Tool arguments are not a reliable signal of a loop:
+a changed argument is different work, an identical argument can be legitimate (a poll, a re-read
+after an edit, a retried check), and the guard cannot tell them apart. The reply budget already
+bounds a model that never stops, which is the failure the guard existed to catch; the compaction
+rule covers the other observed thrash.
+
+## Consequences
+
+A reply may repeat any call until its budget, so a genuinely stuck model runs up to 320 calls or 60
+minutes instead of being stopped earlier. No run-event schema, stored-data layout, server method or
+App presentation changes: `stuck` remains a readable checkpoint reason and `stalled` remains the
+watchdog's reason for a silent run. This supersedes the targeted repeated-call, repeated-failing-check
+and edit-churn protections in [ADR-0039](ADR-0039-progress-aware-stall-guards.md); the rest of that
+decision, including the bounded plan-research child, stands. See also
+[PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md).

package/docs/decisions/ADR-0054-terminal-reply-heartbeat-and-stall.md

@@ -0,0 +1,52 @@
+---
+id: ADR-0054
+title: A live terminal reply reports a heartbeat and ends when it stops making progress
+status: Accepted
+created: 2026-10-28
+proposal: PROP-0041
+---
+
+# ADR-0054: A live terminal reply reports a heartbeat and ends when it stops making progress
+
+## Context
+
+A structured run emits a `heartbeat` every 30 seconds while it works, and the run sweep uses it to
+settle a reply that stopped reporting (INV-RUN-14). A terminal reply emitted none: the extension sent
+tool, message and usage telemetry, but never a heartbeat. Two consequences followed.
+
+The sweep could not tell a wedged reply from one written before heartbeats existed, so it waited the
+full 30-minute silence window, and then recorded `owner_gone` — "the owner process is gone" — while
+the owner was alive and its turn was still pending. On 2026-10-28 a `deepseek-v4.1-flash` request in
+a terminal session produced a partial tool call and then nothing for 38 minutes; a request earlier in
+the same session stayed open for 2 h 13 min and ended only when the person typed the next message.
+The run showed as `running` the whole time.
+
+## Decision
+
+A terminal reply reports a `heartbeat` every 30 seconds for as long as its turn is live, with the
+counters its work slice already keeps: steps, elapsed time, last tool, compactions, slice and the
+call budget. The controller records it on the active run like any other telemetry, so the sweep's
+existing five-minute heartbeat rule now applies to terminal replies.
+
+A heartbeat proves the turn is alive, not that it is working, so the terminal controller also ends a
+reply that produced no event other than heartbeats for fifteen minutes. It does that by asking the
+native turn to abort through the command the extension already polls; the run records `interrupted`
+with reason `stalled`. A reply whose oldest running tool has run for thirty minutes is ended the same
+way. A reply with an unanswered approval or question is never cut short, because it is waiting on the
+person, not on the model.
+
+## Rationale
+
+The two windows are different questions. Five minutes of silence with no heartbeat means the process
+stopped reporting, which the sweep settles; fifteen minutes of heartbeats with no progress means the
+process is alive but the reply is not moving, which only the controller can end. Keeping both avoids
+weakening the rule that protects a live but quiet turn: a long tool or a long reasoning stream still
+reports its heartbeat, and the person answering a decision is never timed out.
+
+## Consequences
+
+A model request that never returns is ended after fifteen minutes instead of running for hours, and
+the record carries a reason that is true. Terminal replies now write one small event every 30
+seconds (about 60 KB an hour), the same as a bounded structured reply. No tool, permission, run-event
+schema or stored-data layout changes: `heartbeat` already exists in the stream, and the reason
+`stalled` is already part of the contract.

package/docs/decisions/ADR-0055-plan-output-repair.md

@@ -0,0 +1,51 @@
+---
+id: ADR-0055
+title: An attended plan run repairs a missing plan block once, in the same run
+status: Accepted
+created: 2026-10-28
+---
+
+# ADR-0055: An attended plan run repairs a missing plan block once, in the same run
+
+## Context
+
+Plan mode ends with a `<proposed_plan>` block that both the terminal and the App parse into a plan
+card and the Implement choice. The block is an instruction to the model, not a schema, and a model
+can omit it while still writing a correct plan body. On 2026-10-28 two attended plan runs in one
+terminal session did exactly that: the plan instructions and the plan-only tool set were present,
+the model's reasoning said it would tag the plan, and the final text had no block. The renderer then
+showed ordinary assistant text with no card, no plan choice and no Implement.
+
+The tag contract is deliberately text-only: it keeps the plan tool list and the cached prompt prefix
+unchanged when the mode switches. Replacing it with a plan tool or a plan artifact would change that
+boundary, the protocol and both renderers for a rare omission.
+
+## Decision
+
+When a top-level attended plan run ends without a complete plan block, the harness makes one hidden
+format-repair turn in the same run. The custom message is not displayed, carries no new user
+request, and asks the model to re-send its own plan, unchanged, in one complete block; a model that
+was asking for input answers `No plan:` instead. The repair is attempted once, uses the same plan
+tool set and gate, and is skipped for plan-research children, commands, probes, improvers,
+reflections and other unattended runs.
+
+If the repair also fails, the plan run still completes: the original reply stays in the transcript,
+the harness records an `extension.notice` warning, and the terminal shows a warning instead of a
+plan choice. The App shows the repaired card when the repair succeeds and otherwise keeps the
+untagged reply.
+
+## Rationale
+
+The repair is the smallest change at the ownership layer that preserves the existing plan contract and
+both surfaces. It does not fabricate a plan or guess where one starts, and it leaves the plan tool
+list, the prompt prefix and the run event schema unchanged. Asking the model to re-send its own
+answer is cheaper and less disruptive than re-planning, and a single bounded attempt keeps the extra
+cost and latency predictable.
+
+## Consequences
+
+An attended plan run may make one additional model request and produce a second assistant message;
+the first untagged reply remains visible. The extra request is counted in the run's usage, and the
+run record, status and event types are unchanged. If the repair proves insufficient, a structured
+plan tool or artifact remains the durable follow-up, but it changes the tool list, the cached prefix
+and both renderers and is not part of this decision.

package/docs/decisions/ADR-0056-remote-control.md

@@ -0,0 +1,53 @@
+---
+id: ADR-0056
+title: Remote control connects a phone directly to the terminal session, with sealed frames
+status: Accepted
+created: 2026-10-28
+---
+
+# ADR-0056: Remote control connects a phone directly to the terminal session, with sealed frames
+
+## Context
+
+A person wants to keep a terminal session going from a phone or iPad, the way Claude Code's
+`/remote-control` (`/rc`) does: the session keeps running on the computer, and the phone sends
+messages, watches the reply, stops it and answers approvals. Claude Code reaches the phone through
+Anthropic's cloud relay. The harness has no cloud service, and every listener it had bound only
+127.0.0.1.
+
+## Decision
+
+`/remote-control` (`/rc`) starts a small HTTP server in the `xagent` parent process, bound to one
+address: the computer's Tailscale address when it has one, otherwise its private Wi-Fi or LAN
+address. The terminal shows a QR code for a pairing link whose key is in the URL fragment. A phone
+that opens it asks to pair; the person at the terminal allows it; the phone receives its own key.
+The phone then becomes a second person at the terminal, with the same powers and the same paths:
+`Terminals.send` and the terminal controller's interrupt and decision calls (page 15).
+
+Every request and event body is a NaCl `secretbox` frame under the link or device key, with a
+replay counter. All keys live in memory and end with the session.
+
+## Rationale
+
+- **Direct, not relayed.** A relay is a service to build, run and trust. A direct connection
+  needs nothing outside the computer, and Tailscale covers the "away from home" case with its own
+  end-to-end encryption.
+- **Sealed frames, not TLS.** A LAN page cannot have a trusted certificate, and a self-signed one
+  shows a warning a person learns to click through. Over plain HTTP the browser has no WebCrypto,
+  so the page uses `tweetnacl`, served beside it. The key never crosses the network: it reaches the
+  phone in the QR code's fragment.
+- **Confirmation at the terminal.** A photographed QR code is not enough to pair; the person at the
+  terminal sees the device and allows it.
+- **In-memory keys.** Nothing to revoke later, nothing on disk (INV-ACC-3), and the link dies with
+  the session.
+
+## Consequences
+
+- New harness module `src/remote/`, a new spec page (15), and two dependencies: `tweetnacl` (also
+  served to the phone) and `uqr` (QR encoding).
+- The terminal extension now reports streamed assistant text, batched, as `delta` telemetry, and
+  terminal runs record `message.delta` events the way structured runs already do.
+- An attacker who can change LAN traffic could serve a changed page to the phone; the terminal
+  confirmation and the advice to use Tailscale on untrusted networks are the mitigation.
+- The App presents remote control only as a stub for now (`PAR-018`): its sessions are not
+  terminal sessions.

package/docs/decisions/ADR-0057-structured-plan-outcomes.md

@@ -0,0 +1,39 @@
+---
+id: ADR-0057
+title: Structured outcomes for attended plan requests
+status: Accepted
+---
+
+# ADR-0057: Structured outcomes for attended plan requests
+
+## Context
+
+A reply asking for a decision is not a finished plan. ADR-0055 prescribes one repair for a missing
+plan block, but the prior server parser recognized only `<proposed_plan>` and could treat a request
+for input as a format failure. The terminal did not run that repair. D-22 records the prior
+implementation gap and documentation ambiguity.
+
+## Decision
+
+An attended top-level plan reply has one classified outcome: `plan_ready` for a complete existing
+`<proposed_plan>` block, `needs_input` for a complete `<plan_clarification>` block containing the
+needed question or explanation, and `invalid` for missing, incomplete, conflicting or malformed
+outcome blocks. Only `plan_ready` permits a plan card and Implement. `needs_input` is displayed as
+input needed, never as an actionable plan. The same classification and bounded repair belong to the
+Harness and apply to both server and terminal, rather than independent surface heuristics.
+
+When `ask_user` is available, it blocks for the person's answer and the same run continues; the
+clarification outcome describes input still needed at the end, including when interaction is not
+available. The model must not invent a decision. For an eligible run ending in `invalid`, one hidden
+repair turn in the same run requests a valid outcome without changing substance or inventing
+answers. Either valid outcome ends repair. If repair fails, retain the original text, complete with
+a warning, and offer no Implement. Skip repair for unattended or child runs, commands, aborts,
+errors and work-slice termination. The plan gate remains in force.
+
+## Compatibility and consequences
+
+This supersedes ADR-0055's plan-only repair criterion, not its bounded same-run mechanism. Existing
+`<proposed_plan>` output and cards remain valid; no new tool, mandatory event type, changed stable
+prompt prefix or widened permissions are required. Older clients may show clarification as ordinary
+text, but must not interpret it as a plan. Historical untagged replies remain visible without being
+fabricated into plans. D-22 is resolved by shared classification and bounded repair on both paths.

package/docs/decisions/ADR-0058-ask-user-only-plan-clarification.md

@@ -0,0 +1,36 @@
+---
+id: ADR-0058
+title: Ask-user-only plan clarification
+status: Accepted
+---
+
+# ADR-0058: Ask-user-only plan clarification
+
+## Context
+
+ADR-0057 allowed a final `<plan_clarification>` containing a question or explanation. That creates
+another clarification channel alongside the blocking `ask_user` tool and can end a run instead of
+continuing planning after the person's answer.
+
+## Decision
+
+For new attended top-level plan final replies, the shared server and terminal classification is
+`plan_ready`, `blocked`, or `invalid`. A complete `<proposed_plan>` is `plan_ready` and alone offers
+a plan card and Implement. If a required user decision cannot be obtained because `ask_user` is
+unavailable, the reply is `blocked`: explain the blocker without inventing the decision, asking a
+free-text question, or offering Implement. Malformed, missing or conflicting outcomes are `invalid`.
+New final replies do not use `<plan_clarification>` or free-text questions for clarification.
+
+When `ask_user` is available and clarification is needed, call it: it blocks the active run for the
+answer, after which the same run continues. The existing one bounded hidden repair for an eligible
+`invalid` outcome remains in the same run and under the same plan gate; it may call `ask_user` and
+wait for the answer. If repair remains invalid, retain the original reply, warn and offer no
+Implement. The existing repair exclusions remain in force.
+
+## Compatibility and consequences
+
+This supersedes ADR-0057's `needs_input` and `<plan_clarification>` final-outcome decision, not its
+shared classification, bounded repair or other safeguards. Old transcripts remain intact and
+visible, including historical clarification blocks; they are not rewritten or promoted into plans.
+Existing plan cards, run events, permissions and the cached prompt boundary remain compatible. This
+is an approved contract; implementation and surface acceptance must be verified separately.

package/docs/decisions/ADR-0059-run-diagnostic-evidence.md

@@ -0,0 +1,35 @@
+---
+id: ADR-0059
+title: Record structured refusal and run stop evidence
+status: Accepted
+created: 2026-10-29
+---
+
+# ADR-0059: Record structured refusal and run stop evidence
+
+## Context
+
+A stopped or incomplete run can result from a guardrail, a lifecycle limit, a provider failure, or
+model behaviour. Human-readable tool results and terminal reasons alone do not reliably distinguish
+these cases, and matching their text binds diagnosis to wording. Historical records cannot establish
+an outcome code that was never recorded.
+
+## Decision
+
+The foundation records a `tool.refused` event for a gate or work-slice refusal, with the call id,
+tool name, bounded reason and a fixed refusal code. It keeps the existing tool response text. The
+terminal relays the same evidence on a best-effort basis; an unreachable controller cannot record its
+own loss. Refusals within a running tool are not gate events.
+
+A settled run records a nullable `terminalCode` separate from its human-readable `terminalReason`.
+Interrupted status events may carry a code; failed events retain their existing failure code, mapped
+to a stop code by the run store. Recovery records its own known cause. Older records without a code
+remain unknown, not a guessed cause. Trajectory search and the terminal trajectory view expose the
+recorded evidence. Compaction events include available measurements rather than estimates.
+
+## Consequences
+
+Diagnostic clients can distinguish recorded causes without parsing prose, while still examining the
+original evidence. Stop codes describe why a run settled, not whether the requested work was actually
+finished. Callers must accept the added event and optional record fields, and historical runs retain
+less precise evidence. The foundation remains the only writer of run records and events.

package/docs/decisions/ADR-0060-approvals-are-controls.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0060
+title: Approvals are controls, not messages
+status: Accepted
+created: 2026-10-29
+---
+
+# ADR-0060: Approvals are controls, not messages
+
+## Context
+
+The gate already pauses a call that needs a person, reports `waiting_for_approval`, and resumes the
+same call when it is allowed. But the compiled guidance said an outside file target "requires
+one-call approval", and a denial said "Ask how they would like to proceed". A model read the first as
+a prerequisite and ended its turn: the person then had to type an approval in a message before the
+work could continue. Typed permission is neither recorded as a decision nor bound to the call it
+authorizes, and it leaves the run idle while a control could have resolved it.
+
+## Decision
+
+An approval is a control a person operates, never a permission asked for or granted in a message.
+The gate pauses the exact call, the run reports `waiting_for_approval`, Allow resumes that same call
+in the same turn, and Deny returns a tool result on the still-running turn. The compiled prompt
+states this rule and tells the model to call the tool rather than ask for permission, end its turn to
+wait, or report a task as blocked before trying it. Denial text tells the model to continue instead
+of asking again. Surfaces present a control: the terminal's decision dock and keypress, the App's
+dock above the composer with an approval notification, and a paired phone's choices. A surface that
+cannot ask a person refuses the call; it never waits for a message.
+
+The boundary still applies before the effect. This decision changes who speaks, not when a call runs:
+nothing outside the workspace changes before the click, and Full Permission remains the explicit
+standing bypass for eligible runs.
+
+## Consequences
+
+The run survives the wait and resumes in place, and no approval depends on prose a person typed.
+Clients must present a control for every request they surface (`INV-GATE-9`). A host that cannot
+present one must refuse the call, and the model must treat that refusal as the tool result rather
+than asking again. Recorded decisions, standing approvals and the refusal codes stay unchanged; only
+the wording the model reads after a denial changed.

package/docs/decisions/ADR-0061-strict-plugin-command-namespaces.md

@@ -0,0 +1,41 @@
+# ADR-0061 — Strict owner namespaces for plugin commands and prompts
+
+Status: Accepted; implementation and surface acceptance not certified.
+Amends: [ADR-0031](ADR-0031-plugin-command-owner-namespaces.md) and
+[ADR-0034](ADR-0034-first-class-harness-terminal-commands.md) for plugin-owned routes.
+Related: [06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[10 Server protocol](../architecture/10-server-protocol.md),
+[11 Terminal](../architecture/11-terminal.md), [parity register](../parity.md).
+
+## Context
+
+An owner-qualified extension command can coexist with a bare package prompt or alias, leaving
+ownership unclear and allowing discovery order to decide what a person invokes. Package templates
+and extension commands need one predictable namespace without changing standalone prompts, skills
+or first-class Harness commands.
+
+## Decision
+
+Plugin-owned commands, including plugin-owned prompt templates, use
+`/<owner-prefix>:<name>` only. No bare plugin command or template alias is offered in listing,
+completion or dispatch. Existing core commands and their core aliases remain core; standalone
+prompt templates retain their existing forms, and `/skill:<name>` remains reserved for skills.
+Built-in default commands continue to use their namespace roots.
+
+A package may set `harness.defaultPrompt` to the name of its own prompt template. The explicit,
+valid and unambiguous selection makes `/<owner-prefix>:` invoke that template; no root is inferred
+from an undeclared, missing, ambiguous or foreign template. Prefixes remain stable owner identities,
+using `harness.commandPrefix` or the existing normalized fallback. When owners claim the same
+prefix, or contributions within one owner claim the same route, including a template and an
+extension command, the collision fails closed with owner diagnostics; discovery order never selects
+a winner. The same rules apply to `commands.list`, completion, recognition and dispatch.
+
+## Consequences
+
+Plugin users must update bare plugin invocations to owner-qualified routes; standalone templates,
+skills and core command routes are not renamed. Ownership does not grant attachment, code trust or
+permission. The decision changes command routing and discovery, not protocol framing or persisted
+run data. A listing is not evidence of surface acceptance. This record approves the contract; it
+is not evidence that source or either surface has implemented it.
+
+Page 14 states the same package-versus-standalone distinction.

package/docs/decisions/ADR-0062-shared-account-state.md

@@ -0,0 +1,67 @@
+---
+id: ADR-0062
+title: A launch signs in as the account state it is given, and development shares the installed one
+status: Accepted
+created: 2026-10-29
+---
+
+# ADR-0062: A launch signs in as the account state it is given, and development shares the installed one
+
+## Context
+
+Account identity was welded to the launch's state directory: a registry, one agent folder per
+account and the owner-only `secrets.json` that holds their credentials, all under `<state dir>`.
+`npm run dev` passes its own `~/.xingular-harness-dev/state`, so it started with no accounts, and a
+person had to sign in again — a second OAuth flow, a second set of tokens and, for a subscription
+provider, a second live sign-in — before the development terminal could run anything. The
+installed `xagent` on the same machine had the sign-in the person actually wanted to use.
+
+Signing in twice is not just friction. A subscription provider's OAuth flow rotates credentials,
+and two independently signed-in copies are two sessions the provider sees; keeping them identical
+by hand is not something a person can do.
+
+## Decision
+
+The account identity of a launch is a folder, not a fixed child of its state directory:
+
+- `HarnessOptions.accountsDir` selects where the registry, the per-account Pi agent folders and
+  their shared settings live. It defaults to `<state dir>/accounts`, so every existing caller is
+  unchanged.
+- The standalone terminal accepts `--account-state <dir>`, which uses that state directory's
+  `accounts/` folder and its `secrets.json`. A launch that shares an account folder must use the
+  secret store those account ids belong to; both halves travel together.
+- `scripts/dev.mjs` passes `--account-state ~/.xingular-harness/state` unless the person names
+  another one, so the development terminal signs in as the installed command's accounts and a
+  single sign-in serves both launches.
+
+Development keeps its own data root, state directory, approvals, plugin trust and connections.
+Only the account identity is shared.
+
+## Rationale
+
+- **One identity, not a copy.** Two credential files that must stay equal is the failure this
+  removes. The registry, the account folders and the credential file are read and written by both
+  launches through the same paths and the same credential lock, which is the concurrency two
+  windows of the installed command already have.
+- **The option belongs to the launch, not to a profile field.** A profile selects defaults; a
+  launch that wants another state's accounts names that state explicitly, and the terminal prints
+  nothing implicit about it. The host (`serve`) keeps deciding its own account identity, as the
+  App does with its own keychain.
+- **The development launcher decides the sharing.** Keeping data and approvals separate was the
+  point of `~/.xingular-harness-dev`; signing in twice was the accident. Sharing only the identity
+  keeps both properties, and `--account-state` restores full isolation in one flag.
+
+## Consequences
+
+- A credential written by either launch is the credential of the other. A sign-out in development
+  signs out the installed command too; this is the same account, not a sandbox of it. Pi's native
+  sessions under each account folder are shared the same way, while run records stay in each
+  launch's own data root.
+- Both launches write the one `secrets.json` under the same lock directory, and the one
+  `accounts.json` through atomic replacement. That is the concurrency the installed command
+  already allows between two of its own windows.
+- Accounts created in the dev state before this change are not migrated. Their registry, folders
+  and credentials remain under `~/.xingular-harness-dev/state`; signing in to the shared identity
+  is the deliberate replacement.
+- `docs/architecture/09-accounts-and-connectors.md`, `11-terminal.md` and `12-storage.md` state the
+  selected account folder rather than a fixed `<state dir>/accounts`.

package/docs/decisions/ADR-0063-unfinished-work-handoffs.md

@@ -0,0 +1,34 @@
+---
+id: ADR-0063
+title: Actionable handoffs for unfinished work
+status: accepted
+created: 2026-10-30
+updated: 2026-10-30
+---
+# ADR-0063 — Actionable handoffs for unfinished work
+
+> **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** this guidance now applies only when the work stopped on a blocker or a decision (`finish`), never as a way to end a reply with work left.
+
+## Context and decision
+
+A reply can accurately report blockers yet leave the person unable to tell what decision or
+action would resolve them. [PROP-0051](../architecture/proposals/PROP-0051-unfinished-run-handoff.md)
+records an example. Extend the stable, harness-owned reporting guidance: when work remains
+unfinished, identify the concrete decision the person must make or the next action and its owner
+for each material blocker. Do not simply restate the blocker or invent a human decision.
+
+This preserves [ADR-0008](ADR-0008-flexible-reporting-guidance.md): use only helpful structure,
+without a fixed heading. It does not change approval controls, run status or the stable/dynamic
+prompt boundary; no live todo state is injected into the system prompt.
+
+## Consequences
+
+- All packs receive the same conditional guidance; completed replies need no handoff boilerplate.
+- The stable prefix changes; cache behavior requires real-request measurement under INV-PRM-8.
+- This is model guidance, not enforced behavior; tests cannot guarantee the model follows it.
+
+## Alternatives considered
+
+- Only list blockers: rejected because it can leave the person without an actionable next step.
+- Require a fixed heading or inject live todo state: rejected to preserve flexible reporting and
+  the stable prompt boundary.