@xingular/harness 1.0.0 → 1.2.0

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/doctor.md

@@ -15,11 +15,17 @@ domain”. MCP checks connect/list only. Browser checks use a disposable headles
 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.
 
+The report keeps mode, progress, account/model and status counts visible above the findings. Wide
+layouts use aligned Status, Check, Category and Verification columns; evidence and any next step
+appear beneath each finding. Narrow layouts stack those fields. Status colors follow the active
+theme: pass is green, warning/blocked amber, fail red, disabled dim and unverified muted.
+
 `r` refreshes local readiness, `t` retries a selected local check, `c` cancels, and Escape closes
-and cancels pending work. Completed findings survive cancellation. Every finding includes evidence
-and, where useful, a next step. Doctor never signs in, switches accounts, installs, grants access,
-or repairs settings. Findings and jobs are retained in memory until shutdown; live run records
-and usage remain in normal Harness storage.
+and cancels pending work. Use Up/Down to scroll by line, PgUp/PgDn or the mouse wheel to scroll by
+page, and Home/End to jump to the first/last finding. Completed findings survive cancellation. Every finding includes
+evidence and, where useful, a next step. Doctor never signs in, switches accounts, installs, grants
+access, or repairs settings. Findings and jobs are retained in memory until shutdown; live run
+records and usage remain in normal Harness storage.
 
 ## Embedding