@xingular/harness 0.1.7 → 1.1.1

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -0,0 +1,70 @@
+---
+id: ADR-0003
+title: Shared asynchronous subagents with native-history delivery receipts
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: ADR-0002
+---
+# ADR-0003 — Shared asynchronous subagents with native-history delivery receipts
+
+## Context and decision
+
+The owner selected reliable delivery, asynchronous spawn/wait, and one SDK/terminal/App API after
+studying OMP. They chose attached children joined before the parent finishes, async spawning by
+default, availability for every interactive caller within its capability ceiling, and recovery
+only when the user explicitly resumes. This supersedes the blocking tool contract in ADR-0002.
+
+`harness.subagents` owns spawning, selective waits and results. SDK and terminal adapters register
+live, frozen parent context with it; no model argument supplies caller, account or replacement
+launch metadata. The terminal adapter uses its private control key. Children use normal Harness
+sessions, isolated accounts, fresh history, existing gates and capability intersection. The old
+`sessions.spawnSubagent` entry point forwards to the service for compatibility.
+
+A parent reserves each child in `runs/<parent>/subagents.json` through the run store before startup.
+A native branch owner marker is persisted before a real parent accepts spawns. Results are delivered
+at turn boundaries or through explicit blocking tools. Native messages and tool results carry typed
+receipts; only receipts on the selected branch acknowledge delivery. Constructing a delivery draft
+never acknowledges it. Large batches acknowledge only the included children. The final settlement
+hook joins children and injects remaining results; an adapter verification guard refuses successful
+completion if persisted native history still lacks a result. The stable system prefix is unchanged.
+
+On explicit resume, matching owner markers, caller/account/folder/native identity and run lineage
+restore undelivered results. A startup reservation that never opened becomes an interrupted run.
+Existing startup recovery interrupts orphaned active runs. Neither recovery path restarts model
+work. Cancellation settles approvals and questions before waiting for SDK abort, preventing blocked
+child interactions from deadlocking parent shutdown.
+
+Interactive sessions enable the tools by default, `null` disables them, and explicit capability
+sets can exclude them. Unattended callers remain off unless the host explicitly enables them.
+Default nesting remains one, with a maximum of three. There is no new scheduler, reusable-worker
+lifecycle, model routing, workspace isolation system, concurrency cap or family budget here.
+
+## Alternatives and consequences
+
+A tool-owned launcher leaves terminal and SDK behavior divergent. An in-memory delivery flag loses
+results across restart; searching prose for run IDs confuses mentions with delivery. Native-history
+receipts identify persisted context without adding a second acknowledgement store. Run records
+remain the outcome source of truth, while the parent file preserves startup reservations.
+
+The App owns organization delegation and resolves native ancestry for thread routing, tools,
+isolation and connections. Its existing work-budget accounting includes native descendants. Harness
+learns no organizational role or application concept. Native completion records execution outcome;
+it does not certify the child's findings or artifacts.
+
+## Evidence and limits
+
+`subagentService.test.ts` covers selective waits, foreign handles, cancellation, bounded batches and
+recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async delivery, inline
+receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
+terminal socket, private controls, native execution and child decision routing. RPC and App host
+regressions cover protocol shapes and ancestry. Tests use disposable storage without external
+model requests. These changes shipped in `@xingular/harness` 2.0.0 (commit `44471bc`); release does not imply live-provider acceptance.
+
+Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
+build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
+and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
+pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
+user-data-root testing was performed.
+
+Release verification on 2026-10-18: npm 10 clean install, typecheck, 515 tests (two skipped), build and standalone proof passed. GitHub CI passed on Ubuntu and macOS, and the npm publish workflow released version 2.0.0 with provenance. No live provider requests were made during release verification.

package/docs/decisions/ADR-0004-fullscreen-terminal-layout.md

@@ -0,0 +1,50 @@
+---
+id: ADR-0004
+title: Fullscreen terminal layout with a fixed dock
+status: superseded
+created: 2026-10-18
+updated: 2026-10-21
+supersedes: none
+superseded_by: ADR-0006
+---
+# ADR-0004 — Fullscreen terminal layout with a fixed dock
+
+## Context and decision
+
+The owned terminal drew its transcript and composer as one flowing list on the main screen. With a
+short transcript the composer sat under the last line and moved down as the transcript grew. Harness
+also kept its own scroll offset, mouse regions and paging, which duplicated the viewport Pi already
+provides in fullscreen.
+
+Harness now uses Pi's fullscreen renderer by default. The welcome and transcript form a scroll view
+that fills the terminal; the dock (working line, queue and notices, widgets, editor and status band,
+footer) sits fixed below it. Pi's `tuiMode`, `fullscreenScrollbar`, `fullscreenWheelScrollLines`,
+`fullscreenCopyOnSelect` and `fullscreenExitOutput` settings are read from the account and honoured.
+`tuiMode: "regular"` keeps the flowing layout on the main screen. When fullscreen ends with
+`fullscreenExitOutput: "transcript"`, the rendered conversation is copied into the normal scrollback.
+
+## Consequences
+
+- While fullscreen is running, the transcript is not in the terminal's scrollback. Mouse capture is
+  on, so terminal drag-selection gives way to the application's selection, which copies on release.
+  These are Pi's defaults and remain changeable in settings.
+- Harness no longer owns scroll state, wheel handling or paging. Those come from Pi's viewport and its
+  `tui.altScreen.*` bindings, and the keyboard list shows the scroll keys only in fullscreen.
+- Regular mode has no Harness-managed scroll position; scrolling there belongs to the terminal.
+- When the screen is short, a long notice shows its first rows and scrolls for the rest. The prompt
+  and status are never clipped; the head of a notice stays readable, so the newest line of a long
+  list may need a scroll.
+- Only `transcript` exit output is implemented. Other values write nothing on exit.
+
+## Alternatives considered
+
+Padding the main-screen output to the terminal height also keeps the composer on the last rows for a
+short transcript. It keeps native scrollback, but Harness would still own its scrolling and mouse
+handling, and the composer would scroll away with the terminal's scrollback once the transcript
+overflowed. That was rejected because it keeps the duplicated code this change removes.
+
+## Evidence
+
+The layout is covered by `src/terminal/tui/screen.test.ts`: the dock stays on the last rows as the
+transcript grows and scrolls, regular mode flows in order, and the exit copy is written with its styles
+reset. The PTY verification of the built CLI is recorded in [the terminal reference](../terminal-tui.md).

package/docs/decisions/ADR-0005-app-provided-oauth-clients.md

@@ -0,0 +1,54 @@
+---
+id: ADR-0005
+title: Application-provided OAuth clients for connected apps
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: none
+---
+# ADR-0005 — Application-provided OAuth clients for connected apps
+
+## Context and decision
+
+Every remote connected app so far authenticated one of two ways: the server registers this app
+dynamically (RFC 7591), or the person registers a client with the provider and pastes its ID and
+secret into Connections. Google's Workspace MCP servers support neither in practice: they have no
+dynamic registration, and requiring every person to create a Google Cloud project before connecting
+Gmail is not a product.
+
+A connection's `oauthClient` now has a third value, `app`: **the application supplies the client**.
+The host does so through one extension point on the harness:
+
+```ts
+export interface AppOAuthClients {
+  ids(): string[]
+  get(catalogId: string): Promise<{ clientId: string; clientSecret?: string } | null>
+}
+```
+
+`HarnessOptions.oauthClients` carries it. Only a connection whose `catalogId` appears in `ids()` can
+use it — a hand-typed connection, a Hub connector recipe, and a plugin template cannot, because none
+of them can name a client the application actually holds. `connections.appClients` reports the ids so
+an application can offer only the connectors it can actually sign in for.
+
+The client is resolved inside `Connections.oauthLoad` and placed in the OAuth state as
+`staticClient`, exactly where a user-registered client goes. `oauthSave` already strips
+`staticClient`, so the client is never written to `connections.json` or the secret store; it is
+re-resolved on each load. Refresh tokens continue to be stored per connection.
+
+## Consequences
+
+- The harness learns no product concept: it knows a catalog entry id, a client, and a sign-in. Which
+  entries an application can serve is entirely the host's answer.
+- A build without a client is a first-class state, not an error: `ids()` is empty, `signIn` refuses
+  with "This connector has no app sign-in in this build", and the application hides those catalog
+  entries instead of offering a dead end.
+- A client secret in a distributed desktop build is extractable, so it is treated as public. The real
+  controls stay Google's consent screen, the requested scopes, and the tool approval gate.
+- One client can serve several catalog entries (five Google servers, one client). Each entry is still
+  its own connection with its own tokens, so signing in to one does not authorize another.
+- The per-user path is untouched: `oauthClient: 'user'` still stores a person's own client in
+  Keychain, and it remains the only route for providers or accounts an application cannot pre-register
+  for.
+- Google's Developer Preview terms, app verification and CASA assessment for restricted scopes are
+  outside this decision; they decide who can use the shipped client, not how it is delivered.

package/docs/decisions/ADR-0006-opentui-only-terminal.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0006
+title: OpenTUI is the only terminal frontend
+status: accepted
+created: 2026-10-21
+updated: 2026-10-21
+supersedes: ADR-0004
+---
+# ADR-0006 — OpenTUI is the only terminal frontend
+
+## Context and decision
+
+Harness carried two terminal frontends: the owned Pi terminal and an OpenTUI/Solid frontend behind
+`XINGULAR_HARNESS_TUI=opentui`. The split kept two launch paths, two input and rendering stacks, and
+a fallback that let the terminal start without the OpenTUI build. The requested terminal is the
+OpenTUI one, so the second frontend no longer earns its maintenance and test surface.
+
+`Terminals.prepare()` now always returns Bun with `--conditions=browser` and
+`dist/terminal-opentui.js`. The harness no longer reads `XINGULAR_HARNESS_TUI`, the CLI no longer
+has the internal `terminal-frontend` command, and the legacy frontend modules are removed.
+`TerminalAssets.openTui` is required. `XINGULAR_HARNESS_BUN` still selects the Bun executable.
+
+Bun 1.3.14 or newer is required to build and run the terminal. `npm run build:tui` fails with a
+clear error when Bun is unavailable instead of writing a placeholder or leaving the old frontend.
+`HarnessOptions.piProgram` remains accepted for source compatibility but is ignored.
+
+## Consequences
+
+- There is one launch path, one frontend test surface, and no silent fallback to a different UI.
+- A machine that installs the package must have Bun; Node remains the runtime for the CLI, server,
+  accounts and Pi sessions.
+- The OpenTUI page dialogs, composer, Bash mode and palette are the shipped presentation; the
+  fullscreen layout in ADR-0004 is history.
+- Embedders that construct `TerminalAssets` themselves must provide `openTui`.
+
+## Alternatives considered
+
+Keeping the legacy frontend as an unreachable fallback preserves dead code and two mental models
+for input, rendering and exit behavior. Keeping OpenTUI opt-in preserves the split the change was
+asked to remove. Both were rejected.
+
+## Evidence
+
+Unit and integration tests construct launches and exercise the shared runtime without a real
+provider request. A PTY probe of the standalone command with `XINGULAR_HARNESS_TUI` unset renders
+the OpenTUI home and exits 0; the capture and build hashes are in
+[the console evidence](../evidence/terminal-2026-10-20-console-tui/default-opentui-probe.json).

package/docs/decisions/ADR-0007-reporting-section.md

@@ -0,0 +1,33 @@
+---
+id: ADR-0007
+title: A fixed Reporting section shapes the final reply
+status: superseded
+created: 2026-10-21
+updated: 2026-10-21
+superseded_by: ADR-0008
+---
+# ADR-0007 — A fixed Reporting section shapes the final reply
+
+## Context and decision
+
+Nothing in the compiled prompt said how a run should end, so final replies buried the answer and
+rarely listed files changed, blockers or unverified work. Other harnesses (opencode, omp, Claude
+Code, Codex CLI, kimi-cli) keep final-answer rules in their fixed prompt text; the comparison is in
+[PROP-0001](../architecture/proposals/PROP-0001-reporting-section.md).
+
+The compiler now adds a harness-owned `reporting` section to every pack (`SECTION_ORDER.reporting`
+95, after `tools`; text `REPORTING_GUIDANCE` in `src/prompt/compile.ts`; budget 2,000, never cut,
+never dynamic). It asks for the answer first, then only the parts with content — Files, Blocked,
+Worth a look, Check by hand, Next steps — and Markdown tables where several items share fields. A
+format the person, the application or the current mode asks for takes precedence.
+
+## Consequences
+
+- Every session and every application gets the same reply shape without configuration.
+- The stable prefix changes once; existing sessions miss the provider cache once after upgrade.
+- The model writes the file list. A harness-built list from run events remains possible later.
+
+## Alternatives considered
+
+Default tree text (old trees never get it, refinement could drop it); an application section
+(every application repeats it, the terminal has none); doing nothing. All rejected.

package/docs/decisions/ADR-0008-flexible-reporting-guidance.md

@@ -0,0 +1,38 @@
+---
+id: ADR-0008
+title: Flexible reporting guidance with optional human inspection
+status: accepted
+created: 2026-10-21
+updated: 2026-10-21
+supersedes: ADR-0007
+---
+# ADR-0008 — Flexible reporting guidance with optional human inspection
+
+## Context and decision
+
+ADR-0007 added stable, harness-owned guidance for final replies, but its fixed heading list could
+produce generic sections and did not clearly identify when a person must perform a check the agent
+could not perform or observe. The user accepted [PROP-0004](../architecture/proposals/PROP-0004-flexible-reporting-guidance.md).
+
+Keep the `reporting` section in the stable system prompt and lead with the outcome, but do not
+require a fixed set of headings. Use only structure that helps explain the work. **Need human
+inspection** is an optional heading for a concrete verification that requires a person because the
+agent could not perform or observe it; state what remains unverified, why, and the specific check
+to make. Do not use it for checks already performed or generic risks. Report only checks actually
+run and their results.
+
+## Consequences
+
+- Every session receives the same concise, flexible reporting guidance.
+- The stable prefix changes once; existing sessions may miss the provider cache once after upgrade.
+- No stored data or server protocol changes. Applications bundling the harness need a rebuild to
+  receive the updated prompt.
+- Cache behavior is measured only with real application requests and the account owner's
+  permission, as required by INV-PRM-8.
+
+## Alternatives considered
+
+- Keep the fixed headings: rejected because they can add generic structure and mislabel follow-up.
+- Remove all guidance about unverified work: rejected because concrete human checks could be omitted.
+- Make **Need human inspection** mandatory: rejected because most tasks do not require a person to
+  perform a check.

package/docs/decisions/ADR-0009-xharness-command.md

@@ -0,0 +1,39 @@
+---
+id: ADR-0009
+title: Publish the Harness CLI as xharness
+status: superseded
+created: 2026-10-22
+updated: 2026-10-24
+related: [PROP-0005]
+supersedes: null
+superseded_by: ADR-0024
+---
+
+# ADR-0009 — Publish the Harness CLI as xharness (superseded)
+
+## Context and decision drivers
+
+The published package used `xingular-harness` as its executable, while the desired short command is
+`xharness`. The CLI already starts the Harness-owned OpenTUI terminal when invoked without a
+subcommand, so the frontend and session runtime need no changes. The npm registry's latest release
+is `3.0.0`; replacing the published executable is a breaking change.
+
+## Decision
+
+Publish `@xingular/harness` `4.0.0` with one binary, `xharness`, mapped to `dist/cli.js`. Do not
+ship `xingular-harness` as a compatibility alias. Keep the package name, `terminal` alias, host
+subcommands, data/state directory names, and `XINGULAR_HARNESS_*` environment variables unchanged.
+
+## Consequences
+
+- Users and scripts that invoke `xingular-harness` must migrate to `xharness`.
+- Running `xharness` with no command opens the existing OpenTUI terminal.
+- No account, data, or state migration is required.
+- The release requires Node 22.19+ and Bun 1.3.14+ for the standalone terminal build/runtime.
+
+## Implementation and verification
+
+- The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
+- CI, the packed-tarball smoke test and the npm publication blocker are recorded in
+  [PROP-0005](../architecture/proposals/PROP-0005-xharness-cli-name.md). The executable-name decision
+  is superseded by [ADR-0024](ADR-0024-xagent-command.md).

package/docs/decisions/ADR-0010-lessons-in-the-wiki.md

@@ -0,0 +1,31 @@
+---
+id: ADR-0010
+title: Lessons from ordinary runs live in the Wiki, not in trees or the refinement library
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+# ADR-0010 — Lessons from ordinary runs live in the Wiki
+
+## Context and decision
+
+[PROP-0008](../architecture/proposals/PROP-0008-lessons-from-runs.md) adds an opt-in reflection
+after a finished run. The harness already has three places that hold what agents learn: the
+harness tree (c3 memory, instructions), the refinement experience library (whole trees plus a
+lesson, per scope and area), and the Wiki (reference notes).
+
+Lessons from ordinary runs go to the Wiki, under `library/lessons/`, with refinement's lesson
+shape (cue, lesson, evidence, confidence, or nothing).
+
+- The tree changes only through refinement and a person's `adopt`. A lesson from one run is not
+  enough evidence to change instructions every later run receives.
+- The refinement library stores whole trees keyed by task area; an ordinary run has neither.
+- The Wiki is reference material by contract (INV-MEM-1): an agent reads a lesson when it searches,
+  and a person can read, edit or delete it like any note. A lesson that keeps proving itself is
+  evidence for a later refinement, which is where behaviour changes.
+
+## Consequences
+
+- Lessons are visible and editable through every Wiki surface, versioned, and announced to hooks.
+- They do not reach the stable prefix; only a count reaches the dynamic `wiki` pointer.
+- The lesson shape is shared with refinement (`parseExperience`), so the two stay comparable.

package/docs/decisions/ADR-0011-foundation-and-variants.md

@@ -0,0 +1,28 @@
+---
+id: ADR-0011
+title: The harness is a fixed foundation running a mutating variant
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+# ADR-0011 — The harness is a fixed foundation running a mutating variant
+
+## Context and decision
+
+[PROP-0009](../architecture/proposals/PROP-0009-foundation-and-variants.md). The harness lets a
+running host improve the harness itself, so two kinds of part must be told apart at all times: the
+ones that never move during that improvement, and the ones that are meant to.
+
+We call the first the **foundation** and the second a **variant**. A variant is one whole c1–c8
+tree for one scope. The foundation decides what a variant may contain and how it runs; a variant
+decides what the agent is told and may load. Refinement edits a copy of a variant, and only a
+person's `adopt` makes it the head.
+
+## Consequences
+
+- Specs, code, storage and the protocol use the two words (`variants/`, `variants.*`,
+  `VariantChoice`). `INV-FND-1` and `INV-FND-2` state the one-way rule.
+- The same split names the prompt-level design in DESIGN-0001 (foundation text and the adapting
+  surface).
+- Breaking release (5.0.0). Stored data is migrated on `open`.
+- The improver prompts keep the Harness² paper's wording, so the method is unchanged.

package/docs/decisions/ADR-0012-native-session-names.md

@@ -0,0 +1,34 @@
+---
+id: ADR-0012
+title: Agents name their own native Pi sessions
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+related: [PROP-0010]
+---
+
+# ADR-0012: Agents name their own native Pi sessions
+
+## Context
+The terminal already supports manual native Pi session names. The user requested agent
+creation and revision, with a six-word limit and a name after the working metrics, in all
+Harness execution paths. The user approved this implementation plan.
+
+## Decision
+A shared foundation tool binds to the current native session and uses Pi session-info
+history as the only writer and source of truth. The normal gate and capability selection
+apply. Plan mode permits naming as session metadata maintenance. Fixed tool guidance asks
+the agent to name work early and rename on objective changes; no changing name enters the
+system prompt. The terminal refreshes through the existing native metadata event.
+
+## Alternatives
+A separate model call adds latency and cost. Separate title storage duplicates native
+metadata and requires synchronization. Manual-only names do not meet the requested behavior.
+
+## Consequences and evidence
+No migration or new host RPC is needed. The agent chooses when to invoke the tool, so
+actual naming frequency depends on model compliance. Manual names can be revised by the
+agent. Tests in `src/tools/sessionName.test.ts`, `src/sessions/sessions.test.ts`, and the
+terminal lifecycle, runtime, working-line and application tests cover the contract.
+Implementation and verification status are tracked in
+[PROP-0010](../architecture/proposals/PROP-0010-session-names.md).

package/docs/decisions/ADR-0013-doctor.md

@@ -0,0 +1,27 @@
+---
+id: ADR-0013
+title: Evidence-based diagnostics with opt-in live probes
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+
+# ADR-0013 — Evidence-based diagnostics with opt-in live probes
+
+## Context and decision
+
+[PROP-0011](../architecture/proposals/PROP-0011-doctor.md) records the user-approved plan.
+A configured tool or locally available model is not evidence of a successful request.
+`/doctor` therefore checks readiness offline and labels live verification separately.
+
+The foundation owns bounded, cancellable diagnostic jobs and validated findings. Tool-provider
+callbacks supply backend-specific evidence using the existing extension point. Live tool calls
+use the production gate and current capabilities. One synthetic model request uses the selected
+account's Pi runtime and records usage in a separate diagnostic run.
+
+## Consequences
+
+Existing providers remain compatible. Unsupported checks are unverified, disabled capabilities
+are disabled, and permission or isolation constraints are blocked. No diagnostic changes an
+account, configuration or permission. Browser tests have a disposable profile and offline page;
+computer input tests require a host-supplied disposable surface. No live tests run automatically.

package/docs/decisions/ADR-0014-public-release-baseline.md

@@ -0,0 +1,22 @@
+---
+id: ADR-0014
+title: A compiled public SDK and explicit 1.0.0 baseline
+status: accepted
+created: 2026-10-22
+updated: 2026-10-22
+---
+
+# ADR-0014 — A compiled public SDK and explicit 1.0.0 baseline
+
+The user approved [PROP-0012](../architecture/proposals/PROP-0012-release-baseline.md) through the
+release implementation plan. Keep @xingular/harness and the then-current `xharness` executable, use
+Apache-2.0 for original code, publish compiled ESM/declarations, and preserve upstream notices and
+historical releases. The executable-name portion was superseded by [ADR-0024](ADR-0024-xagent-command.md); the other release-baseline decisions remain.
+
+Generic isolated browser execution belongs in the foundation; App browser presentation, tab
+sharing and OS/computer integration remain with the host. No application concept or object is
+introduced into the Harness. Provider diagnostics continue through the existing tool surface.
+
+The 1.0.0 baseline deliberately resets development numbering. The release pipeline publishes
+one tested tarball with provenance and explicitly assigns latest. Registry and unrestricted CI
+verification are mandatory; accepted design and local builds do not prove publication.

package/docs/decisions/ADR-0015-resource-browser.md

@@ -0,0 +1,28 @@
+# ADR-0015 — One terminal browser for resources and discovery
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-22).
+Related: [PROP-0013](../architecture/proposals/PROP-0013-resource-browser.md),
+[source study](../study/tui-resource-browser.md).
+
+## Context
+
+Skills, plugins, Hub items and variant additions have different entry points and misleading
+availability labels. Users need to identify what exists, what this session can use, and what changes later.
+
+## Decision
+
+Use a shared responsive browser with section shortcuts, Installed/Discover views, provenance and
+inspection before management. Join saved configuration with actual runtime resources; never infer
+loaded state from attachment settings or the latest variant head. Keep the loader, gate and service
+ownership intact. Show foundation and variant as different ownership layers.
+
+## Alternatives
+
+Separate pages retain navigation fragmentation. A single combined remote/local list confuses
+installation with availability. A full editor expands the task beyond browse/manage.
+
+## Consequences
+
+The browser adds a protected service adapter and focused navigation state. Resource reads are bounded,
+credentials stay masked, and installing does not activate resources. Existing commands remain shortcuts.
+Implementation and verification evidence belong in the terminal guide, not in this decision record.

package/docs/decisions/ADR-0016-fullscreen-browser-tabs.md

@@ -0,0 +1,31 @@
+# ADR-0016 — Full-screen browser with persistent resource tabs
+
+Status: Accepted (user requested implementation of the agreed plan, 2026-10-23).
+Related: [PROP-0014](../architecture/proposals/PROP-0014-fullscreen-browser-tabs.md),
+[ADR-0015](ADR-0015-resource-browser.md).
+
+## Context
+
+The unified browser's centered layout and nested section/detail navigation leave little space
+for inventory and inspection. The user wants one full-page workspace with resource-section tabs.
+
+## Decision
+
+Resource-browser commands use a full-screen surface with persistent section tabs. Wide terminals
+show inventory beside an inspector containing metadata, actions and content. Compact terminals
+show inline detail views under the same tab strip. Tab moves focus, arrows change a focused tab,
+and mouse tab selection targets the section directly.
+
+TerminalPage declares its presentation and optionally supports direct tab selection. Centered
+presentation remains the default for other pages. Resource services keep their existing ownership.
+
+## Alternatives
+
+Keeping the centered panel restricts working space. Replacing the list with details at all widths
+loses inventory context. Variant c1–c8 tabs do not match the selected resource-navigation intent.
+
+## Consequences
+
+The browser owns responsive inventory/inspector focus and preserves section search and selection.
+Small terminals use compact tab navigation. There are no storage or protocol changes.
+Verification belongs in the terminal guide and its automated page and PTY checks.

package/docs/decisions/ADR-0017-one-capability-surface.md

@@ -0,0 +1,34 @@
+# ADR-0017 — One capability surface for the terminal and every host
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0015](../architecture/proposals/PROP-0015-one-capability-surface.md),
+[PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[PROP-0017](../architecture/proposals/PROP-0017-page-annotations.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Capabilities grew in the App alone, so the Harness terminal could not do what the App did, and
+ownership between the repositories was unclear. The owner wants the App to be a richer
+presentation of the Harness, with the same capabilities as the terminal, and room for future
+host-only surfaces such as interactive agent output.
+
+## Decision
+
+Every user capability is a Harness capability with a terminal surface (INV-PAR-1, INV-PAR-2).
+Capabilities that need an operating-system object only a host has define a generic contract and a
+terminal fallback (INV-PAR-3). Host-only surfaces own no capability and are registered by the host
+with an owner decision (INV-PAR-4). Managed worktrees and page annotations move into the Harness
+under PROP-0016 and PROP-0017. Orchestration across agents (organizations, routed chats, group
+chats, delegated work queues) is not a Harness capability; the App removes it and keeps it only in
+an archived version.
+
+## Alternatives
+
+Keeping the App as the full product leaves two products. Identical front ends cannot accommodate
+presentation a terminal cannot show. Doing nothing lets the gap grow.
+
+## Consequences
+
+New user features start in the Harness with a terminal surface. The register `docs/parity.md`
+tracks gaps until both surfaces pass. Hosts keep native bridges, windows and presentation.

package/docs/decisions/ADR-0018-builtin-feature-plugins.md

@@ -0,0 +1,35 @@
+# ADR-0018 — Built-in feature modules and namespaced commands
+
+Status: Accepted (owner requested implementation of the plan, 2026-10-24).
+Related: [PROP-0020](../architecture/proposals/PROP-0020-builtin-feature-plugins.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[11 Terminal](../architecture/11-terminal.md).
+
+## Context
+
+First-party plugin descriptors existed, but runtime assembly, server handlers and TUI command
+dispatch were centralized in separate files. Plugin commands shared the same unprefixed namespace
+as core commands. Duplicate Pi extension commands were silently assigned suffixes by the SDK.
+
+## Decision
+
+Use a typed internal registry for built-in plugin modules. Modules own their existing plugin
+descriptor and may supply world parts, public method handlers, terminal command metadata and
+lifecycle. Foundation keeps plugin loading and trust, capability attachment and gating, the TUI
+framework, and the generic isolated browser engine. Plugin commands use `/plugin:<command>`;
+duplicate names are rejected with owner diagnostics. The ownership taxonomy is documentation only.
+
+Retire old unprefixed forms for doctor, worktree, trajectory, subagents, notes and annotate at the
+cutover. Public server methods and stored data keep their current names and shapes.
+
+## Alternatives
+
+Keeping direct central dispatch preserves the current drift between plugin descriptions and
+runtime ownership. Exposing categories in public metadata adds a schema without a runtime need.
+Letting the SDK suffix duplicate commands makes their identity depend on extension load order.
+
+## Consequences
+
+New Harness-managed features register through the built-in plugin registry. The terminal owns the
+page adapter and UI; feature plugins contribute namespaced command metadata. Embedding hosts see
+the existing method table and capability contracts.

package/docs/decisions/ADR-0019-managed-git-worktrees.md

@@ -0,0 +1,31 @@
+# ADR-0019 — Managed Git worktrees are a Harness capability
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Worktrees isolate source changes, but an App-only implementation leaves terminal users without
+that capability and lets each host invent its own lifecycle and safety rules.
+
+## Decision
+
+The Harness owns the worktree registry, lifecycle, session leases, and server methods. Managed
+worktrees are disposable detached checkouts in device-local state; permanent worktrees are retained.
+Creating a worktree disables repository filters, carries source changes only under the defined
+copy/apply rules, and runs setup scripts only after exact-text trust. Leases prevent concurrent
+removal; removal snapshots recoverable work before deleting a checkout. Hosts call `worktrees.*`
+rather than managing these records independently, and the terminal provides the reference surface.
+
+## Alternatives
+
+Keeping the feature in the App breaks terminal/host parity. Putting large worktree checkouts inside
+source repositories pollutes them and makes the data visible to tools and editors. Platform-specific
+copy-on-write clones were deferred in favor of Git's portable linked-worktree behavior.
+
+## Consequences
+
+`worktreeId` identifies a Harness-managed worktree in a run. Worktree state is device-local under
+the Harness state directory. Hosts can present richer controls but do not own lifecycle or safety.