@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/handoff-2026-10-25-app-parity-and-solo-tabs.md

@@ -0,0 +1,202 @@
+# Handoff: App parity with the Harness, and the Solo sidebar and tabs (updated 2026-11-19)
+
+The scoped implementation and documentation are in place; full parity acceptance remains open.
+Nothing is committed. The working trees contain substantial pre-existing uncommitted work; preserve
+it and do not revert unrelated files.
+
+| Repository | Branch | State |
+|---|---|---|
+| `Xingular Agent/Harness` | `release/1.0.0` | Code and architecture docs updated; typecheck, full tests and `prove` pass |
+| `Xingular UI` | (current) | Shared tab-manager change; typecheck and full tests pass |
+| `Xingular Agent/App` | `app-as-frontend` | Profile safety, commands, Solo tabs, browser refusal and docs updated; automated checks pass |
+| `Xingular Workspace` | (current) | Shared-UI consumers typecheck and UI check pass; four test failures were observed |
+
+Approved plan: `~/.claude/plans/i-wanna-make-change-velvet-nova.md`.
+
+## What the owner asked for
+
+1. Solo sidebar: **Project › Session**, with no folder or worktree level. People never configure
+   worktrees. A new session runs in the project folder, as `xagent` does in a terminal.
+2. Each session card has two rows: the title, then a muted row such as `2h ago · 5.1MB`.
+3. One shared top bar over the chat, with tabs and an icon-only view switch:
+   - **Split**: every open session is its own panel (the earlier behaviour).
+   - **Single**: one panel; clicking a tab replaces what it shows.
+4. The sidebar shows which sessions are open. A middle click on a tab closes it. Closing a tab
+   only closes the tab; it never archives the session.
+5. Every Harness terminal slash command works in the App.
+6. The prompt, runtime, plugins and skills are the same in both front ends. Features that work
+   better in the App (annotate capture, the WebKit browser, computer control) are labelled as
+   add-ons in their plugin descriptions.
+
+Choices the owner made:
+- Parity: same core, plus labelled add-ons.
+- Build every command now.
+- Closing a tab only closes it.
+
+## Done
+
+### Harness
+
+- **Shared command registry.** `src/commands/registry.ts` holds `CORE_COMMANDS`, plain data, each
+  with `kind` (session, page or local) and `methods`. The terminal's `BUILTINS` now comes from it
+  (`src/terminal/tui/commands.ts`).
+- **`commands.list` server method** (`src/commands/list.ts`). It returns core commands, built-in
+  plugin commands (`annotate:…`), extension commands with their owner prefix, prompt templates
+  and `skill:` entries.
+- **Session control methods** (`src/sessions/control.ts`, wired in `src/server/methods.ts`):
+  - `sessions.tree`, `sessions.navigate` (no summary; the move is saved as a `xingular-navigation`
+    custom entry so the next turn opens on it)
+  - `sessions.fork`, `sessions.clone` (both into a `targetDir`)
+  - `sessions.rename`, `sessions.lastReply`, `sessions.export` (JSONL)
+  - `sessions.reload`
+- **Session command runs.** `SessionRunInput.command` / `TurnParams.command` accepts `compact`,
+  `navigate` (with a summary) or `export` (HTML). `runTurn` runs the command instead of a prompt
+  and skips the context update. `checkCommand` in `src/sessions/sessions.ts` validates it.
+- **One launch path for prompts and tools:**
+  - `Launch.standard` (`src/prompt/standard.ts`) adds the same role, working-folder (with the
+    project name) and connections text for every front end.
+  - The terminal always uses it; the App now asks for it.
+  - The terminal-only `xagent-wiki` wording is gone from `compile.ts`. There is one files-and-shell
+    paragraph for every caller, and a standard session always gets it.
+  - A new Annotations tool group carries the `page_notes_*` guidance, moved from the App.
+- **The terminal gets the same tools:**
+  - The Harness History, Wiki and skill tools go over the socket (`ownTools` in
+    `src/terminal/terminals.ts`), which closes PAR-002.
+  - Output trim and Budget guard load in the terminal (`firstParty.list` socket call plus
+    `piExtension.ts`), which closes PAR-006. Budget guard now resets its count per reply
+    (`agent_start`).
+  - The terminal-only `ask_user_question` alias is removed; `ask_user` covers it.
+  - The `pi` command's own extensions (llama.cpp, codemode, tool-search, mcp) are no longer loaded
+    in the terminal, because a host session cannot have them. See `catalogue.ts` and
+    `inventory.ts`.
+- **`xagent --variant <scope>`** (`src/terminal/standalone.ts`, `src/cli.ts`). With the App's
+  `--data`, the terminal runs on the same variant as an App agent.
+- **Add-on labels.** New `PluginDescriptor.surfaces` / `Plugin.surfaces` field
+  `{ preferred: 'host', terminal: 'fallback' | 'unavailable', note }`, with helpers in
+  `src/plugins/surfaces.ts`.
+  - The annotations plugin is labelled. The layer check forbids naming the App inside the
+    Harness, so its text says "a desktop app built on this harness".
+  - The terminal's `/plugins` and `/harness` pages show the note and a badge.
+- **New exports** in `src/index.ts`: the registry, `SessionCommand`, `SessionTree`,
+  `PluginSurfaces`, `describePlugin`, `STANDARD_CONNECTIONS`.
+- **Tests:**
+  - Added: `src/commands/registry.test.ts`, `src/sessions/control.test.ts`,
+    `src/prompt/surfaceParity.test.ts` (a terminal and a host session compile to identical text
+    and tool groups), and session-command tests in `sessions.test.ts`.
+  - Updated: terminal, catalogue, standalone, runtime-socket and lifecycle tests.
+
+### Xingular UI
+
+- `WorkspaceTabManager` (`src/ui/document-workspace.tsx`): new `addLabel`, and `activeTabId` may
+  be `null`. Test added in `tests/workspace-tabs.test.tsx`. Middle-click close already existed.
+
+### App
+
+- **Solo model rewritten:**
+  - `src/modes/solo/soloLayout.ts` (version 2): one layout across projects. Every open tab has a
+    pane; `view` is `split` or `single`. Functions: `openSoloTab`, `closeSoloTab`, `focusSoloTab`,
+    `visibleSoloTree`, `restoreSoloLayout` (migrates version 1).
+  - `soloWorkspaceState.ts`: storage key `…:v2`, migrated from the v1 key.
+  - `soloThreads.ts`: `groupSoloProjects`, `projectDefaultGroup`, `tabGroup`, `tabProjectId`.
+- **Sidebar** (`SoloThreadList.tsx`):
+  - Project › Session, with two-row cards (`sessionMeta`) and an open/active indicator
+    (`data-open`, `data-active`, `data-solo-open-indicator`).
+  - Each session's ⋯ menu has Archive and Remove.
+  - The project's + button starts a session in the project's default folder group.
+  - The group rows and worktree controls are removed, and `SoloGroupDialog.tsx` is deleted.
+- **Center** (`SoloCenter.tsx`):
+  - `SoloTabBar` and `SoloViewToggle` sit in the shared `PageFrame` compact header, wired in
+    `SoloWorkspace.tsx`.
+  - Per-pane headers are removed.
+  - ⌘W / ⌘T now call `closeFocusedTab` / `newSession` (`src/shell/frameControls.ts`,
+    `src/App.tsx`).
+- **Session size.** `ThreadSummary.size_bytes` (Rust `history_bytes` in `agents.rs`) and
+  `sizeBytes` in `shared/contracts.ts`. `formatSessionSize` in `shared/files.ts` matches the
+  terminal's format.
+- **Slash commands from the Harness:**
+  - `src/modes/solo/soloCommands.ts` has a handler for every non-sending core command.
+    `soloCommands.test.ts` fails if the registry gains one without a handler.
+  - `SoloCommandPicker.tsx` is the picker or page dialog.
+  - `SoloConversation.tsx`:
+    - The `/` menu and highlighting come from `commands.list`.
+    - Aliases (`/side`, `/tree`, `/resume`) work.
+    - A bare `/plan` toggles a persistent plan mode, and a bare `/btw` dismisses the side question.
+  - `chatCommands.ts` is reduced to `isStopCommand` and `chatCommandInput`. The duplicate
+    extension-command helpers in `pluginModel.ts` are removed.
+- **Host side:**
+  - New Tauri commands in `src-tauri/src/agents.rs`, registered in `lib.rs`: `session_tree`,
+    `session_fork`, `session_clone` (fork and clone copy the transcript too), `session_rename`,
+    `session_compact`, `session_export`, `session_reload`.
+  - New sidecar `agent.command` (`createSessionCommand` in `sidecar/src/agentRuns.ts`).
+  - `RENDERER_METHODS` (`src-tauri/src/harness.rs`) gained `commands.list`, `doctor.*`,
+    `worktrees.list/status` and `agents.list/get`.
+  - Bridge: `bridge.commands`, `bridge.session` and `bridge.harnessPages` in
+    `src/bridge/commands.ts`. The schemas are in `shared/sessionCommands.ts`.
+- **Prompt:**
+  - `src-tauri/src/prompts.rs` no longer writes identity, role, working-project or its own
+    connections text.
+  - It keeps only the add-on groups: App browser and computer, Files, Capabilities, Reactions.
+  - It adds a `folder-access` section for trusted folders.
+  - `agents.rs` sets `launch.standard = { cwd }`.
+- **Plugin labels:**
+  - `sidecar/src/appPlugins.ts` labels every App part as an add-on, with `surfaces`.
+  - `app-identity` and `app-web-guidance` are removed, and `app-folder-access` is added.
+  - The Plugins screen shows a "Better in the app" or "App only" badge (`pluginModel.ts`,
+    `PluginCatalog.tsx`, `PluginInspector.tsx`).
+  - The plugin schema gains `surfaces`.
+- **Guide demo** (`src/modes/guide/SoloWorkspaceExample.tsx`) and the Playwright fixtures and
+  specs (`tests/browser/solo-*.{fixture.tsx,spec.ts}`) are rewritten.
+- **Shared interactive profile and root safety:** production App and standalone use the Harness
+  profile at `~/.xingular-harness/profile.json`; development uses the isolated
+  `~/.xingular-harness-dev/profile.json`. Existing App roots are adopted by reference, explicit
+  `dataRoot` overrides remain authoritative, and conflicting populated roots block startup rather
+  than merge. Historical account/variant/path/cwd pins are not rewritten. Legacy App Support moves
+  only if the destination is absent; if both trees exist, startup reports a recovery error and
+  leaves both untouched. Development paths are checked against production, including symlink
+  traversal. The App resolves the selected host credential backend through Keychain and fails
+  closed; the terminal also fails closed without a host adapter. Disposable App identifiers remain
+  blocked until an isolated Keychain adapter exists. Sidecar startup requires and validates the
+  selected profile and state-directory paths. Coverage is in `sidecar/src/profile.test.ts` and
+  `src-tauri/src/{state.rs,host.rs,secrets.rs}`.
+- **Browser safety:** unsupported native WebKit operations (refs, accessibility snapshots,
+  screenshots, waits, and key presses) return an explicit refusal before effects; the App does not
+  switch automatically to the isolated Harness browser.
+- **Current App documentation:** accepted ADR-0033 records Project › Session and shared tabs;
+  ADR-0027 and the obsolete pane-header portion of ADR-0031 are marked superseded. FEAT-0010,
+  FEAT-0018, the Solo glossary, architecture/implementation pages, and this handoff now describe
+  shared profile defaults, remaining gaps, and current verification.
+
+## Check results (2026-11-19)
+
+| Check | Result |
+|---|---|
+| Harness `npm run typecheck` | pass |
+| Harness `npm test` | pass: 163 files, 1,255 passed, 3 skipped |
+| Harness `npm run prove` | pass: build and standalone proof suite; no provider request |
+| App `npm run typecheck` | pass |
+| App `npm test` | pass: renderer 90 files/586 tests; sidecar 11 files/86 tests |
+| App `npm run check:layers` | pass |
+| App `npm run check:ui` | pass: 38 recorded findings, baseline 38 |
+| App `cargo test` | pass: 186 passed, 1 ignored; compiler warnings remain |
+| App `cargo test --features dev-profile` | pass: 189 passed, 1 ignored; compiler warnings remain |
+| App Playwright | pass: all 61 tests with installed Chrome |
+| Xingular UI typecheck and `npm test` | pass: 21 files, 124 tests; the package has no `check:ui` script |
+| Xingular Workspace typecheck | pass |
+| Xingular Workspace `check:ui` | pass: 79 findings, baseline 87 |
+| Xingular Workspace `npm run test:run` | **4 failed, 993 passed**: three `assistantService.test.ts` cases hit the Harness Pi-version guard (requires Pi 1.2.0, found 1.4.0), leaving the fake provider's `release` callback unset; one `commandPaletteNoteItem.test.ts` assertion expects an inline SVG style string that is absent |
+| Xingular Workspace `electron-vite build` | pass (targeted tab-E2E run) |
+| Xingular Workspace tab Playwright (three selected tests) | **3 failed before tab assertions**: shared `launchWithFixture` clicked the Notes sidebar control, then `expectNotePanelReady` timed out. The run used temporary `HOME`, `TMPDIR`, vault and user-data paths; no root cause was established |
+
+Browser command: `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" npx playwright test --reporter=list`.
+
+No provider calls or owner profiles were used. Tests use fixture or temporary data. The Workspace test failures were not changed as part of this task; the shared-tab tests in Xingular UI and App Playwright passed.
+
+## Remaining gaps and decisions
+
+1. **Parity acceptance is not complete.** The source routes and command handlers are present, but each fixed core command still needs its own acceptance. `PAR-002` (Harness History/Wiki/skill tools) and `PAR-006` (first-party hooks) are implemented on both surfaces but acceptance has not been recertified. `get_capabilities` is now Harness-owned; the App has no duplicate tool.
+2. **The session catalog remains separate (`PAR-008`).** App `/session` lists App-owned Solo threads; terminal `/session` lists native Pi histories. The read-only audit recommends a Harness-owned catalog of opaque references to existing native histories—not merging or copying transcripts or IDs. Keep logical/App and native Pi IDs distinct; retain the exact locator privately, preserve account/path/cwd guards, fail rather than substitute an unknown account, and serialize shared writes. This is a recommendation, not an implementation; do not claim `/session` parity.
+3. **Other registered gaps remain:** `PAR-001` App checklist surface; `PAR-003` continuation; `PAR-004` terminal variant/refinement actions; `PAR-005` App-only Wiki browsing; `PAR-007` host-backed computer/files capabilities; `PAR-009` shared recent-folder choice; `PAR-010` Solo `/agents` detail/management; `PAR-011` native WebKit annotation-gesture acceptance; `PAR-012` Solo worktree status/create/remove; and `PAR-015` native WebKit browser coverage. Unsupported browser refs, accessibility snapshots, screenshots, waits, and key presses explicitly refuse before effects; there is no automatic switch to the isolated Harness browser.
+4. **Profile interoperability is intentionally bounded.** Production App and standalone share profile-selected data/state defaults; explicit roots, `--variant`, and historical run pins remain authoritative. The App's per-agent variant is still an App-supplied override. App credentials use the host Keychain backend; a frontend without that host adapter fails closed, and disposable App identifiers are blocked until an isolated Keychain adapter exists. Shared roots do not mean credential-store copying or automatic account substitution.
+5. **Native App acceptance was not performed.** The full Playwright suite ran against isolated browser fixtures, not a Tauri window. No real-model request or user profile was used; the native Keychain and WebKit surfaces therefore remain unverified in a running App.
+6. **Workspace test failures need a separate follow-up.** `assistantService.test.ts` requires the pinned Pi runtime but this Workspace installation resolves Pi 1.4.0; `commandPaletteNoteItem.test.ts` has an SVG markup expectation mismatch. Typecheck and `check:ui` pass.
+7. **Commits:** one per repository, in order Harness → Xingular UI → App, only when the owner asks. No files were committed in this work.

package/docs/parity.md

@@ -0,0 +1,158 @@
+# Capability parity register
+
+**Status:** descriptive register, as of 2026-11-19. The binding rules are
+[14 Surfaces and parity](architecture/14-surfaces-and-parity.md) (`INV-PAR-1`–`INV-PAR-4`).
+
+Every capability a person can use is a Harness capability. The standalone terminal (`xagent`)
+is the reference front end; a host such as the App presents the same capabilities with a richer
+UI. This page lists each capability, where the Harness owns it, how each front end shows it, and
+whether both pass. A gap has an ID (`PAR-NNN`) until it is closed.
+
+Host-only surfaces (presentation a terminal cannot show, `INV-PAR-4`) are not listed here; each
+host keeps its own register. The App's is
+[`App/docs/architecture/app-only-surfaces.md`](../../App/docs/architecture/app-only-surfaces.md).
+
+Status: **parity** only where both surfaces passed acceptance; **implemented** means source routes
+exist but acceptance is not certified; **terminal only**, **host only**, **partial**, **planned**,
+and **host-backed** (needs a host object; terminal fallback named). A slash-command row marked
+implemented is not a parity claim; acceptance is tracked per command.
+
+## Register
+
+| Capability | Harness owner | Method or tool | Terminal surface | App surface | Status | Gap |
+|---|---|---|---|---|---|---|
+| Sessions and turns | `sessions/` | `sessions.run`, `terminal.*` | the terminal itself | Solo chat | parity | — |
+| Pending follow-up and steering queues | Pi session queue, terminal queue projection | `followUp` and `steer` delivery modes | clickable native queue rows; `/follow-up` edits, sends next or removes, preserving images; on explicit user stop send one unconsumed steer before follow-ups; never drain on retry/failure/non-user interruption | inline Send now/Remove controls; successful completion stays FIFO, explicit stop prioritizes an undelivered steer; `/follow-up` points to the inline queue | implemented; acceptance not recertified | — |
+| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; shared outcome and bounded repair; a reply that needs no plan ends with no card or warning; plan/todo context restored after compaction | plan request, PlanCard for a complete block and nothing otherwise; shared Harness classification and checkpoint behavior | ADR-0077 `no_plan` outcome implemented; surface acceptance not recertified | — |
+| Goal (`/goal`, ADR-0072) | `sessions/goal.ts`, `sessions/goalLoop.ts`, `sessions/goalPrompts.ts` | `sessions.run { goal }`, `goalMode` on the run record, model tools `get_goal`/`update_goal` while a goal exists, `extension: 'goal'` notices | `/goal [<objective>\|edit\|pause\|resume\|clear]`, `--rounds`/`--hours`, footer label, Esc pauses, goal restored `paused` from the Pi session | not wired: no goal control or status | terminal implemented; App presentation planned | PAR-017 |
+| Capability discovery | `tools/getCapabilities.ts` | read-only `get_capabilities` | terminal extension reports Pi's active tools and schemas; shared plan allowlist includes it | structured Harness run uses the same tool; no duplicate App-owned tool | implemented; acceptance not recertified | — |
+| Bash command mode | `sessions/sessions.ts`, `sessions/initialBash.ts` | `initialBashCommand`; Bash `workspaceWriteScope` | `!command` defaults to workspace; `!outside command` asks before running once | same `!command` and `!outside command` composer semantics | parity | — |
+| Workspace-scoped writes | `core/workspace.ts`, `sessions/workspaceBoundary.ts`, `core/workspaceBashTool.ts`, `core/workspaceSandbox.ts`, `core/workspaceWriteOperations.ts` | pinned non-root `RunRecord.workspaceRoot`; native `edit`/`write`; Bash scope | revalidated atomic native writes; external-hard-link scan and Bash sandbox (Windows: no sandbox, each Bash call asks once, plan-mode Bash refused; ADR-0042); complete escaped outside command in scrollable approval details (deny if too small); no output-triggered retry | same Harness gate and full approval action in scrollable App details; App policy can tighten scope; Full Permission remains the eligible explicit bypass | parity | — |
+| Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock; the answer renders as Markdown, with scroll and copy | side-question dock through the shared service | parity | — |
+| Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*`; run events `approval.requested`/`approval.resolved` | decision dock, `/permissions`; the call pauses in `waiting_for_approval` and resumes in the same turn | approvals dock above the composer, approval notification in the notification inbox and as a system notification while the window is hidden; settings | parity | — |
+| Opening a link | `core/links.ts` | `links.open`; `HarnessOptions.linkOpener` (ADR-0047) | hover shows the hand pointer and recolours the link, Ctrl+click (the primary click on macOS, whose ⌘ the mouse protocol cannot report) opens web, `mailto:`, file and folder targets with the system handler, a refused link posts a notice | ⌘-click on macOS and Ctrl+click elsewhere opens with the system handler, a plain click keeps the sidebar and falls back to the system for what it cannot show, `a:hover` uses `--link-hover` | implemented; acceptance not certified | — |
+| Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, fixed 80-column padded sketch canvas with a viewport-bounded frame and horizontal panning; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028, ADR-0080) | plan-mode form accepts the same permissive 80×24 ASCII source contract with a literal, horizontally scrollable preview; no App code change required | existing question surface parity; ADR-0058 plan clarification contract not verified | — |
+| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles; per-profile and total child budgets enforced in `Subagents.spawn` (ADR-0052), with the same refusal result in both surfaces | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
+| Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*`; package profiles through `Loading.profilePaths` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete; package profiles listed under "From a plugin" and switched on `/plugins` | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
+| Run todo list | `tools/todo.ts` | `todo_write`, `runs.todo` (`runs.checklist` deprecated); terminal `todo` telemetry | registered in terminal sessions and their subagents; each write shows as a todo block in the transcript; `/todo` shows the current list; a subagent row shows its `n of m tasks` | `/todo` shows the current list on demand; each write is not rendered inline | terminal done; App shows it on demand | PAR-001 |
+| Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
+| Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts`, `sessions/stallWatch.ts` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; every harness run and terminal reply heartbeats and a reply with no progress for fifteen minutes ends as `stalled` (a stalled live session is closed), a reply waiting on subagents is judged by each child's own clock, and the working row names what it waits on; the handoff is recorded on the run; no checkpoint card or slice control yet | not wired | implemented; terminal card, App presentation and `/slices` open | PAR-004 |
+| Accounts | `accounts/` | `accounts.*` | `/accounts` | Accounts | parity | — |
+| Models and effort | `accounts/choices.ts` | — | `/model`, `/effort` | composer pickers | parity | — |
+| Skills | `plugins/`, `tools/dispatch.ts`, `prompt/compile.ts` | `skill_load`; `Launch.requiredSkills` | `$name` at any word start (required for that request), `/skill:name`, browser Skills tab | composer `$` chip with `requiredSkills`; Capability | implemented; install routes taught in the release-owned skill, foreign manifest skills load as package skills; acceptance not recertified | — |
+| Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | full-screen `/plugins` local manager; separate full-screen `/hub` Community catalog with bounded registry/document Preview (no Pi-package Preview) | local Plugins manager; Community Hub with payload Preview for non-package entries | parity | — |
+| Plugin authoring and proposal review | `plugins/proposals.ts`, `tools/defaultSkills.ts` | `plugin_propose`, `plugins.proposals.*` | `/plugins` Proposals tab: preview, accept or reject | structured model tool and skill; review UI not implemented | partial; App review pending | PAR-017 |
+| Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
+| Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
+| Browser (isolated or Brave) | `browser/`, `browser/extension/` | shared `browser_*` schemas; `browser.config`, `browser.extension.*` | isolated or connected Brave tools; `/settings` selects the device backend, pairs the extension and shows status | WebKit: navigate, tabs, visible-text read, page screenshot and page scroll without refs; Brave: shared snapshot-ref tools through the paired extension; `browser_upload` remains WebKit-only; no fallback on disconnect | implemented; disposable loopback acceptance passed; non-loopback host grant prompt untested; WebKit gap remains | PAR-015 |
+| Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038, PROP-0048) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` page (Annotate and All annotations tabs; DevTools app list and launch), `/annotate:notes`, `/annotate:submit`, `/annotate:clear` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | App behind PROP-0048 (queue methods removed); native WKWebView gestures unaccepted | PAR-011 |
+| Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | Solo `/worktree` lists records only; Solo starts sessions in the project folder and has no worktree level | partial | PAR-012 |
+| Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `Terminals.ownTools` registers Wiki-read tools through the session socket; `xagent-wiki` remains a person-facing shell utility | structured Harness tools | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
+| History and trajectory (model tools) | `history/` | `history_*`, `trajectory_*` | `Terminals.ownTools` registers model tools through the session socket; `/trajectory` shows refusal events and interrupted status reasons or codes; `/history` navigates session branches | structured tools and trajectory views | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
+| Wiki browsing | `wiki/` | `wiki.*` | none | Wiki | host only | PAR-005 |
+| Variants and refinement | `variant/`, `refine/` | `variants.*`, `refine.*` | `/variant` (switch, restore, compare, tag, take components), `/refine [guidance]` with background status and review/adopt, browser Variant tab, `xagent refine` | Harness screen; `/refine` and `/variant` open it | host only | PAR-004 |
+| Output trim and budget guard plugins | `plugins/firstParty.ts` | trusted first-party hooks | `firstParty.list` loads enabled hooks in `terminal/piExtension.ts` | structured Harness sessions load enabled hooks | implemented on both; acceptance not recertified | PAR-006: acceptance not recertified |
+| Doctor | `doctor/` | `doctor.*` | `/doctor` | diagnostics | parity | — |
+| Run inspection | `sessions/runStore.ts` | `runs.*` | `/trajectory`, `/log` | run views, analytics | parity | — |
+| Usage analytics | `usage/` (PROP-0042) | `usage.summary`, `usage.sync` | `/usage:`, `/usage:analysis` page (Analysis tab) | not wired | terminal implemented; host planned | PAR-016 |
+| Remote control (ADR-0056) | `remote/` | protected `terminal.remoteControl.*`; phone calls through `Terminals.send` and the terminal controller | `/remote-control` (`/rc`) page with link, QR code, devices and pair confirmation; `rc` status-bar group; `--remote-control`; the served phone page | stub: App sessions are not terminal sessions | terminal only | PAR-018 |
+| Run details | `context/runDetails.ts` | `context.runDetails`; protected terminal trajectory details | `/context` Run details tab, scoped run selection and links to `/trajectory` | Context Run details tab and links to Trajectory | implemented; acceptance not certified; skill observations cover `skill_load` only and terminal plugin activation is unknown | — |
+| Context attribution (PROP-0049) | `context/` | `context.attribution`; protected `terminal.context` | `/context` page with Request and Growth tabs, a four-colour context bar with a free track and a compaction marker, `space` fold, `enter` row text, `g` grouping, `c` compact; the page header reads `18.3%/1M`, and the composer status band carries no context figure | full-width Context page opened from the Context tab with the same four-colour bar and a screen-reader reading of it, composer ring reading the same share | implemented on both; acceptance not recertified | — |
+| Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
+| Session catalog (sessions per folder) | `sessions/` saved-history controls; shared catalog not implemented | `sessions.*` controls; no cross-surface catalog method | `/session` selects native Pi histories in the current folder | `/session` reads `bridge.agent.threads(SOLO_ID)`, maps each thread to its project folder, and filters by current effective account; `all` broadens only this App list | planned; catalogs differ | PAR-008 |
+| Folder choice and recent folders | project/worktree selection remains surface-specific | launch `cwd`, `--worktree`, `/worktree` | starts in launch folder; explicit worktree commands | Solo sidebar is Project › Session; new sessions use the project's folder, with no folder/worktree level | planned; no shared recent-folder picker | PAR-009 |
+| Computer control | `computer/screenshot.ts` defines an opt-in approved-window screenshot contract; `computer/control.ts` is an unregistered interaction adapter, not an authorization boundary | `computer_*` (host tools) | no computer screenshot or interaction backend | macOS bridge (host-backed); its display capture has not adopted the approved-window contract | partial; shared interaction adapter is not integrated | PAR-007 |
+| Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
+
+## Plugin command namespaces (ADR-0061)
+
+The approved contract gives plugin-owned extension commands and plugin-owned prompt templates the
+same `/<owner-prefix>:<name>` namespace, with no bare plugin aliases. A package may set
+`harness.defaultPrompt` to its own template for `/<owner-prefix>:`; built-in defaults remain
+supported. Owner-prefix and same-owner route collisions fail closed with owner diagnostics.
+Standalone templates, `/skill:<name>`, and core commands and their core aliases remain available.
+`commands.list`, terminal completion and dispatch must agree; this documentation change does not
+certify implementation or acceptance on either surface.
+
+## Core slash-command surfaces (PROP-0040)
+
+These are the fixed `CORE_COMMANDS` entries. The App column records the current Solo source route,
+not a claim that it has passed acceptance. `commands.list`, a handler-completeness test, and source
+presence do not certify parity. Each command needs its own acceptance evidence; dynamic
+plugin/extension, prompt-template and skill commands are listed by `commands.list` but are not in
+this fixed table.
+
+| Command | Terminal surface | App Solo route in source | Acceptance / remaining gap |
+|---|---|---|---|
+| `/help` | Command list and palette | Searchable command picker; selection fills the composer | Not certified per command |
+| `/plan` | Plan request / mode toggle | Plan request; bare form toggles persistent plan mode; model Bash runs read-only (PROP-0043) | Not certified per command |
+| `/goal` | Set or view a goal; edit, pause, resume, clear | Not wired: PAR-017 | Not certified per command |
+| `/btw` (`/side`) | Contextual side-question dock | Shared side-question service; bare form dismisses the dock | Not certified per command |
+| `/new` | New conversation | Replaces focused tab with a draft; archives its saved session | Not certified per command |
+| `/stop` | Interrupt current reply; explicitly releases the next eligible native queue item after settlement | Stops the focused session and sends the next eligible queued item after an explicit stop | Not certified per command |
+| `/follow-up` | Opens the follow-up and steering queue editor | Points to the existing inline queue and its Send now/Remove controls | Not certified per command |
+| `/session` (`/resume`) | Search/select native saved history in the current folder | Lists App Solo threads by folder and effective account; `all` widens only within that App list | PAR-008: separate catalogs; no native-history path opening; not certified |
+| `/history` (`/tree`) | Navigate branches in the current native session | Calls `session.navigate` with stable native entry ID; same-session navigation, optional summary, no fork fallback | Route uses Harness `sessions.navigate`; per-command acceptance pending |
+| `/fork` | Fork from a user message | Uses session tree/fork and opens the new session | Not certified per command |
+| `/remote-control` (`/rc`) | Pairing link, QR code and devices; phone page served by the harness | Stub notice: remote control runs from an `xagent` terminal session | PAR-018; terminal only |
+| `/clone` | Clone the current branch | Uses session clone and opens the copy | Not certified per command |
+| `/model` | Choose model | App model picker updates session runtime | Not certified per command |
+| `/effort` | Choose reasoning effort | Updates session runtime effort | Not certified per command |
+| `/thinking` | Toggle thinking display | Toggles transcript thinking visibility | Not certified per command |
+| `/name` | Name the native session | Renames the saved session | Not certified per command |
+| `/compact` | Compact current context | Runs Harness compact command | Not certified per command |
+| `/copy` | Copy last reply | Copies last reply to the clipboard | Not certified per command |
+| `/export` | Export HTML or JSONL | Runs Harness session export; relative paths resolve from the project folder | Not certified per command |
+| `/trajectory` | Inspect recorded runs | Opens trajectory view for the requested or latest run | Not certified per command |
+| `/reload` | Reload trusted resources and keybindings | Reloads Harness resources and refreshes command discovery | Not certified per command |
+| `/accounts` | Accounts page | Opens App Accounts | Not certified per command |
+| `/permissions` | Permissions page | Opens App approval settings | Not certified per command |
+| `/harness` | Harness resource browser | Opens App Harness screen | Not certified per command |
+| `/skills` | Skills browser shortcut | Opens Capability skills | Not certified per command |
+| `/connections` | Connections browser | Opens App connectors | Not certified per command |
+| `/mcp` | Connections browser shortcut | Opens the same App connectors view | Not certified per command |
+| `/tools` | Tools page | Opens Capability tools | Not certified per command |
+| `/plugins` | Full-screen local Plugins manager | Opens local Plugins manager | Not certified per command |
+| `/hub` | Separate full-screen Community Hub catalog | Opens Community Hub | Not certified per command |
+| `/components` | Components browser | Opens App Harness components | Not certified per command |
+| `/settings` | Terminal settings | Opens App settings | Not certified per command |
+| `/doctor` | Doctor checks, including explicitly confirmed live probes | Runs local readiness checks only | Not certified; App route does not expose live checks |
+| `/worktree` | Managed-worktree page and actions | Lists worktrees; Solo has no typed create/status/remove methods wired, and no worktree level | PAR-012; management actions unavailable; not certified |
+| `/subagents` | Live monitor and roster with the `main` row, restored on reopen | Opens latest run's trajectory, not a dedicated subagent roster | Not certified; surfaces differ |
+| `/agents` | Browse/create/edit/copy/delete profiles | Lists profiles only; detail/create/remove methods are not wired into Solo | PAR-010; management actions unavailable; not certified |
+| `/log` | Harness diagnostics and current run events | Opens latest run's trajectory, not a separate log reader | Not certified; surfaces differ |
+| `/hotkeys` | Keyboard controls | Opens App shortcut settings | Not certified per command |
+| `/quit` | Restore terminal and exit | Closes the focused Solo tab; does not exit the App | Not certified per command |
+
+The terminal-only display amendments [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md)
+and [PROP-0028](architecture/proposals/PROP-0028-normalize-question-wireframes.md) permit connected
+structural glyphs, frame-attached standalone dividers, and high-confidence boundary normalization
+through whitespace while retaining literal ASCII persistence and unchanged answers. The App may
+keep its literal preview. This does not reopen the expanded metadata contract verified under
+PAR-013. Isolated production PTY evidence verifies bounded fixture topology, not every emulator/font
+or live-model sketch quality.
+
+## Gaps
+
+| ID | Gap | Planned change |
+|---|---|---|
+| PAR-019 | Client terminal (ADR-0083) | The default terminal runs on harness live sessions; `--daemon` and `xagent attach` let a reply outlive its window. The full production PTY run passes at 40x20, 80x24, 100x30 and 120x40, with the focused suites as recorded in ADR-0083; the suites that still fail fail the same way on the previous release's in-process runtime (Known drift D-30, D-31). Plugin custom TUI components, key handlers, renderers, shortcuts and themes need `XINGULAR_TERMINAL_RUNTIME=inprocess` (INV-TUI-8). Provider limits are captured by the harness's own model runtime; `/goal` runs as a harness goal. |
+| PAR-018 | Remote control from the App | `/remote-control` drives an `xagent` terminal session from a phone (page 15). App sessions are structured runs, not terminal sessions; the App would need the same pairing over its own session controls, or to present a terminal session's remote control. ADR-0083: App chat turns now run on live sessions (`live: true`), the same path a client terminal uses, so remote control can move to live sessions; not built yet. |
+| PAR-017 | Plugin proposal review surfaces | The terminal provides hash-bound review in `/plugins`; the App has no proposal review UI yet. |
+| PAR-001 | Todo list not rendered inline in the App | Both surfaces can show the current list: the terminal renders each write as a todo block and `/todo` shows a snapshot; the App's `/todo` shows a read-only list. The App still does not draw an inline block for each write. |
+| PAR-002 | Acceptance of terminal-model History/Wiki/skill tools | Source gap resolved: `Terminals.ownTools` registers History/trajectory, Wiki-read and skill tools over the session socket; `xagent-wiki` is a user-facing shell utility, not the model's only route. Acceptance has not been recertified in this documentation pass. |
+| PAR-003 | Continuation unused | `/resume` lists interrupted runs and continues one with `continueFrom`; the App offers Continue. |
+| PAR-004 | Replaying a turn and switching a conversation's version only in the terminal | The terminal has `/refine` (replay, guidance, review, adopt) and `/variant` (PROP-0052). The App's Harness screen lacks replaying an App turn, guidance, tags, per-component revert and switching an open conversation to another version. |
+| PAR-005 | Wiki browsing only in the App | A `/wiki` page over `wiki.*`. |
+| PAR-006 | Acceptance of terminal first-party hooks | Source gap resolved: enabled hooks are returned by protected `firstParty.list` and loaded by `terminal/piExtension.ts`. Acceptance has not been recertified in this documentation pass. |
+| PAR-007 | Host tools without a complete Harness surface | The opt-in screenshot contract and unregistered interaction adapter exist, but terminal availability reporting, per-action authorization and a conforming backend are not wired. The current macOS host captures a display, not an isolated approved window, and uses global input. Terminal socket execution and native input delivery require a verified authorization boundary before control tools can be exposed. The remaining computer controls are host-owned; the files vault becomes a Harness capability or is dropped. |
+| PAR-008 | Separate session catalogs | Proposal approved; shared catalog is not implemented. Terminal `/session` selects native Pi history in the current folder. App `/session` reads Solo `agent.threads`, maps threads through Solo project groups, and filters to the current effective account and folder; `/session all` broadens only within that App catalog. It cannot open an arbitrary native session path. No cross-surface catalog or visibility guarantee exists. ADR-0083: `sessions.live` lists the live sessions of one harness, and the long-lived harness lists detached terminal replies (`terminal.detached`); neither is a catalog of saved sessions. |
+| PAR-009 | Shared folder/recent-project choice | Terminal starts from its launch `cwd` and can switch through its worktree surface. App Solo uses Project › Session and starts new sessions in the selected project's folder; it has no folder/worktree level or shared recent-folder picker. |
+| PAR-010 | Agent profile management in Solo | App Solo `/agents` can list profiles. Although the renderer allowlist includes `agents.get`, Solo does not wrap it; `agents.create/remove` are not exposed there. Profile details and management actions are unavailable, unlike terminal `/agents`. |
+| PAR-011 | Web annotations | Harness, terminal and App source done (PROP-0017, PROP-0018, 2026-10-24): the App calls `annotations.*`, imports its old notes once, uses the `page_notes_*` tools, and has the Annotate panel. Open: acceptance of the inspector and selection gestures in the running App's WKWebView. PROP-0038 (2026-10-25): both front ends share the page helper, so open shadow roots work in the terminal's capture browser and the App's tabs alike; composed text capture, save, resolve and reveal were exercised in an isolated App WKWebView, inspector clicks were not. PROP-0048 (2026-10-27): Harness and terminal moved to pending/sent with two popover actions, send-all with an optional request, clear, read-only page-note tools, and DevTools app discovery and launch; the App's Annotate panel still uses the removed queue methods and must follow. |
+| PAR-012 | Managed worktree management in Solo | Harness and terminal provide full worktree operations (PROP-0016). Solo `/worktree` lists records only: its renderer adapter does not wire typed `worktrees.create`, `status` or `remove` calls, and Solo session creation stays at the project folder with no worktree level. Handoff, branch, prune, restore and setup-trust actions are also absent from this Solo surface. |
+| PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |
+| PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |
+| PAR-016 | Usage analytics and provider limits in the App | The terminal has `/usage:analysis` and `/usage:limit` over `usage.*`. The App presents the same capability: an analytics view and a per-account provider limit view. |
+| PAR-017 | Goal in the App | The terminal has `/goal` over `sessions.run { goal }` (ADR-0072). The App has no way to set, edit, pause, resume or clear a goal, or to show its status, rounds and time; it can read `goalMode` on a run record and the `extension: 'goal'` notices. Pause and resume across unrelated runs need `goal.set/get/clear` methods that are not built yet. |
+| PAR-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads, page screenshots and scrolling without refs; live screenshot acceptance is pending. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll/ref-screenshot), waits and keyboard presses return an explicit `browser_unsupported` refusal before effects; there is no automatic switch to the isolated Harness browser. See page 13 and the native backend's `surfaces` note. |

package/docs/releases/1.0.0.md

@@ -0,0 +1,40 @@
+# Xingular Harness 1.0.0
+
+This release establishes @xingular/harness@1.0.0 as the stable baseline and retains the xharness
+command. It intentionally resets the earlier development numbering; historical tags and published
+versions remain unchanged. The npm registry published 1.0.0 as the stable baseline; this file
+remains its release notes.
+
+## Included
+
+- Pi execution with isolated accounts, pinned models/capabilities, gated tools and recorded usage.
+- Foundation/variant architecture, validated c1–c8 variants, version history, continuation,
+  answer-free refinement and opt-in lessons.
+- Wiki notes, history/trajectory tools, MCP connectors, plugins, Hub installation and terminal UI.
+- Generic web search/fetch and isolated browser tools, plus account and backend diagnostics in
+  /doctor. Local inspection is the default; selected live probes require consent.
+- Compiled Node ESM SDK and TypeScript declarations, including supported subpath imports.
+- Apache-2.0 for original project code, with retained upstream attribution and license texts.
+
+## Installation and requirements
+
+Use `npm install --global @xingular/harness@1.0.0`, then `xharness`. Node 22.19 or later is required.
+The terminal additionally requires Bun; release CI uses Node 22.19.0 and Bun 1.4.2. Browser operation
+requires an installed compatible browser or a deliberately configured endpoint. Model credentials
+are configured inside an isolated Harness account.
+
+## Migration
+
+- SDK tree symbols/paths become variant symbols/paths: VariantChoice, seedVariant, variant/*.
+- Server harnesses.* methods become variants.*. Session/context inputs use variant; variant
+  snapshots use variant and materialisation returns files. Old method aliases are not provided.
+- Existing stored data is migrated without overwriting; historical run records remain readable.
+- Versions numerically above 1.0.0 will not receive this release through higher-major semver ranges.
+  Install the exact version or latest tag deliberately.
+
+## Diagnostics limitations
+
+Local readiness is not live connectivity. Doctor never signs in, switches accounts or repairs
+settings. Provider probes may incur charges. Computer input remains blocked when the embedding
+host cannot provide an isolated diagnostic surface. Runtime execution and compiled artifacts are
+validated independently from publication; see the release checklist for actual gate results.

package/docs/releases/1.1.1.md

@@ -0,0 +1,28 @@
+# Xingular Harness 1.1.1
+
+The first published release of the 1.1 line, and npm `latest`. It follows the published 1.0.0
+baseline. The 1.1.0 tag was pushed, but its release run stopped before publishing, so nothing was
+published under 1.1.0.
+
+## Agent profiles and named subagents
+
+- A subagent can start from a named profile: the built-in `worker` and `explorer`, a person's
+  `<data root>/agents/<name>.md`, a repository's `.xingular/agents/<name>.md`, or a variant's c5
+  subagent. A profile narrows the child's tools and plugins and may choose its variant, model and
+  effort (PROP-0029, ADR-0030).
+- The parent names each subagent. `spawn_subagent` requires a short `title`; `subagents.spawn`
+  takes an optional one (PROP-0030). The live roster, `/subagents` and the transcript show the
+  title.
+- The terminal runs the checklist tool and shows each write as a checklist block. An in-progress
+  item shows a yellow dot, and a running subagent's row shows the working spinner in its profile's
+  colour.
+
+## Release pipeline
+
+- The release pack and smoke scripts take their npm cache from the system temp folder. They
+  previously used a macOS-only path, which failed on Linux runners.
+- The `/help` terminal check matches the documented grouped, scrollable help: it pages until every
+  group is seen, and its expected group is `Plugins`.
+
+Checks for this release: `npm run ci` (148 test files, 1111 tests), the exact-tarball fresh
+installation smoke test including the packaged terminal, and the release preflight.

package/docs/releases/1.2.0.md

@@ -0,0 +1,49 @@
+# Xingular Harness 1.2.0
+
+This release builds on the published 1.1.1 line.
+
+## Compatibility note
+
+The filesystem root cannot be used as an active workspace, because that would make the boundary
+meaningless. The workspace boundary is intentionally stricter: model-controlled writes outside the active project,
+including writes to temporary directories, require a one-call approval unless the eligible Full
+Permission switch is explicitly enabled. Remembered per-tool grants do not cover them; unattended
+runs cannot request approval. The Full Permission switch remains off by default. A workspace with
+an external hard-link alias blocks default-scope Bash until the alias is removed or the file is
+replaced with a copy. Native writes use atomic replacement and preserve ordinary file mode where
+possible; ACLs and extended attributes are not guaranteed to survive replacement. On macOS, the
+sandbox also blocks workspace-local hard-link creation.
+
+## Workspace write boundary
+
+Model-controlled file writes and Bash are scoped to the active project workspace by default. Native
+write/edit operations revalidate the target and atomically replace the directory entry under an
+OS-enforced write scope, so an in-workspace hard link does not modify an outside alias. Default Bash
+scans for external hard links and runs in an OS sandbox that prevents cross-boundary hard-link
+creation; unavailable or incomplete enforcement fails closed. Reads remain unchanged. Explicit
+outside Bash writes require pre-execution one-call approval and run exactly once (`workspaceWriteScope:
+'outside'`; in the terminal composer, `!outside <command>`). The approval shows the complete quoted
+command in scrollable details; if the terminal is too small to show both details and choices, the
+request is denied. Command output cannot trigger approval or automatic retry. Runs record their
+resolved `workspaceRoot`; older run records remain readable.
+Protection from a separate same-user process outside Harness is not provided.
+
+## Planning and run continuity
+
+Plan mode now requires evidence-grounded repository research and can delegate bounded read-only investigations to eligible research profiles. After compaction, active runs rehydrate the latest checklist and plan instructions. The terminal keeps the latest subagent status visible until its next run.
+
+## Terminal commands and annotations
+
+Plugin-owned terminal commands use `/<owner-prefix>:<command>`, while Harness-owned routes such as `/doctor`, `/worktree`, `/trajectory`, `/subagents`, and `/agents` are first-class core commands. Prior command forms remain hidden compatibility aliases for one release; migrate scripts and keybindings to the canonical names.
+
+The annotation inspector now supports content in open shadow roots, including composed selections and targets. Closed shadow roots and frames remain unsupported, and existing document-only annotations retain their behavior.
+
+## Terminal interaction
+
+`/session` without a path now opens a searchable saved-session picker. Composer history includes user prompts, Bash commands and executed slash commands; browsing temporarily replaces the draft and restores its cursor, mode and attachments when it returns. Compact question docks now size each tab independently, keep nested sketches scrollable, and preserve page-footer hints at narrow widths.
+
+## Performance evidence
+
+Adds reproducible PTY and session-runtime profiling and publishes the [EXP-0003 report](../experiments/EXP-0003-performance-audit/results.md). That report is a 1.1.1 baseline captured from a dirty worktree, not a clean 1.2.0 benchmark; it also records a failed narrow-width `/settings` footer check and other measurement limits.
+
+Node 22.19 or later is required. Building or running the standalone terminal also requires Bun 1.3.14 or later. See the project license and notices for third-party terms.

package/docs/releases/1.3.0.md

@@ -0,0 +1,21 @@
+# Xingular Harness 1.3.0
+
+This minor release builds on 1.2.0 with clearer run progress, more reliable work-slice limits, bounded plan research, and distinct local-plugin and Community Hub experiences.
+
+## Run progress and work slices
+
+- `session_name` guidance names the session before the first tool call when a request needs tools or changes state. Multi-step work uses `todo_write`; the prompt and tool descriptions share the same concrete guidance.
+- The run checklist is now a todo list: `todo_write`, `todo.updated`, `runs.todo`, the `todo` plugin and a terminal todo block. `/todo` displays the current list without a model request; `/checklist` remains an alias. Existing `checklist.updated` events are still read, and legacy pinned tools and server methods remain available as deprecated compatibility aliases for one release.
+- Work slices default to 320 tool calls and 60 minutes, with no token cap unless configured. Stall detection recognizes meaningful progress, bounds repeated calls by name and arguments within each reply, and resets its counters between replies.
+- Plan research can delegate only to named profiles whose effective tools and plugins qualify for read-only research. The active plan and latest todo list are restored after compaction.
+
+## Plugins and Community Hub
+
+- `/plugins` is a dedicated local plugin manager for installed packages, switching, trust, settings, install, update and removal. `/hub` is a separate Community catalog with Catalog and Installed views; Installed retains receipts from every channel and labels each channel.
+- Hub shows cached or bundled catalog entries before refreshing remotely, and exposes origin, refresh time and stale/error status. Registry/document entries keep a bounded payload Preview; Pi packages have no payload Preview. Hub-owned packages remain pinned to receipt versions: removal is receipt-aware, and floating plugin updates cannot silently replace them.
+- No catalog schema or storage migration is required; existing receipts, settings and trust remain intact. The broad `/harness` resource browser remains available.
+
+## Terminal
+
+- Skill completion and syntax highlighting distinguish enabled skill invocations, command names and arguments while retaining the existing composer workflow.
+- Doctor's Bash readiness check now requires the platform write-boundary sandbox. Its live check runs one fixed, no-network command through the same workspace boundary as normal Bash, reports only the exit status, and stays subject to policy without being widened by Full Permission.

package/docs/releases/1.3.1-unstable.1.md

@@ -0,0 +1,8 @@
+# Xingular Harness 1.3.1-unstable.1
+
+Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
+
+- Import agent profiles from compatible plugins and continue stopped subagents across interruptions and restarts.
+- Improve Windows shell, workspace write and edit support, with explicit per-call approval where an OS write-boundary sandbox is unavailable.
+- Extend Doctor to check the active shell and exercise its workspace boundary with a fixed, no-network probe.
+- Improve terminal subagent progress and plugin management, plus work-slice and plan-research behavior.

package/docs/releases/1.3.1-unstable.2.md

@@ -0,0 +1,11 @@
+# Xingular Harness 1.3.1-unstable.2
+
+Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
+
+- Swap the OpenTUI send keys back. `Return` sends, or steers a running reply, and `Cmd+Return`,
+  `Ctrl+Return` or `Alt+Return` queues a follow-up. The `app.message.followUp` action replaces
+  `app.message.steer`, so a `keybindings.json` entry under that name needs renaming.
+- Show pending steering, follow-up and deferred plan/Bash inputs above the working line, each with
+  its delivery type. A queued plan or `!` command is a barrier: it runs as a standalone turn and
+  later inputs wait behind it instead of entering Pi's native queues.
+- Restore queued text to the draft with `Alt+Up`. Queued images are dropped; deferred images warn.

package/docs/releases/1.3.1-unstable.3.md

@@ -0,0 +1,54 @@
+# Xingular Harness 1.3.1-unstable.3
+
+Unstable preview of the current Harness work. Install with `npm install @xingular/harness@unstable`.
+
+- Name a skill anywhere in a message: `$name` at any word start makes that skill required for the
+  request (ADR-0048). `Launch.requiredSkills` carries it, and the compiler renders a
+  `required-skills` section at order 52 from the pinned variant through `readSkillFile`, bounded at
+  12,000 characters. An unavailable skill is named honestly instead of invented, and the built-in
+  `plugin-authoring` skill stands in when the variant ships no skills. The section belongs to the
+  request, so an identical one is delivered again rather than deduplicated. The terminal builds the
+  same text with `requiredSkillsText` and appends it as a hidden `xingular-required-skills` message,
+  so the person's own wording reaches the model unchanged. In the composer the `$` palette opens at
+  the caret and inserts there, keeping the rest of the draft.
+- Bound delegation per run and per profile (ADR-0052). A run now starts at most four distinct child
+  conversations: two `worker`, three `explorer`, one of any other named profile and one with no
+  profile. `SessionRunInput.subagents` / the SDK's `Subagents` options override them with
+  `maxChildren`, `maxByProfile`, `maxOther` and `maxUnprofiled` (clamped to 0–50), and the model's
+  `spawn_subagent` description states the budget it has left. `Subagents.spawn` refuses a child past
+  a limit with `invalid_request` and starts no run; continuing a stopped child costs no slot, and a
+  work-slice continuation keeps the parent's budget.
+- Read what a request was made of. `context.attribution` returns one row per contributor with its
+  estimated tokens and share of the window, reconciled to the provider's measured total, and one
+  row's text on request; the terminal reaches it through `terminal.context`. The compiler now
+  records where its characters went: `renderSized` returns each section's size and the framing that
+  belongs to no section, `Delivery.sizes` stores them on the recorded pack, and `Source.chars`
+  attributes a variant's tool guidance inside the tools section. `context.snapshot` also records the
+  compaction headroom the run was held to (`compaction: { enabled, reserveTokens }`) from Pi's own
+  settings. The terminal page over this data arrives in a later preview; no `/context` command is
+  registered yet.
+- Add an opt-in approved-window screenshot contract (ADR-0050). `src/computer/screenshot.ts` defines
+  `computer_screenshot` for a host-supplied backend: it captures exactly one currently approved
+  window, excludes the desktop, other windows and overlapping overlays, and refuses with
+  `COMPUTER_SCREENSHOT_UNAVAILABLE` rather than returning display pixels. It goes through the
+  ordinary tool gate, is not plan-mode safe, and adds no extension point. The standalone terminal
+  has no backend, and the existing macOS host capture has not adopted this contract.
+- Deliver approvals and questions promptly without polling: the control-key-protected
+  `terminal.pending.wait` returns as soon as the pending revision changes and otherwise waits at most
+  20 s, waking on additions, removals and disposal (ADR-0051). `terminal.pending` is unchanged and
+  the server protocol is untouched.
+- Swap the OpenTUI send keys back. `Return` sends, or queues a follow-up behind a running reply, and
+  `Cmd+Return`, `Ctrl+Return` or `Alt+Return` steers that reply. The `app.message.followUp` action is
+  `app.message.steer` again, so a `keybindings.json` entry under the newer name needs renaming.
+- Keep a stray mouse report out of input. A report split across the input parser's timeout no longer
+  types its `<button;column;row>` tail into the composer or a single-line field, so a scroll cannot
+  become a run's prompt or a filter; typing and pastes are untouched and `/trajectory` no longer
+  prints a recorded report.
+
+## Upgrading
+
+- A leading `$name` is no longer rewritten to Pi's `/skill:name`. An embedding host sends required
+  skills as `Launch.requiredSkills`, and the message text reaches the model as written.
+- Runs that spawned children freely now stop at the defaults above; set `subagents` explicitly to
+  change them.
+- A `keybindings.json` entry named `app.message.followUp` is now `app.message.steer`.