@xingular/harness 2.0.0 → 2.0.1-unstable

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,35 @@
+# ADR-0032 — Rehydrate bounded run checkpoints after compaction
+
+Status: Accepted (PROP-0033, 2026-10-25). Delivery superseded in part by
+[ADR-0067](ADR-0067-cache-stable-compaction-checkpoint.md): the checkpoint arms only for a compaction
+during its run and sits, unchanged, right after the summary.
+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,43 @@
+---
+id: ADR-0039
+title: Progress-aware stall guards and bounded plan research children
+status: Accepted
+superseded_by: ADR-0053 (targeted protections only)
+created: 2026-10-27
+proposal: PROP-0046
+---
+
+# ADR-0039: Progress-aware stall guards and bounded plan research children
+
+The targeted repeated-call, repeated-failing-check and edit-churn protections decided here are
+superseded by [ADR-0053](ADR-0053-no-repeated-work-guard.md); the rest of the decision stands.
+
+## 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/decisions/ADR-0044-annotations-pending-or-sent.md

@@ -0,0 +1,24 @@
+---
+id: ADR-0044
+title: An annotation is pending or sent; the agent's page-note tools are read-only
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0044: An annotation is pending or sent
+
+## Decision
+
+- Every annotation a person makes in the inspector with a session is shared with that session at
+  once and is **pending** until sent. There is no queue to add to or take out of, and no "fixed"
+  state. Records written before keep working: `queued` reads as `pending`, `fixed` as `sent`.
+- The popover has two actions, Annotate and Annotate & send. A send sends every pending note of
+  the session as one message, optionally followed by the person's request (`/annotate:submit`).
+- `page_notes_mark_fixed` is removed. The agent reads annotations; only the person resolves them.
+- A held-back send is retried while the session is still busy after a run ends.
+- Built-in plugin commands may be `rootOnly`, so a namespace root is not listed twice.
+
+## Why
+
+People found three actions, a queue and a fix status too much to control, and the extra state is
+what made sends fail silently. See [PROP-0048](../architecture/proposals/PROP-0048-simple-annotate.md).

package/docs/decisions/ADR-0045-default-plugin-authoring-skill.md

@@ -0,0 +1,9 @@
+# ADR-0045: Release-owned plugin-authoring skill
+
+## Decision
+
+Ship plugin-authoring guidance as an on-demand Harness resource, selected for both structured and terminal sessions without changing variant versions. A pinned variant's skill of the same name takes precedence. The release supplies the resource in the package; the normal skill loader and Pi resource loader expose it. The guidance grants no trust or permissions.
+
+## Consequences
+
+Existing variants receive the guidance without migration. Its release-owned content can change with the installed Harness version rather than with a variant fingerprint. Only its name and description are advertised until requested; the body does not enter the always-on variant text. Proposal creation and hash-bound review are separate from the skill and are recorded in [ADR-0046](ADR-0046-hash-bound-plugin-proposals.md).

package/docs/decisions/ADR-0046-hash-bound-plugin-proposals.md

@@ -0,0 +1,20 @@
+# ADR-0046: Hash-bound plugin proposal review
+
+## Decision
+
+Keep model-authored plugin proposals as inert, bounded text in the data root. The model may create
+one through the gated `plugin_propose` tool; only a trusted caller may accept or reject it. Both
+decisions require the hash of the current revalidated preview. The hash binds the name, description,
+generated manifest and sorted file contents, not a person's identity or an authorization grant.
+Acceptance publishes a new package switched off, does not run its code or grant trust, and refuses
+an existing package name or identical already-trusted package code. Normal attachment, code trust,
+capability and approval checks remain separate.
+
+## Consequences
+
+Reviewers can inspect exactly the content a decision names, and stale or already-decided reviews
+are refused. Text can itself contain hostile instructions and may load when enabled without code
+trust; review must cover every contribution. Proposal records, including rejected ones, remain in
+the data root; device-local code trust remains in the state directory. This decision does not claim
+that a terminal or host review UI exists. See [06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[10 Server protocol](../architecture/10-server-protocol.md), and [PAR-017](../parity.md#gaps).

package/docs/decisions/ADR-0047-links-open-with-the-os-handler.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0047
+title: A link a person clicks opens with the system's own handler, through one allowlist
+status: Accepted
+created: 2026-11-20
+---
+
+# ADR-0047: A link a person clicks opens with the system's own handler
+
+## Decision
+
+- `core/links.ts` holds the one link policy: `linkTarget` classifies a target without touching the
+  filesystem (`http`/`https`, `mailto`, `file`, an absolute path, or a relative path under a
+  supplied base), and `openableTarget` checks what a path names before anything is launched.
+- A path may be opened only when it is a regular file or a directory, is not an application bundle
+  or an installer, is not a launchable script kind (`.command`, `.sh`, `.bat`, `.pkg`, `.dmg`,
+  `.app`, …), and has no executable bit set. The last two matter because `xdg-open` runs an
+  executable file and `open` launches a bundle.
+- The address reaches `open` (macOS), `xdg-open` (Linux and the BSDs) or `rundll32.exe
+  url.dll,FileProtocolHandler` (Windows) as one argument, never through a shell.
+- `links.open` is a server method, so a host presents the same capability, and the terminal is the
+  reference surface: hovering a link recolours it, and the gesture the platform uses opens it —
+  Ctrl+click where a terminal reports the modifier, and the primary click on macOS, whose ⌘ the
+  terminal mouse protocol cannot carry. The opener is `HarnessOptions.linkOpener`, so a host with
+  its own native opener replaces the spawn and keeps the policy.
+- A link is a person's action. Nothing here is in `HARNESS_TOOLS`, so the gate, standing approvals
+  and redaction are not involved, exactly as with `variants.save`.
+- Both front ends show the hover state: the terminal repaints the hovered link's spans in
+  `theme.linkHover`, and the App uses the shared `--link-hover` token on `a:hover`. The App's
+  modifier is the platform's own: ⌘ on macOS, Ctrl elsewhere.
+
+## Rationale
+
+The terminal opened web links only, and the App opened web pages and stored documents in its
+sidebar while silently swallowing everything else — `mailto:`, folders, relative paths and unknown
+kinds. The allowlist existed three times (a terminal module, the App's TypeScript, and the App's
+Rust), which is the drift the parity rules exist to prevent. One policy in the Harness, used by
+both surfaces, is the smallest thing that makes a link behave the same everywhere.
+
+## Consequences
+
+A refused link is reported, never ignored: the terminal posts a notice and the App reports an
+error. Opening a document still hands its bytes to whichever application the system has associated
+with that kind, which is inherent to the request; the deny list and the executable-bit check are
+the boundary, not a sandbox. A host that wants different kinds to open replaces `linkOpener`, and
+an architecture change would be needed to let a model open a link on its own, because that would
+put an operating-system action inside the gate's reach.