@xingular/harness 1.1.1 → 1.3.1-unstable.0

package/docs/architecture/proposals/README.md

@@ -1,16 +1,16 @@
 # Architecture proposals
 
-A proposal is required before any change that alters a contract, an invariant, a layer
-boundary, an extension point, or the storage layout described in [the specification](../README.md).
-The author writes it and stops; the user reviews it. Code and spec pages change only after the
-proposal is `Accepted`.
+Proposals are optional design records for changes to contracts, invariants, layer boundaries,
+extension points, or storage layout in [the specification](../README.md). They may be written before
+or alongside implementation, but do not gate code or spec changes. When a proposal is created, add
+it to the index and update its status as the work progresses.
 
 ## Status
 
 | Status | Meaning |
 |---|---|
-| `Proposed` | Written, waiting for the user. Nothing has changed. |
-| `Accepted` | The user approved it. Implement it and update the spec pages in the same change. |
+| `Proposed` | A draft design record; implementation status is tracked separately. |
+| `Accepted` | The user approved the design. Approval is not a prerequisite to implementation. |
 | `Implemented` | Code and spec pages match the proposal. Link the commit or ADR. |
 | `Rejected` | The user declined it. The file stays as a record. |
 | `Withdrawn` | The author dropped it before review. |
@@ -59,6 +59,24 @@ proposal is `Accepted`.
 | [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
 | [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
 | [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+| [PROP-0031](PROP-0031-plugin-command-owner-namespaces.md) | Namespace plugin commands by owner | Implemented; Harness and App checks passed | INV-TUI-7, 06, 11, 14, terminal-tui.md, README.md, ADR-0021, ADR-0031 | 2026-10-25 |
+| [PROP-0032](PROP-0032-planning-quality.md) | Evidence-grounded planning with read-only research delegation | Implemented; live model pilot pending authorization | INV-RUN-8, INV-GATE-3, INV-CAP-1, 02, 06, 07, 14, parity, ADR-0033 | 2026-10-25 |
+| [PROP-0033](PROP-0033-compaction-plan-checkpoints.md) | Rehydrate bounded run checkpoints after compaction | Accepted; implemented | INV-PRM-1/4/10, INV-RUN-8/12, 02, 04, 11, 14, ADR-0032 | 2026-10-25 |
+| [PROP-0034](PROP-0034-conversation-fast-mode.md) | Conversation-scoped provider fast mode | Proposed | INV-RUN-1/3, INV-PAR-1/2, 02, 09, 10, 11, 12, 14, parity, App thread runtime settings | 2026-10-25 |
+| [PROP-0035](PROP-0035-retain-subagent-status.md) | Retain terminal subagent status until the next run | Implemented; initial PTY failure resolved; full verifier passed at three sizes (2026-11-19) | 11-terminal.md, terminal-tui.md | 2026-10-25 |
+| [PROP-0036](PROP-0036-first-class-harness-commands.md) | First-class Harness terminal commands | Implemented | INV-PLG-10, INV-TUI-7, 06, 11, 14, terminal-tui.md, parity, ADR-0034 | 2026-10-25 |
+| [PROP-0037](PROP-0037-workspace-write-boundary.md) | Default filesystem writes to the active project workspace | Implemented | INV-GATE-1/3/8, INV-RUN-1, INV-TUI-8, 02, 04, 07, 10, 11, 12, 14, parity | 2026-11-19 |
+| [PROP-0038](PROP-0038-annotate-open-shadow-roots.md) | Annotate inside open shadow roots | Implemented | 13-world-tools.md, note target, PROP-0017, PROP-0018, parity | 2026-10-25 |
+| [PROP-0039](PROP-0039-workspace-boundary-hardening.md) | Harden workspace writes against inode escapes and unverified retries | Accepted; implementation validated on macOS, Linux validation pending | INV-GATE-3/8, INV-TUI-8, 02, 07, 11, 14, parity | 2026-10-26 |
+
+| [PROP-0040](PROP-0040-one-launch-path.md) | One launch path and command contract across front ends | Accepted; implementation in progress | 01–04, 06–07, 10–14, parity | 2026-11-19 |
+| [PROP-0041](PROP-0041-bounded-work-slices.md) | Bounded work slices, a durable checkpoint, and a stall guard for long replies | Implemented; terminal card, App presentation and /slices open (PAR-004) | INV-RUN-2/3/4/12, INV-PRM-1/2/4/5/10, INV-GATE-2, INV-STO-3, INV-PAR-1/2, 02, 04, 07, 10–12, 14, parity | 2026-10-26 |
+| [PROP-0042](PROP-0042-usage-and-provider-limits.md) | Usage analytics and provider limits as a built-in capability | Accepted; implemented | INV-MEM-5/6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02, 06, 08–12, 14, parity, ADR-0037 | 2026-10-26 |
+| [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
+| [PROP-0044](PROP-0044-work-slice-defaults.md) | Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap | Accepted; implemented | INV-RUN-13, 02, 10, 11, PROP-0041 | 2026-10-26 |
+| [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
+| [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
+| [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
 
 Numbers are four digits, start at `0001`, and are never reused.
 

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -34,7 +34,7 @@ Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatibl
 socket/controller bridge and its final gate. Keep the private control claim in process memory
 across native session replacement, revalidate prepared resource trust before every load, and
 scope native resume/import to the terminal's original working folder. Put unavoidable Pi
-implementation imports in one adapter checked against the pinned 1.2.0 version.
+implementation imports in one adapter checked against the pinned Pi version.
 
 Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
 commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and

package/docs/decisions/ADR-0021-required-command-namespaces.md

@@ -1,6 +1,6 @@
 # ADR-0021 — Required built-in commands use the bare namespace
 
-Status: Accepted (owner requested implementation of PROP-0021, 2026-10-24).
+Status: Superseded by [ADR-0031](ADR-0031-plugin-command-owner-namespaces.md).
 Supersedes: The command-namespace portion of [ADR-0018](ADR-0018-builtin-feature-plugins.md).
 Related: [PROP-0021](../architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md),
 [11 Terminal](../architecture/11-terminal.md),

package/docs/decisions/ADR-0031-plugin-command-owner-namespaces.md

@@ -0,0 +1,37 @@
+# ADR-0031 — Plugin commands use owner-qualified namespaces
+
+Status: Accepted (PROP-0031, 2026-10-25).
+Supersedes: The command-namespace decision in [ADR-0021](ADR-0021-required-command-namespaces.md).
+Related: [PROP-0031](../architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md).
+
+## Context
+
+The generic `/plugin:<command>` form hid command ownership for optional built-ins and Pi extensions,
+while required built-ins used a separate bare-command rule. Both forms left a global collision surface
+and made help, completion and invocation inconsistent across owners. Annotation routes also used the
+generic plugin prefix despite the plugin's annotation-focused purpose.
+
+## Decision
+
+Every plugin-owned terminal command is invoked as `/<owner-prefix>:<command>`, regardless of whether
+the owner is a required built-in, optional built-in or Pi extension. Core terminal commands remain
+unprefixed, and `/skill:<name>` remains reserved for skill invocation. Built-in plugins use stable
+prefixes; Pi packages may set `harness.commandPrefix` and otherwise derive the prefix from normalized
+package identity, while loose extensions use normalized extension names. Prefixes identify owners and
+must be unique; duplicate commands within an owner and owner-prefix collisions are rejected with
+source diagnostics.
+
+A built-in plugin module may choose a default command for its namespace root. Web annotations uses `/annotate:` for
+capture, `/annotate:annotate` as an equivalent alias, and `/annotate:notes` for saved annotations.
+For one release, the previous `/plugin:<command>` and bare required-plugin forms remain hidden
+compatibility aliases when unambiguous. They are omitted from help and completion.
+
+## Consequences
+
+The namespace rule applies uniformly to completion, help, highlighting and dispatch. Plugin packages
+may opt into a stable custom prefix with `harness.commandPrefix`. The compatibility aliases expire
+after one release and should not be used for new scripts or keybindings. This changes no server method,
+capability identifier, account data or annotation storage format.

package/docs/decisions/ADR-0032-compaction-run-checkpoints.md

@@ -0,0 +1,33 @@
+# ADR-0032 — Rehydrate bounded run checkpoints after compaction
+
+Status: Accepted (PROP-0033, 2026-10-25).
+Related: [PROP-0033](../architecture/proposals/PROP-0033-compaction-plan-checkpoints.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[04 Prompt](../architecture/04-prompt.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Pi preserves the native conversation transcript when compacting, but subsequent model requests use a
+summary and recent messages. The Harness already records the latest checklist as a run event and
+restores it when a stopped run is continued; an active run lacked equivalent rehydration after
+compaction. SDK plan instructions are dynamic context and may also be included in the summarized
+span.
+
+## Decision
+
+After compaction, each model request in the still-active run receives one bounded, ephemeral context
+message when a checklist or applicable plan instructions exist to restore. It contains the current
+request and available state. The prompt compiler assembles this content, and one Harness-owned
+extension provides the same behavior to embedded sessions and the terminal. The extension state is run-scoped and clears on
+settlement or branch navigation. The context message is not persisted to the native transcript or
+run-event stream; existing session history, checklist events and continuation records remain the
+sources of durable state. Hidden reasoning is never captured.
+
+## Consequences
+
+Post-compaction requests carry a small additional context block until the active run settles. The
+feature adds no storage, event, server method, tool, permission or stable-system-prompt change. Plan
+mode's existing gate remains authoritative. Runs without an explicit checklist or active plan state
+receive no checkpoint.

package/docs/decisions/ADR-0033-plan-mode-research-delegation.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0033
+title: Keep delegation selective and research-only in plan mode
+status: accepted
+created: 2026-10-25
+updated: 2026-10-25
+related: [PROP-0032, INV-RUN-8, INV-GATE-3, INV-CAP-1]
+---
+
+# ADR-0033 — Keep delegation selective and research-only in plan mode
+
+## Context
+
+Subagents can reduce the cost of substantial independent work, but a child starts without the
+parent's conversation and parallel edits create integration risk. Plan mode must remain read-only;
+allowing every profile would let profile overrides expand its effective tools or plugins. Ordinary
+subagent guidance also belongs in request context, not the stable system prompt.
+
+## Decision
+
+- In normal mode, recommend delegation only for substantial, bounded, independent work. Prefer a
+  fitting specialist, give each child a self-contained brief, parallelize only independent tasks,
+  and keep integration and verification with the parent. Simple lookups, tiny edits and tightly
+  coupled work stay with the parent.
+- In plan mode, allow only a named profile whose resolved tool and plugin allowlists are explicit
+  and confined to read-only research. The tool gate checks each spawn's arguments before approvals;
+  the subagent service checks again before launch.
+- A research child inherits plan mode and can use only the intersection of its profile, the parent's
+  frozen capabilities and the plan research set. It has no connectors, user questions, writes,
+  commands or nested subagents. Its evidence returns to the parent, which verifies and synthesizes it.
+- Put normal delegation guidance in the generated Subagents prompt section and the spawn tool's
+  description. Keep plan instructions request-scoped. Do not expand the stable system prompt or add
+  a second capability, approval, storage or plan-file mechanism.
+
+## Consequences
+
+Normal runs receive concise advice at the point where profile choices are listed. Plan runs expose
+only eligible profiles and enforce the same restriction at both the gate and launch service. The
+terminal and hosts share the Harness behavior. Plan outcomes remain in the existing run history and
+PlanCard handoff; no protocol or stored-data migration is introduced.
+
+## Verification
+
+Harness tests cover normal prompt guidance, plan-mode profile eligibility and overrides, pre-approval
+refusals, child tool/plugin narrowing, plan inheritance and non-nesting. The versioned Evaluation
+suite adds one case where research delegation helps and one small case where it should be skipped.
+Live model comparisons require explicit authorization and credentials.

package/docs/decisions/ADR-0034-first-class-harness-terminal-commands.md

@@ -0,0 +1,25 @@
+# ADR-0034 — First-class Harness terminal commands
+
+Status: Accepted (PROP-0036, 2026-10-25).
+Supersedes: The plugin-command ownership rule of ADR-0031 only for the Harness terminal commands listed below.
+Related: [PROP-0036](../architecture/proposals/PROP-0036-first-class-harness-commands.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md),
+[ADR-0031](ADR-0031-plugin-command-owner-namespaces.md).
+
+## Context
+
+The required `subagents`, `history`, `doctor` and `worktrees` feature modules currently contribute terminal commands through `BuiltinPluginRegistry`. These features are not optional plugin toggles, and their terminal pages are first-class Harness surfaces. `/history` already means session-branch navigation, while `/mcp` already opens the Connections browser as a core command.
+
+## Decision
+
+The terminal's core command registry owns these canonical routes: `/doctor`, `/worktree`, `/trajectory [run-id]`, `/subagents` and `/agents`. `/history` and `/tree` continue to navigate session branches. `/mcp` and `/connections` continue to open Connections.
+
+The underlying required feature descriptors, tools, server methods and services remain registered by `BuiltinPluginRegistry`; they no longer own the terminal command metadata for these routes. Other plugin-owned built-in and Pi extension commands remain `/<owner-prefix>:<command>`, including the annotations namespace.
+
+For one release, the prior owner-qualified and `/plugin:<command>` routes for the promoted commands remain accepted as hidden compatibility aliases. They are omitted from help and completion. Core command names remain reserved under the normal collision policy.
+
+## Consequences
+
+The core terminal command table owns help, completion, highlighting and dispatch for the promoted routes. Plugin namespace collision checks and extension command ownership are unchanged. No server method, capability contract or stored data changes.

package/docs/decisions/ADR-0035-one-launch-path.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0035
+title: One launch and command contract for every front end
+status: Accepted
+created: 2026-11-19
+proposal: PROP-0040
+---
+
+# ADR-0035: One launch and command contract for every front end
+
+## Decision
+
+The owner approved Complete App parity and Solo tabs; accepted
+[PROP-0040](../architecture/proposals/PROP-0040-one-launch-path.md) records the Harness contract.
+The foundation owns one interactive launch policy, not a policy per renderer:
+
+- `Launch.standard` supplies shared role, working-folder and connection guidance. Hosts add only
+  attributed context, policy and declared add-ons through existing extension points.
+- `commands/registry.ts` defines core commands; `commands.list` adds effective plugin commands,
+  prompts and skills. Session history controls use `sessions.*`; live-session operations use
+  `SessionRunInput.command` and the normal run lifecycle.
+- Both surfaces load Harness-selected trusted resources and first-party hooks. Pi CLI built-ins
+  and the terminal-only question alias are excluded; attended planning uses `ask_user`.
+- Interactive defaults (roots, neutral variant scope and credential backend), shared session
+  references, browser schemas and frozen capability discovery belong to Harness. Explicit choices
+  and historical pins win. Existing profiles are never silently merged or credentials copied.
+- Optional `surfaces` metadata describes a host preference and a terminal fallback or unavailability;
+  it neither creates a plugin category nor grants permission.
+
+## Consequences and alternatives
+
+Separate front-end defaults and command implementations make identical labels promise different
+behavior. A shared contract permits richer presentation without a second loader, gate or state owner.
+Host-backed tools must refuse unsupported semantics honestly. Matching roots alone does not share
+credentials when the backends differ.
+
+This is an accepted design, not release or acceptance evidence. Shared-default adoption, actual
+runtime pins, native browser behavior, actionable command pages and cross-surface session discovery
+remain subject to implementation and both-surface acceptance. The [parity register](../parity.md)
+tracks source status and gaps; compiler-only equality tests do not establish runtime parity.

package/docs/decisions/ADR-0036-workspace-write-operation-boundary.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0036
+title: Enforce workspace writes at the filesystem operation
+status: Accepted
+created: 2026-10-26
+proposal: PROP-0039
+---
+
+# ADR-0036: Enforce workspace writes at the filesystem operation
+
+## Decision
+
+The Harness owns one filesystem-effect boundary shared by SDK sessions and the terminal. Each run
+pins a non-root `workspaceRoot`; model-controlled native writes and default-scope Bash are confined
+to that root by operating-system enforcement, not by prompt guidance or pathname checks alone.
+
+- Native `write` and `edit` calls revalidate the authorized canonical target at mutation and use
+  atomic replacement under an OS-enforced write scope. Outside file targets need a one-call
+  approval; replacing a directory entry rather than truncating an inode prevents an outside
+  hard-link alias from being changed.
+- Before default-scope Bash, Harness scans the workspace for regular-file inodes with links outside
+  it and blocks the command if the scan is incomplete or an external alias may exist. The OS
+  sandbox prevents the command from creating a cross-boundary hard link. On macOS it denies
+  hard-link creation entirely, including within the workspace.
+- Bash outside scope is an explicit `workspaceWriteScope: 'outside'` request, or terminal
+  `!outside <command>`. The complete quoted command is shown in approval details. Approval happens
+  before execution, is human-only and nonrememberable, and runs the exact command once. An
+  undersized terminal denies the request. stdout/stderr never proves a sandbox denial and never
+  triggers approval or replay.
+- Full Permission remains the existing explicit boundary bypass for eligible interactive runs; it
+  remains subject to hard policy, authorization, read-only, plan, unattended and refinement rules.
+- The filesystem root is not a valid workspace. A same-user peer process outside Harness remains
+  outside this boundary. Atomic replacement preserves ordinary file mode where possible but does
+  not guarantee ACL or extended-attribute preservation.
+
+## Rationale
+
+Canonical path checks alone do not contain effects through hard links and are vulnerable to
+pathname changes between authorization and mutation. Atomic replacement avoids writing through a
+shared inode, while an OS scope constrains the helper if a path changes. Shell output is controlled
+by the command and cannot authenticate a denial event; explicit pre-execution scope requests avoid
+replaying partial side effects and make broad writes an intentional decision.
+
+## Consequences and alternatives
+
+Workspaces with external hard-link aliases cannot use default Bash until repaired. Unsupported or
+incomplete sandbox enforcement fails closed. Outside writes remain possible through the explicit
+one-call approval path. A private copy-on-write workspace would also isolate against same-user peer
+processes, but changes visibility, writeback, conflict handling, metadata and performance; it remains
+out of scope unless that threat must be covered.
+
+This decision is not release evidence. See [PROP-0039](../architecture/proposals/PROP-0039-workspace-boundary-hardening.md),
+[the gate contract](../architecture/07-tools-and-gate.md), [terminal parity](../architecture/11-terminal.md)
+and [the release note](../releases/1.2.0.md) for implementation and validation status.

package/docs/decisions/ADR-0037-usage-ledger-and-provider-limits.md

@@ -0,0 +1,44 @@
+# ADR-0037: Usage analytics read a derived ledger; provider limits are read, never guessed
+
+**Status:** Accepted (2026-10-26)
+
+## Context
+
+Token and cost figures already reach the harness per model request, but only inside run events,
+and the index stores no usage. Provider limits have a schema and health rules but no producer.
+A person needs both answers without reading run folders, and a subscription's plan window must
+not be presented as a made-up percentage.
+
+## Decision
+
+- **The usage ledger is derived.** `usage_requests` and `usage_indexed` live in `index.sqlite`,
+  are written from `usage.updated` events, and are rebuilt from `runs/` like recall. No run file,
+  folder or schema changes.
+- **Analytics are bounded and scope-first.** One scope, one period, top-ten breakdowns, an
+  unpriced-request count, and cost estimates marked separately from provider figures.
+- **Limits have a stated source.** Response headers first (free and fresh), then a small registry
+  of documented provider endpoints read with the credential `Models.getAuth` resolves, then an
+  explicit unavailable reason. Undocumented endpoints are off unless `experimentalProbes` is on.
+- **Freshness is a person's choice.** Readings are cached for a configurable interval and
+  refreshed on page open or `r`, never by a background timer.
+- **One built-in plugin owns the capability.** `usage` contributes the methods and the two
+  namespaced terminal commands; the public method table still comes from `server/methods.ts`.
+
+## Consequences
+
+The index carries one more derived table set, with an append-only migration. `AccountState`
+gains an optional readout list and `Limit` optional absolute fields, both additive. A page open
+may make a read-only provider request with the account's existing credential; nothing is written
+to a credential file and no model request is made. Hosts can present the same methods later; the
+terminal is the reference surface.
+
+## Alternatives rejected
+
+Reading raw run logs per page (unbounded), a new data folder (duplicates derived data), scraping
+dashboards (no stable API), inventing percentages (misleading), background polling (surprise
+egress).
+
+## References
+
+[PROP-0042](../architecture/proposals/PROP-0042-usage-and-provider-limits.md), architecture pages
+02, 06, 08, 09, 10, 11, 12 and 14.

package/docs/decisions/ADR-0038-plan-bash-os-read-only.md

@@ -0,0 +1,29 @@
+---
+id: ADR-0038
+title: Plan-mode Bash is read-only by OS sandbox, not by command parsing
+status: Accepted
+created: 2026-10-26
+proposal: PROP-0043
+---
+
+# ADR-0038: Plan-mode Bash is read-only by OS sandbox, not by command parsing
+
+## Decision
+
+Plan runs may use Bash, and each call runs in the workspace sandbox's `read-only` scope: no writes
+except a discarded per-call temp folder, no network, no signals outside the sandbox, and (macOS) no
+mach services. Nothing widens that scope in plan mode. A small denylist of system-acting commands is
+checked by the gate as defence in depth only.
+
+## Rationale
+
+Whether a shell command writes cannot be decided reliably from its text; many read-looking commands
+can run others or write through flags. The Harness already depends on `sandbox-exec` and `bwrap` for
+the workspace boundary (ADR-0036), so the same mechanism with no write roots gives a kernel-enforced
+read-only guarantee at little cost.
+
+## Consequences
+
+Plans can inspect with real commands. Commands that need to write, such as most builds and tests,
+fail in plan mode. Platforms without a sandbox refuse plan Bash. See
+[PROP-0043](../architecture/proposals/PROP-0043-read-only-plan-bash.md).

package/docs/decisions/ADR-0039-progress-aware-stall-guards.md

@@ -0,0 +1,39 @@
+---
+id: ADR-0039
+title: Progress-aware stall guards and bounded plan research children
+status: Accepted
+created: 2026-10-27
+proposal: PROP-0046
+---
+
+# ADR-0039: Progress-aware stall guards and bounded plan research children
+
+## Decision
+
+Remove the global file-change/check no-progress trigger. Keep the targeted protections for repeated
+calls, repeated failing checks, per-path edit churn, compaction thrash, and the independent
+work-slice call/time budgets. Count edit churn only from successful native `edit`/`write` results
+with a path. A successful edit/write clears failed-check counts, exact Bash-check repetition counts
+and the pending nudge, but preserves edit counts and repeats of other calls; a passing check clears
+edit churn.
+
+Bound plan-research children with the configured work-slice policy without adding
+`checkpoint_write` or any other capability. When that tool is absent, a budget or stall refusal asks
+the child to stop and return partial findings; another tool call ends the reply, and the runner
+records an evidence-derived checkpoint. Children do not auto-continue. Plan-mode browser and
+connected-app restrictions remain unchanged.
+
+## Rationale
+
+Distinct reads are not evidence of a stall, and the former 25-call threshold imposed an arbitrary
+file/check-progress boundary. Tool results are the shared, observable signal for whether a native
+edit succeeded; treating failed or blocked attempts as edits would consume the churn allowance
+without changing code. Resetting check-retry state after a successful edit lets the same check run
+against changed input without weakening protection when code is unchanged. A derived checkpoint
+bounds read-only research children without widening their frozen capability set.
+
+## Consequences
+
+Long sequences of distinct reads are limited by the configured slice budget and targeted loop
+protections, not by missing file/check progress. No run-event schema, stored-data layout or server protocol changes are introduced; the terminal
+uses the same guard rules. See [PROP-0046](../architecture/proposals/PROP-0046-progress-aware-stall-guards.md).

package/docs/decisions/ADR-0040-architecture-change-workflow.md

@@ -0,0 +1,31 @@
+---
+id: ADR-0040
+title: Architecture changes do not require proposal approval first
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0040: Architecture changes do not require proposal approval first
+
+## Decision
+
+The architecture specification remains binding, and changes that alter its contracts, invariants,
+layer boundaries, extension points, or storage layout must update the affected specification pages
+in the same change. Such work does not require a proposal or user approval before implementation.
+
+Proposals remain optional design records. When used, they may be created before or alongside
+implementation and should be indexed and status-tracked. Add an ADR for a lasting architectural
+choice. Report existing code/spec drift and resolve relevant drift by updating both sides together
+within the requested scope.
+
+## Rationale
+
+A binding specification and same-change documentation keep implementation accountable to the
+architecture without making a separate proposal review a prerequisite to requested work. Optional
+proposals remain available when a design benefits from a written comparison or durable rationale.
+
+## Consequences
+
+Coding agents read the affected specification pages, implement the requested change, update the
+specification in the same change, and run relevant checks. Proposal status records design review or
+implementation progress but does not gate implementation.

package/docs/decisions/ADR-0041-plugins-hub-separation.md

@@ -0,0 +1,41 @@
+---
+id: ADR-0041
+title: Separate local plugin management from Community Hub discovery
+status: Accepted
+created: 2026-10-27
+proposal: PROP-0047
+---
+
+# ADR-0041: Separate local plugin management from Community Hub discovery
+
+## Decision
+
+- `/plugins` is the dedicated local installed-plugin manager: switching, code trust, settings, and
+  local package install, update and removal. It does not browse the public catalog.
+- `/hub` is a distinct public-catalog page. Its Catalog view shows Community entries across active
+  supported types; its Installed view shows receipts from every channel with the channel visible.
+  The broad `/harness` resource browser remains available.
+- Opening Hub shows cached or bundled entries first, then refreshes remotely. The page retains the
+  data origin, last-refresh time and any fallback/error status. Registry/document entries keep a
+  bounded payload Preview; Pi packages have no payload Preview.
+- A Hub-owned package cannot be silently floated by `plugins.update`. Removing it through
+  `plugins.remove` delegates to Hub's exact-receipt uninstall operation; Hub remains the writer of
+  its receipt and owned resources. Replacing it requires an explicit, exact catalog version.
+- Host presentations use the same filtering, refresh and receipt lifecycle while choosing their own
+  layouts. No new capability, loader, storage format or server response schema is introduced.
+
+## Rationale
+
+Local plugin management and public catalog discovery have different owners and different safety
+contracts. Separating the direct pages makes that visible without duplicating the services: local
+packages use the plugin manager, while Hub installs are pinned catalog releases with receipts. A
+Community-only catalog view also avoids presenting official items as community submissions, while
+retaining existing Official receipts for management.
+
+## Consequences
+
+The direct terminal and host routes have distinct screens, but `/harness` stays a broad resource
+browser. Catalog filtering is presentation-only; `hub.list` remains unfiltered for other callers.
+Existing receipts and plugin settings need no migration. The current public catalog has no
+Community Pi-package entry, so no Community plugin appears until a publisher adds one. See
+[PROP-0047](../architecture/proposals/PROP-0047-plugins-hub-separation.md).

package/docs/decisions/ADR-0042-windows-shell-without-sandbox.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0042
+title: Run Windows commands behind a per-call approval instead of a sandbox
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0042: Run Windows commands behind a per-call approval instead of a sandbox
+
+## Context
+
+Bash runs inside an OS write-boundary sandbox: `sandbox-exec` on macOS, bubblewrap on Linux
+(INV-GATE-3, INV-GATE-8). Windows has neither, and missing enforcement fails closed, so on Windows
+every Bash call, and every native `write` and `edit` (whose helper was launched through the same
+sandbox), failed before it started. The shell lookup also searched only `/bin/bash`. A harness
+installed from npm on Windows could not run a command or change a file.
+
+## Decision
+
+- **Shell.** On Windows, commands run in Git Bash (`%ProgramFiles%\Git\bin\bash.exe`,
+  `%ProgramFiles(x86)%\Git\bin\bash.exe`, then `bash.exe` on `PATH`, never the WSL launcher in
+  `System32`), otherwise in PowerShell (`pwsh.exe`, PowerShell 7 in Program Files, then Windows
+  PowerShell). The capability and tool keep the name `bash`, so capability sets, the gate, plan
+  lists and approvals are unchanged; the description names the shell.
+- **Bash.** Every Windows command takes the existing `outside` path: a human-only one-call approval
+  or an eligible Full Permission answer, then it runs once unconfined. Remembered tool grants never
+  answer it. Plan-mode (read-only) Bash is refused on Windows.
+- **Write and edit.** On Windows the atomic helper runs with Node directly. The target is still
+  canonicalized, authorized, revalidated, and replaced by rename; outside targets still need their
+  one-call approval. In-workspace writes do not ask.
+- `/doctor` reports the Windows shell as a warning that names it and the approval rule.
+
+## Consequences
+
+- The harness works on Windows right after `npm install`, with no Git or native helper required.
+- Windows commands are unconfined once approved. The guarantee comes from the person, not the OS.
+- On Windows, a junction or symlink swap between the write check and the rename is not prevented
+  by the OS. Atomic replacement still keeps a write from going through a hard-link alias.
+- A real Windows sandbox (restricted token and ACLs through a native helper) would let Windows use
+  the macOS/Linux rules again. It is not built.

package/docs/decisions/ADR-0043-parents-continue-stopped-subagents.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0043
+title: A parent continues its stopped subagents; the monitor shows the main agent and survives reopening
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0043: A parent continues its stopped subagents
+
+## Decision
+
+- `spawn_subagent { continue: <runId> }` (and `subagents.spawn { continue }`) continues a child that
+  stopped before finishing (`interrupted` or `failed`, with saved history). It is a new child run
+  with `continueFrom`. It reopens the first link's history folder
+  (`<parent sessionDir>/subagents/<first child run id>`) and keeps the earlier child's session id,
+  profile, title, goal, account, variant version and frozen capability set. That set must still lie
+  within the parent's ceiling; `agent` and `tools` are refused with `continue`. The id may name any
+  link of a chain: the newest link is the one continued, and an active or completed newest link is
+  refused.
+- The model decides. A subagent never continues itself, and a restarted harness never restarts
+  model work (INV-RUN-4). Children an earlier reply left stopped are delivered **before** the next
+  reply's first request: a hidden `xingular-subagent-results` message with a receipt, which says
+  each child can be continued. A stopped child that has a continuation is reported through that
+  continuation instead.
+- Recovery of an earlier parent's children is keyed on the native history branch: the owner
+  marker, the same native history id, account, agent, project and working folder. The Harness
+  session id is not compared, because a host may give each launch of one conversation a new one.
+- `main` is a reserved profile name. The terminal monitor projects the parent run itself as a
+  `main` row: account, model, effort, usage, activity and todo counts, like a child. The
+  `/subagents` page shows it pinned first; the rows under the status line omit it.
+- The terminal marks every turn's run on the branch (`xingular-subagent-owner`). When a
+  conversation opens with no run active, it rebuilds the monitor from the branch's latest parent
+  run in that folder and its descendants, by folding their saved events. The rows keep their final
+  status until the next run begins.
+- Run records carry the launch `model` and `effort` (the opened session's model supersedes the
+  selection), so a rebuilt row can show them.
+
+## Rationale
+
+Esc on a parent interrupts every child, and until now the next turn was told to start them again.
+That lost work that was saved on disk. Reopening a child's own history keeps every pin a run
+already has, so no capability or account can change, and leaving the choice to the model keeps
+INV-RUN-4.
+
+## Consequences
+
+The monitor stays a private, read-only terminal projection; no event or public method is added.
+Records written before this change have no `model` or `effort`, and their rebuilt rows show `—`.
+A person cannot continue a child from the page directly; they ask the parent.

package/docs/doctor.md

@@ -8,10 +8,23 @@ provider requests, token refreshes, browser launch, permission prompts or comput
 pass does not establish live connectivity. Other accounts show their saved status and timestamp.
 Providers without diagnostics report unverified. Disabled capabilities are not failures.
 
+The shell check reports which `bash` the session would run and whether the platform's
+write-boundary sandbox (sandbox-exec on macOS, bubblewrap on Linux) is installed, because a missing
+backend stops every Bash call before the command starts. It runs nothing. On Windows it reports a
+warning naming the shell (Git Bash or PowerShell) and that each command asks for approval, because
+Windows has no write-boundary sandbox; the live shell check reports unverified there, since a
+command would need a person to approve it.
+
 Press `l` to choose live checks, then review the account/model, destinations, possible charges and
 isolation notice. The model check makes one synthetic request with at most 64 output tokens;
 usage appears on a separate diagnostic run. Web checks fetch example.com and search for “example
-domain”. MCP checks connect/list only. Browser checks use a disposable headless profile and an
+domain”. The shell check runs one fixed command written by the harness (`printf`) in the working
+folder through the same root, hard-link scan and write-boundary sandbox a normal Bash call uses, and
+reports only the exit status: no model input is sent, no file is written and no network request is
+made. A diagnostic never widens the boundary, so Full Permission cannot change its result; when the
+boundary refuses before the shell starts (for example a hard-link alias in the workspace), the
+finding is blocked with that reason instead of claiming the shell is broken. MCP checks
+connect/list only. Browser checks use a disposable headless profile and an
 offline synthetic page; configured CDP attachment is blocked. Computer input is blocked unless the
 host supplies a disposable diagnostic surface; the current desktop host supplies readiness only.