@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/proposals/PROP-0036-first-class-harness-commands.md

@@ -0,0 +1,59 @@
+---
+id: PROP-0036
+title: First-class Harness terminal commands
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [INV-PLG-10, INV-TUI-7, 06-plugins-and-capabilities.md, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0031]
+---
+
+# PROP-0036: First-class Harness terminal commands
+
+## Problem
+
+Harness-owned pages for subagents, agent profiles, recorded-run inspection, diagnostics and worktrees are currently exposed through `BuiltinPluginRegistry` command metadata. This couples their terminal command namespace and discoverability to a feature-plugin registry even though these required features are not optional plugin toggles. It also makes ordinary Harness commands appear as plugin commands in help and completion.
+
+Evidence: `src/plugins/builtin.ts` registers these commands on the `subagents`, `history`, `doctor` and `worktrees` modules; `src/terminal/tui/pluginCommands.ts` maps them to pages; `src/terminal/tui/commands.ts` builds canonical namespaced completion and dispatch from `BuiltinPluginRegistry`.
+
+## Affected rules
+
+- **INV-PLG-10** currently couples a built-in feature's descriptor, tools, server methods and terminal command metadata to one registry owner. Plugin-owned commands should remain with their feature modules, but Harness core commands should be owned by the terminal's core command registry.
+- **INV-TUI-7** requires every plugin-owned command to use an owner prefix. The commands in this proposal become Harness core commands, not plugin-owned commands; all other plugin and extension commands retain owner-qualified routes.
+- **14 Surfaces and parity, Contracts** describes the current terminal command namespace. The command changes are presentation only and add no capability or server method.
+
+## Proposal
+
+Register these routes directly in the core terminal command table and dispatch them to the existing Harness pages:
+
+- `/doctor` opens readiness diagnostics.
+- `/worktree` opens managed worktrees.
+- `/trajectory [run-id]` opens recorded runs and events.
+- `/subagents` opens the subagent roster; `/agents` opens agent profiles.
+
+Keep `/history` (and its `/tree` alias) for session branch navigation. Keep `/mcp` and `/connections` as first-class entries into the Connections browser. All other core commands stay unprefixed. Plugin-owned built-in and extension commands continue to use `/<owner-prefix>:<command>`; annotations retain their `annotate` namespace and default route.
+
+The `doctor`, `worktrees`, `history` and `subagents` feature descriptors remain registered and required. Their services, server methods, tools and capability behavior do not move. Only their terminal command metadata and dispatch move to the core command registry. Core commands reserve their names under the existing terminal command collision policy.
+
+For one release, accept the prior owner-qualified and `/plugin:<command>` forms for the routes being promoted as hidden compatibility aliases. Do not show aliases in help or completion. Remove them after the compatibility release.
+
+## Alternatives
+
+- Keep these routes under owner prefixes. Rejected: it keeps core terminal actions classified as plugin commands and exposes redundant namespaces for required Harness features.
+- Remove the feature descriptors from `BuiltinPluginRegistry`. Rejected: those descriptors still own Harness tools, server methods and capability contributions; only terminal command ownership needs to change.
+- Replace `/history` with the trajectory page. Rejected: `/history` already navigates the current session's branches. Keep it and expose the run trajectory as `/trajectory`.
+- Do nothing. Rejected: help, completion and dispatch continue to treat these core pages as plugin-owned commands.
+
+## Consequences
+
+Help, completion, slash recognition and dispatch use the core command table for the promoted commands. The `/mcp` command remains in that table and keeps its Connections behavior. Plugin command-prefix collision checks remain in force for plugin-owned commands. No capability set, server protocol, account data, run record or stored resource changes.
+
+## Migration
+
+No stored-data migration. Accept the previous qualified forms as hidden aliases for one release; scripts and keybindings should use the bare canonical names. `/history` remains the branch picker and `/trajectory` is the recorded-run page.
+
+## Checks
+
+- Registry and terminal tests cover bare routes, help, completion, slash recognition, compatibility aliases, prompt-name collisions, `/history`, `/mcp` and unchanged plugin namespace routing.
+- Harness `npm run typecheck`, `npm test` (150 files; 1,143 passed, 3 skipped) and `npm run prove` passed.
+- Xingular Agent `npm run typecheck`, `npm test` (App and sidecar suites: 634 passed; signing tests: 7 passed, 1 skipped), `npm run check:layers` and `cargo test` (167 passed, 1 ignored) passed.
+- Isolated terminal PTY checks passed for `/help`, composer modes, and the `/trajectory` Runs/Events page. `/help` screen-layout assertions were skipped because optional `pyte` is unavailable.

package/docs/architecture/proposals/PROP-0037-workspace-write-boundary.md

@@ -0,0 +1,63 @@
+---
+id: PROP-0037
+title: Default filesystem writes to the active project workspace
+status: Implemented
+created: 2026-11-19
+updated: 2026-11-19
+affects: [INV-GATE-1, INV-GATE-3, INV-GATE-8, INV-RUN-1, INV-TUI-8, 02-sessions-and-runs.md, 04-prompt.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0037: Default filesystem writes to the active project workspace
+
+> **Implementation update:** This proposal records the original pathname-check and
+> denial-triggered-retry design. Security review found those details bypassable; accepted
+> [PROP-0039](PROP-0039-workspace-boundary-hardening.md) replaces them with operation-time atomic
+> writes and explicit pre-execution outside-scope approval. Follow the current contracts in
+> [07 Tools and the gate](../07-tools-and-gate.md) and [11 Terminal](../11-terminal.md).
+
+## Problem
+
+Harness tells the model that read-only file tools can use any path the process can read, and that the working folder is not a repository boundary (`src/prompt/compile.ts`; `docs/architecture/07-tools-and-gate.md`, Native file paths). The same page says `edit`, `write` and `bash` pass through the existing gate and policy, but that gate has no built-in workspace-root rule. The SDK's `ToolPolicy` is optional, and the terminal's default approval flow is not a filesystem sandbox (`src/sessions/policy.ts`, `src/sessions/sessions.ts`, `src/terminal/terminals.ts`). Thus a session has no Harness-wide default that keeps model-initiated file mutations in its project.
+
+## Affected rules
+
+- **INV-GATE-8**, as it stands: “Native read-only file access is bounded by process and operating-system permissions, not by the repository root. Absolute and `~` paths are valid inputs. This does not change the gate or permissions for writes and commands.” The first two sentences remain; the final sentence changes because the Harness will scope writes and shell file effects.
+- **INV-GATE-3**, as it stands: “Order is fixed: capability and plan-mode refusals, then the policy's scope and authorize, then standing approvals, then the person, then authorize again.” The mandatory workspace check must join this ordering without allowing a host policy to silently broaden it; an approved one-call escape must be authorized before the operation runs.
+- **INV-RUN-1**, as it stands: “A run pins one account, one variant version and one capability set when it starts. None of them changes during the run.” A run will also pin its resolved workspace-write root so a continuation or later filesystem change cannot silently widen its scope.
+- **INV-TUI-8**, added by implementation: the terminal uses the same Harness-pinned root and workspace-write policy as SDK sessions; it cannot widen the boundary through its private socket or native extension.
+
+## Proposal
+
+1. **Preserve broad reads.** Read-only filesystem tools retain their existing process/OS-permission behavior. The write boundary applies to model-controlled filesystem mutations, not to reads.
+2. **Resolve one trusted workspace root per run.** After Harness has selected the effective `cwd` (including a managed worktree), resolve the nearest ancestor containing `.git`, canonicalize it, and store it as `RunRecord.workspaceRoot`. If there is no Git repository, use the canonical `cwd`. A worktree is its own active workspace. Do not infer the root from model-supplied tool arguments or an unvalidated `projectId`.
+3. **Default file writes to that root.** Native `edit` and `write` calls may mutate paths inside the root. Resolve paths canonically and reject symlink/path escapes. Paths outside it require approval for that operation. A per-tool remembered grant does not authorize an outside write.
+4. **Enforce shell writes, not just shell-call names.** Run model Bash—including the initial `!` command—under an OS-enforced workspace-write sandbox. Shell commands may read as before but may write only under `workspaceRoot`; `/tmp` and other external paths are outside the default write scope. A denied outside write produces a clear denial and a one-shot escalation path for that command. Approval reruns only that command with the wider access needed. Fail closed when workspace-mode enforcement is unavailable; never silently run it unconfined.
+5. **Use existing approval controls.** Outside writes require a person’s one-call approval. Mark the request human-only so remembered grants cannot answer it. The existing Full Permission switch may automatically grant this explicitly eligible escape; it is off by default. Preserve hard policy denials and the existing read-only, plan, unattended, probe, improver and reflection restrictions. Full Permission does not add tools or bypass those restrictions.
+6. **Keep artifacts in the project by default.** Files created for the task, including deliverables, belong inside the active workspace. Prefer an existing project convention such as `artifacts/` or `outputs/` when present; do not require or create a universal output folder. An explicitly approved outside write remains possible.
+7. **Make the policy Harness-owned and shared.** Apply the same root and decision in SDK sessions and the standalone terminal. Host `ToolPolicy` may impose stricter limits, but cannot waive the Harness boundary except through the same explicit approval path. Connected-app and other non-filesystem side effects remain governed by their existing tool policies.
+
+## Alternatives
+
+- **Prompt-only “write in the repo” guidance.** Rejected: it expresses a preference but does not prevent absolute paths, symlink escapes or shell commands from writing elsewhere.
+- **Rely only on the host `ToolPolicy`.** Rejected: it is optional and host-specific, so terminal and embedded sessions could differ.
+- **Check only `edit`/`write` paths or parse Bash strings.** Rejected: shell commands can write through arbitrary programs, redirection, subprocesses and indirect paths; string inspection is not a reliable boundary.
+- **Allow all OS temp directories by default.** Rejected for this proposal: the requested default is project-only. A temp location outside the workspace needs the same approval as any other outside write.
+- **Do nothing.** Keeps the existing broad behavior and leaves repository scope to prompt guidance or host configuration.
+
+## Consequences
+
+- Add an optional, backward-compatible `workspaceRoot` field to `RunRecord`; new runs set it, old records remain readable, and continuations of older runs derive it from their recorded working directory. No separate workspace registry or output directory is introduced.
+- The native file tools and shell need different enforcement mechanisms: canonical target checks for file mutations and an OS sandbox for shell subprocesses. The same workspace policy and approval semantics must be used by SDK and terminal paths.
+- The `RunRecord` schema is returned over the server protocol, so embedding hosts and sidecar schemas must tolerate the additive field. The Harness remains responsible for computing it; a host cannot nominate an arbitrary wider root.
+- Workspace mode fails closed on unsupported or unavailable sandbox backends. A person can still explicitly authorize one outside operation, or use the existing Full Permission switch where permitted.
+- Standard commands that need to write outside the project (including to `/tmp`) may need an approved one-shot retry. Project-local artifact/output conventions continue to work without extra approval.
+
+## Migration
+
+No stored files are rewritten. Parsers accept older run records without `workspaceRoot`; a continuation derives the root from the earlier record's `workingDirectory` and stores it on the new run. New runs pin the effective root after worktree selection. Existing remembered tool grants remain stored but do not satisfy outside-write approvals. The current Full Permission switch remains off/on as configured; it is the only standing choice that may approve a boundary escape, and read-only or unattended facts continue to disable it.
+
+## Checks
+
+- Workspace resolution, canonical file-write inspection, session/terminal approvals and sandbox tests cover Git roots, worktrees, non-Git folders, symlink escapes, broad reads, remembered-grant rejection, eligible Full Permission, hard restrictions, fail-closed behavior and one-shot retries. Passed.
+- Harness `npm run typecheck`, full `npm test` (153 files; 1,167 passed, 3 skipped), and `npm run prove` passed on 2026-11-19.
+- The App sidecar contract verifies `runs.find` returns the pinned root. App `npm run typecheck`, `npm test` (571 renderer and 67 sidecar tests passed; 7 development-signing tests passed, 1 skipped), `npm run check:layers`, and `cd src-tauri && cargo test` (169 passed, 1 ignored) passed. Rust compilation emitted warnings.

package/docs/architecture/proposals/PROP-0038-annotate-open-shadow-roots.md

@@ -0,0 +1,73 @@
+---
+id: PROP-0038
+title: Annotate inside open shadow roots
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [13-world-tools.md, 12-storage.md (note target), PROP-0017, PROP-0018, parity]
+---
+
+# PROP-0038: Annotate inside open shadow roots
+
+Requested by the owner on 2026-10-25 after the inspector did nothing on reddit.com; they approved
+this design in the same session.
+
+## Problem
+
+Sites built from web components keep their content in shadow roots. Reddit's posts, comments and
+feed are `shreddit-*` elements with open shadow roots. The page helper (`annotations/pageScript.ts`)
+refused anything whose root node is not `document`, anything under an element with a shadow root, and
+any custom-element tag (PROP-0017, PROP-0018: "frames, shadow roots and custom elements are never
+picked"). Its text stream (`TreeWalker` over `document.body`) and element lookup
+(`document.getElementsByTagName`) never entered a shadow root. On such sites the inspector drew no
+outline, ignored clicks and said nothing. In WebKit, `getRangeAt` reports a selection inside a shadow
+root as a collapsed point on its host, so text capture could not work there either.
+
+## Proposal
+
+1. **Walk the composed tree.** New helper primitives walk open shadow roots and slotted content in
+   rendered order (`composedParent`, `flatChildren`, a bounded composed text stream). Visibility and
+   the excluded-content rules are checked on composed ancestors, and `aria-labelledby` ids are looked up
+   in the element's own root. Closed shadow roots stay unreadable, and light text a closed component
+   does not render is left out. Frames are never entered.
+2. **Version the target.** Text and element targets captured this way carry `tree: 'composed'`. A
+   target without it (every note saved before) is captured, stored and resolved by the document-only
+   rules exactly as before, so a saved note never changes what it points at, and a composed note can
+   never match a light-DOM node through the old path. The store accepts only the literal `'composed'`
+   and never on a page target.
+3. **Selections across trees.** Selections are read with `Selection.getComposedRanges` (dictionary
+   form, then variadic). Boundary points map to stream positions through the composed walk, so a
+   selection may start in the page and end inside a component. A selection that spans a visible form
+   field or private content is refused. A selection that grows over such content no longer leaves the
+   last acceptable selection behind; this also fixes the document-only path. Without
+   `getComposedRanges` the helper keeps the document-only capture.
+4. **Matches and marks.** A composed text match is a list of per-text-node ranges, since a `Range`
+   cannot span trees. Element candidates come from the document and every open shadow root, with the
+   same 2 000-candidate cap and equality rules. Context at the top of a shadow root is the component
+   that holds it. Marks clip to scrollports inside components and follow their scrolls and mutations.
+5. **Inspector.** The inspector picks the nearest annotatable element on the event's composed path, so
+   an icon gives way to its button, and content inside open components is reachable. A custom element
+   is pickable when it carries readable text or a label. It says why when it refuses, in a muted chip
+   and a toast on click: form fields and private content, embedded frames, or a component whose
+   contents are private.
+6. **Agents.** `page_notes_read` adds that a composed target lies inside a page component, where a
+   document-wide selector will not reach it.
+
+## Out of scope
+
+Iframes (cross-origin frames are unreachable by page script) and closed shadow roots.
+
+## Migration
+
+None. Existing notes have no `tree` and keep the old behaviour. Hosts that validate targets strictly
+accept the optional field (the App's `shared/browserAnnotations.ts`).
+
+## Checks
+
+`src/annotations/pageScript.test.ts` (headless Chromium) adds a web-component fixture: picks inside
+open roots, slotted and nested content, duplicate controls told apart by context, text inside and
+across roots, refusal over a field, hints for fields and a closed component, and identical
+legacy/composed captures on a page without components. `store.test.ts` covers the marker. In the App's
+isolated probe instance (real WKWebView), text inside a component and text crossing into one were
+captured, saved, resolved and revealed. Inspector clicks in WKWebView need real pointer input and were
+not exercised there.

package/docs/architecture/proposals/PROP-0039-workspace-boundary-hardening.md

@@ -0,0 +1,139 @@
+---
+id: PROP-0039
+title: Harden workspace writes against inode escapes and unverified retries
+status: Accepted
+created: 2026-10-26
+updated: 2026-10-26
+affects: [INV-GATE-3, INV-GATE-8, INV-TUI-8, 02-sessions-and-runs.md, 07-tools-and-gate.md, 11-terminal.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0039: Harden workspace writes against inode escapes and unverified retries
+
+## Problem
+
+PROP-0037 promises that model-controlled writes stay inside the pinned workspace unless a person
+approves an escape. The current implementation checks canonical pathnames, but Pi performs native
+`write` and `edit` operations afterward using ordinary filesystem calls. A hard link keeps an
+in-workspace pathname while sharing an outside inode, and a parent symlink can change after the
+check. Source review found both cases can bypass the intended approval boundary.
+
+The Bash sandbox also exposes the live workspace as a writable path. A macOS integration
+reproduction created a hard link from a file outside the workspace to a name inside it, then ran a
+sandboxed Bash write through the in-workspace name. The command succeeded and the outside alias
+contained the new content. Linux behavior has not yet been reproduced locally.
+
+Finally, `workspaceSandbox.ts` infers a sandbox denial from matching text anywhere in captured
+stdout/stderr. A command controls that output; the text can prompt for an unconfined retry even when
+no sandbox denial occurred. Approval is still required, but the prompt's reason is not verified and
+approval replays the entire command.
+
+A separate launcher-selection issue was fixed in the 1.2.0 working tree: the sandbox launcher now
+comes only from fixed system paths, with a fake-PATH regression test. This does not resolve the
+remaining findings. No candidate, tag, or publication has been created.
+
+## Affected rules
+
+- **INV-GATE-3**, as it stands: “Bash first passes the gate's scope and authorization, then executes
+  only inside the OS sandbox; a detected write denial may enter a separate one-shot approval before
+  retry. The policy may tighten or deny a call, but cannot waive the boundary. Outside file writes
+  and sandbox-denied Bash retries cannot use remembered per-tool approval; only the eligible Full
+  Permission switch can answer automatically.” The output-triggered retry is replaced by an
+  explicit pre-execution scope request.
+- **INV-GATE-8**, as it stands: “Native reads are bounded by process and operating-system
+  permissions, not by the workspace root; absolute and `~` paths are valid. Every run pins its
+  canonical `workspaceRoot`. Native `edit` and `write` targets must resolve inside it by default,
+  with symlink escapes refused; outside targets require one-call approval and cannot use remembered
+  tool grants. Bash, including the initial `!` command, is OS-sandboxed to write only inside that
+  root while retaining broad reads. Sandbox denial permits at most one retry after explicit
+  approval. Full Permission is the only standing boundary bypass and remains subject to host
+  policy, authorization, and read-only, plan, unattended, probe, improver and reflection
+  restrictions. Missing enforcement fails closed.” The rule must define containment by the actual
+  filesystem effect, not just the path string.
+- **INV-TUI-8**: the terminal must present the same safe write and pre-execution approval behavior
+  as SDK sessions.
+
+## Proposal
+
+1. **Keep workspace-only as the default.** Each run continues to pin its canonical workspace root.
+   Reads remain broad as today.
+2. **Enforce native writes at the operation.** Harness supplies the `write` and `edit` tools with
+   safe filesystem operations instead of delegating their mutations to Pi's default in-place
+   `fsWriteFile`. The operation revalidates the pinned target and performs an atomic replacement
+   under the OS-enforced workspace boundary. Replacing the in-workspace directory entry rather
+   than truncating a shared inode prevents a hard-link alias from changing an outside file. A
+   symlink or parent-directory swap cannot widen the operation's OS write scope. Outside targets
+   retain their existing human-only, one-call approval; the helper receives only that approved
+   canonical target. Tool names and model-facing schemas stay the same.
+3. **Fail closed on external hard links for sandboxed Bash.** Before a default Bash call, inspect the
+   workspace for regular-file inodes whose link count exceeds the names found inside the workspace.
+   If the scan is incomplete or finds a possible outside alias, do not run the command; explain that
+   the alias must be removed or copied. The OS sandbox must also prevent the model's sandboxed
+   processes from creating a cross-boundary hard link. If a backend cannot establish both
+   conditions, it fails closed. A local process outside Harness with the same user's filesystem
+   permissions is not controlled by this rule; if protection from such peer processes is required,
+   that needs a separate inode-isolated workspace/snapshot design.
+4. **Ask before broad Bash writes, never infer from output.** Add an explicit
+   `workspaceWriteScope` choice to the Harness-owned Bash call, defaulting to `workspace`. A call
+   requesting `outside` is approved before it runs, as a human-only, nonrememberable operation; the
+   approval presentation must expose the complete command (scrollable in the terminal). The
+   eligible Full Permission switch may answer only under its existing restrictions. After approval,
+   run that exact command once with broader filesystem access. stdout/stderr text never triggers
+   approval or an automatic retry, and a denied command is never replayed after partial effects.
+5. **Keep other gates intact.** Plan, read-only, unattended, probe, improver and reflection
+   restrictions, host policy, authorization, and the tool capability set remain in force. Outside
+   writes and broad Bash calls cannot use remembered per-tool grants.
+
+## Alternatives
+
+- **Keep pathname checks and the output regex.** Rejected: hard links are invisible to `realpath`,
+  native operations race after validation, and command output is not evidence of a sandbox event.
+- **Only reject files with `nlink > 1` for native writes.** Rejected: a link can be added after the
+  check, and the native operation remains subject to path swaps.
+- **Run every shell call in a private copy-on-write workspace and commit changes back.** This gives
+  stronger inode isolation, including against peer processes, but changes shell visibility,
+  writeback/conflict behavior, metadata, storage use, and performance. It remains the alternative
+  if protection from same-user processes outside Harness is required.
+- **Remove all outside-write capability.** Rejected for now: the existing contract intentionally
+  supports explicitly approved escapes. The proposed pre-execution request preserves that choice
+  without guessing from output.
+- **Do nothing.** Leaves the default workspace boundary bypassable.
+
+## Consequences
+
+- The public server protocol and stored `RunRecord` layout need no new fields. The Bash tool schema
+  gains an optional scope choice; existing calls default to the current workspace-only behavior.
+- SDK sessions and the standalone terminal must register the same safe native tools and apply the
+  same pre-execution Bash gate. Terminal approval remains available through its existing inbox.
+- Atomic replacement changes the inode for a written path. The implementation must preserve normal
+  file mode behavior where possible and document any platform metadata that cannot be retained.
+- Reject the filesystem root as an active workspace; otherwise every path is inside the pinned root
+  and the boundary provides no containment.
+- A workspace containing a possible external hard link cannot use default sandboxed Bash until it
+  is repaired. Explicit outside scope remains a separate, visible approval, not a way to silently
+  reuse remembered grants.
+- The boundary protects model-controlled operations inside Harness. Other local processes running
+  with the same user's filesystem permissions remain outside this proposal's protection. On macOS,
+  the OS sandbox denies all hard-link creation by sandboxed Bash, including links entirely inside the
+  workspace.
+
+## Migration
+
+No stored runs or workspace data are rewritten. Old sessions continue to pin the same workspace
+root. Existing Bash calls omit `workspaceWriteScope` and therefore remain workspace-only; a command
+that needs broader writes must be issued again with an explicit outside scope and approved before
+execution. Existing outside-write approvals remain per-call and are not migrated into standing
+grants.
+
+## Checks
+
+- Add adversarial tests for native hard-link writes, symlink/parent swaps between validation and
+  mutation, shell writes through pre-existing external hard links, and cross-boundary hard-link
+  creation on macOS and Linux.
+- Verify command output containing denial-like text cannot request approval or rerun a command;
+  verify explicit outside scope asks before execution and runs at most once after approval.
+- Verify the complete requested command is visible in outside-scope approval details, and Full
+  Permission and all read-only, plan, unattended, refinement, authorization, and host policy
+  restrictions remain intact in SDK and terminal paths.
+- Run Harness `npm run typecheck`, `npm test`, and `npm run prove`; run the App compatibility checks
+  and inspect the relevant terminal behavior. Exercise the sandbox integration tests on macOS and
+  Linux before release.

package/docs/architecture/proposals/PROP-0040-one-launch-path.md

@@ -0,0 +1,87 @@
+---
+id: PROP-0040
+title: One launch path and command contract across front ends
+status: Accepted
+created: 2026-11-19
+updated: 2026-11-19
+affects: [INV-EXT-1, INV-RUN-1, INV-VAR-4, INV-PLG-11, INV-PAR-1, INV-PAR-2, INV-STO-3, 01-extension-points.md, 02-sessions-and-runs.md, 03-variants.md, 04-prompt.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 13-world-tools.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0040: One launch path and command contract across front ends
+
+## Problem
+
+The approved App parity and Solo tabs handoff implemented a shared command registry and standard
+prompt sections, but the actual terminal still loads Pi command built-ins, terminal run records
+omit variant pins, session operations differ across front ends, and native browser schemas differ.
+Matching data roots alone does not share credentials: the terminal defaults to a file SecretStore
+while a host may supply its Keychain. Existing compiler-only tests do not establish runtime parity.
+
+## Affected rules
+
+- INV-PAR-1: every capability a person uses in a host is a Harness capability with a terminal surface.
+- INV-PAR-2: both surfaces must pass acceptance before a capability is complete.
+- INV-RUN-1 and INV-VAR-4: runs retain account, variant and capability pins.
+- INV-EXT-1: extension-point changes require a proposal; native backends remain tool providers.
+- INV-STO-3: storage layout changes are explicit and owned by one Harness module.
+- INV-PLG-11: plugin categories remain internal; surface availability is optional metadata, not a category.
+
+## Proposal
+
+The owner approved “Complete App parity and Solo tabs”, including one shared interactive default,
+on 2026-11-19. This proposal records that design; implementation status is tracked separately.
+
+1. Core commands are browser-safe data in `commands/registry.ts`. `commands.list` resolves the
+   effective scope's trusted plugin commands, prompts and skills with identical namespace and
+   collision rules. A menu entry alone does not prove command acceptance.
+2. Saved-history controls cover tree, navigate, fork, clone, rename, last reply and JSONL export.
+   Commands requiring a live session use `SessionRunInput.command`: compact, summarized navigation
+   and HTML export. They retain normal run lifecycle, busy fencing, cancellation and pins.
+3. `Launch.standard` supplies shared role, working-folder and connection wording. Tool and prompt
+   differences must be attributable to declared add-ons or explicit caller policy, not a front end.
+4. Interactive defaults are Harness-owned: data root, state directory, neutral default variant
+   scope and credential backend. Explicit roots/scopes and existing session/continuation pins win.
+   No App-specific discovery, automatic root merge, account substitution, credential downgrade or
+   OAuth-store copying is permitted. Adoption of conflicting populated profiles is explicit.
+5. Both surfaces load Harness-trusted resources and first-party hooks. Terminal-only Pi built-ins
+   and `ask_user_question` are removed; attended plan mode uses `ask_user`.
+6. Browser contracts are backend-neutral and owned by Harness; the isolated and native host
+   backends share names, schemas, safety metadata and ref freshness. A backend must report an
+   unsupported operation honestly, never reinterpret a snapshot ref as a selector.
+7. `get_capabilities` is a read-only Harness tool bound to the current run's frozen callable set
+   and actual registered schemas. Discovery never grants permission or accepts caller identity.
+8. Optional `PluginDescriptor.surfaces` / `Plugin.surfaces` metadata is
+   `{ preferred: 'host', terminal: 'fallback' | 'unavailable', note }`. Generic host-backed
+   capabilities retain Harness ownership; inspection shows fallback/unavailable reasons.
+9. Shared session references/catalog registration belong to Harness. Existing host transcript
+   presentation remains host-owned; native entry identities, not positional message counts,
+   connect navigation and fork to that presentation.
+
+## Alternatives
+
+- Do nothing: leaves command names that only approximate the advertised capabilities.
+- Match roots manually: rejected by the owner's explicit choice of one shared default.
+- Put browser contracts or session orchestration in the host: violates INV-PAR-1.
+- Merge existing stores automatically: unsafe for account pins, credentials and conflicting variants.
+
+## Consequences
+
+Server methods and SDK fields are additive. Existing session histories and account IDs remain valid.
+Terminal run records gain variant identity. Host browser adapters implement the common contract;
+legacy native routes may remain non-model-visible compatibility aliases for one release. Metadata
+labels do not certify acceptance or waive the gate.
+
+## Migration
+
+Keep explicit custom roots and historical pins. Seed only an absent default scope through validated
+variant APIs. Shared profile adoption must preserve originals, report conflicts/failure, and never
+silently select an empty replacement. Credentials remain in their owning backend. Shared processes
+must coordinate credential refresh and respect live run owners. Development/disposable profiles
+remain isolated from production. No migration is exercised on owner data during implementation.
+
+## Checks
+
+Harness typecheck, full tests and prove; deterministic terminal verification; App renderer/sidecar,
+layer/UI and Rust checks; full browser fixtures; shared UI and both consuming applications' checks.
+Runtime parity compares actual prepared launches, tool schemas and recorded pins. Native WebKit
+acceptance uses an isolated profile. Real-provider/cache checks require separate owner permission.