@xingular/harness 1.1.1 → 1.2.0

package/docs/experiments/EXP-0003-performance-audit/plan.md

@@ -0,0 +1,109 @@
+---
+id: EXP-0003
+title: Layered Xingular terminal and Harness runtime performance audit
+status: completed
+created: 2026-10-25
+updated: 2026-10-25
+related: [EXP-0002]
+---
+
+# EXP-0003 — Layered performance audit
+
+## Question and falsifiable hypothesis
+
+How much of the user-visible delay belongs to terminal input/rendering, fresh-process startup, and
+Harness session orchestration? After the OpenTUI work in EXP-0002, the hypothesis is that steady
+keystroke-to-screen latency is comparable to Pi and OpenCode, while the Harness layers show up more
+strongly in cold startup and memory. A long transcript should not materially increase Harness input
+latency.
+
+The comparison can falsify this: if Harness p95 grows after history, stays above OpenCode during
+streaming, or Harness session calls contribute large repeatable latency with the injected session,
+those are separate regression candidates.
+
+## Targets and controls
+
+- **Xingular Harness:** built `node dist/cli.js`, with temporary `--state` and `--data` roots, an
+  isolated API-key account, and a loopback OpenAI-compatible model.
+- **Pure Pi:** `@earendil-works/pi-coding-agent` 1.2.0 with an isolated `PI_CODING_AGENT_DIR`.
+- **OpenCode:** v2.1.4 with `--standalone`, isolated XDG roots and a loopback-compatible provider.
+- Each terminal target runs in its own PTY and temporary profile. A local deterministic SSE provider
+  supplies the same fixture response to all targets. No external provider, OAuth profile, or
+  credential is used.
+- Main terminal runs use a 160×45 PTY, 35 ms key interval, two rounds of 30 typed characters and
+  five independent launches for idle, stream and burst. The first eight keys in each round are
+  excluded from latency scoring; each idle run therefore scores 44 keys and each stream/burst run
+  scores 22. Target order rotates between repeats.
+- History uses three launches per target. Each history is an 80-turn local tool loop (about 240
+  transcript messages) before typing is measured. The question scenario is Harness-only and uses
+  plan mode. A separate 80×24 run checks a compact terminal once per target; it is sensitivity data,
+  not a repeated comparison.
+- The runtime benchmark runs in a separate Node process with temporary state/data and a deterministic
+  injected session. It measures SDK import, Harness initialization, cold/warm `terminal.prepare`,
+  run-to-first-persisted-delta/completion, and one local tool-event path. It does not start Bun or a
+  real model.
+
+## Metrics
+
+- Input latency is the time between writing a key to the PTY and the first time its typed prefix is
+  visible on a `pyte` virtual screen (p50/p95/p99/max). Missed keys are reported separately. This
+  includes the PTY and `pyte` parser, not a terminal emulator's physical paint.
+- Startup is measured from process launch to first output, first nonblank visible screen, and a
+  quiet screen (750 ms with no further output). Process-tree RSS is sampled at that initial stable
+  screen. CPU and RSS are process-tree measurements; typing CPU is measured over the typing window.
+- Terminal comparison summaries take the median of each run's metric (including each run's p95); they
+  are not pooled per-key percentiles. Session-runtime summaries use the median of measured samples.
+- No credentialed run is required. The profiler rejects `--real` unless it is exactly one Xingular
+  run; this audit does not invoke `--real`.
+
+## Reproduction
+
+Build the CLI and create an isolated Python environment for the PTY screen parser:
+
+```sh
+npm run build
+python3 -m venv /tmp/harness-perf-venv
+/tmp/harness-perf-venv/bin/python -m pip install -r scripts/requirements-performance.txt
+```
+
+Main repeated comparison:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 5 --scenarios idle,stream,burst \
+  --rounds 2 --length 30 --interval 0.035 --width 160 --height 45 \
+  --warm-idle-seconds 2 --idle-seconds 2 --stream-seconds 4 \
+  --output /tmp/harness-perf-wide
+```
+
+History and compact-terminal sensitivity runs:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 3 --scenarios history \
+  --rounds 2 --length 30 --interval 0.035 --width 160 --height 45 \
+  --warm-idle-seconds 1 --idle-seconds 1 --stream-seconds 2 \
+  --output /tmp/harness-perf-history
+
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular,pi,opencode --repeats 1 --scenarios idle,stream,burst \
+  --rounds 2 --length 30 --interval 0.035 --width 80 --height 24 \
+  --warm-idle-seconds 2 --idle-seconds 1 --stream-seconds 4 \
+  --output /tmp/harness-perf-compact
+```
+
+Harness-only question latency and deterministic runtime overhead:
+
+```sh
+/tmp/harness-perf-venv/bin/python scripts/profile-terminal-latency.py \
+  --targets xingular --repeats 1 --scenarios question --rounds 2 --length 30 \
+  --width 160 --height 45 --warm-idle-seconds 1 --idle-seconds 1 \
+  --stream-seconds 3 --output /tmp/harness-perf-question
+
+npm run profile:session-runtime -- --iterations 5 --warmup 1 \
+  --output /tmp/harness-session-runtime.json
+```
+
+For terminal behavior verification, run `python scripts/verify-terminal.py` with the same Python
+environment. `npm run profile:terminal-input` measures the local draft-control socket separately;
+it is not a substitute for the PTY latency run.

package/docs/experiments/EXP-0003-performance-audit/results.md

@@ -0,0 +1,151 @@
+# EXP-0003 — Results
+
+- **Status:** audit completed; one terminal behavior verification check failed (details below).
+- **Run date:** 2026-10-25.
+- **Code:** base commit `6f72a07` with a dirty worktree (81 changed/untracked paths were present).
+  Product changes in that worktree predate this audit; this audit added benchmark tooling and report
+  artifacts only.
+- **Machine/runtime:** macOS 27.0, arm64, 8 logical CPUs; Node v26.8.2; Bun 1.4.2; Harness
+  1.1.1; Pi 1.2.0; OpenCode v2.1.4; Python 3.12.12; pyte 0.8.2.
+- **Credentials/network:** terminal comparisons used a loopback model in isolated temporary
+  profiles. The session-runtime benchmark used an injected deterministic session. No provider,
+  OAuth credential, or user profile was used; `--real` was not run.
+
+Raw terminal and runtime JSON is in [`data/`](data/): `terminal-wide.json`,
+`terminal-history.json`, `terminal-compact.json`, `terminal-question.json`,
+`session-runtime.json`, and `session-runtime-replication.json`. The OpenCode executable field is
+normalized to `opencode` to avoid publishing a machine-specific path; measurements are unchanged.
+
+## Terminal comparison
+
+Main repeated comparison: 160×45 PTY, five launches per target, 2 rounds of 30 characters at 35 ms
+per key, 2 s warm-idle and 2 s idle measurement. The table shows the median of per-launch values;
+latency is milliseconds p50/p95 and CPU is process-tree CPU during the typing window. Every target
+had zero missed keys.
+
+| Scenario | Target | p50 / p95 (ms) | CPU (%) |
+|---|---|---:|---:|
+| Idle typing | Xingular | 5.11 / 9.98 | 7.7 |
+|  | Pure Pi | 5.32 / 6.39 | 3.1 |
+|  | OpenCode | 7.17 / 10.41 | 26.5 |
+| After ~240 transcript messages | Xingular | 5.09 / 10.05 | 8.9 |
+|  | Pure Pi | 5.44 / 10.34 | 4.3 |
+|  | OpenCode | 9.47 / 12.70 | 32.6 |
+| Regular stream | Xingular | 9.13 / 19.91 | 14.2 |
+|  | Pure Pi | 3.18 / 22.26 | 10.5 |
+|  | OpenCode | 10.02 / 24.87 | 41.5 |
+| Burst stream | Xingular | 5.01 / 10.73 | 12.3 |
+|  | Pure Pi | 4.72 / 6.31 | 5.5 |
+|  | OpenCode | 10.42 / 21.85 | 33.2 |
+
+History setup took a median 7.5 s for Xingular, 6.5 s for Pi, and 9.8 s for OpenCode. Xingular's
+idle p95 was 9.98 ms before history and 10.05 ms after it, so this run found no meaningful
+history-related typing regression. The median streaming p95 was lower than both comparisons; burst
+p95 was below OpenCode but above Pi. Xingular idle p95 was roughly on par with OpenCode and 1.56×
+Pure Pi; burst p95 was 1.70× Pure Pi. Thus the prior EXP-0002 p95 criterion of “no worse than
+OpenCode” held for these four scenarios, while “within 1.5× Pi” did not hold for idle or burst.
+
+The five-run p95 ranges show why the medians should not be read as precise rankings: idle ranges
+were 9.64–10.19 ms (Xingular), 6.04–9.92 ms (Pi), and 9.58–11.08 ms (OpenCode); stream ranges
+were 18.32–20.25, 22.02–23.38, and 19.00–26.36 ms; burst ranges were 8.87–12.08, 5.81–33.23,
+and 12.86–26.00 ms respectively. Each run scores 44 idle keys and 22 stream/burst keys; p95 values
+are medians of per-run p95, not pooled per-key percentiles.
+
+### Fresh launch and memory
+
+`first visible` is the first nonblank PTY screen; `stable screen` is measured after 750 ms without
+output. Process-tree RSS is sampled at that initial stable screen.
+
+| Target | First visible (ms) | Stable screen (ms) | Process-tree RSS (MiB) |
+|---|---:|---:|---:|
+| Xingular | 2,814 | 3,768 | 392 |
+| Pure Pi | 261 | 1,035 | 134 |
+| OpenCode | 304 | 1,107 | 489 |
+
+On this machine, Xingular's end-to-end first-visible time was about 10.8× Pi and 9.3× OpenCode;
+its process-tree RSS was about 2.9× Pi and 0.8× OpenCode. This launch comparison includes the
+Harness CLI and its terminal child, while Pi and OpenCode have different process architectures. It
+measures the user-visible path, not the renderer alone. A separate 80×24 single-run sensitivity
+check showed idle p95 of 4.66/5.08/8.11 ms and stream p95 of 10.95/5.72/18.61 ms for
+Xingular/Pi/OpenCode respectively; it supports the same broad pattern but is not a repeated result.
+
+The Harness-only plan-question scenario passed after the profiler was changed to enter plan mode:
+44 keys, no misses, p50 5.03 ms, p95 9.53 ms (one run; not a cross-target comparison). The raw
+record is `data/terminal-question.json`.
+
+A separate 2 s post-warm-up idle-resource window in the wide run measured median process-tree CPU
+of 2.0% for Xingular, 0.5% for Pi, and 1.5% for OpenCode. These short windows are coarse and should
+not be treated as a stable ranking.
+
+## Harness runtime overhead
+
+Two invocations of the isolated runtime benchmark contributed ten measured samples per warm
+operation (five iterations and one warmup per invocation). It imports the built SDK and uses a fake
+session seam; these values exclude model/provider latency and real Pi startup.
+
+| Operation | Median | Sample range |
+|---|---:|---:|
+| Warm `terminal.prepare` | 9.65 ms | 7.69–11.78 ms |
+| `sessions.run` to first persisted delta | 25.65 ms | 21.78–29.44 ms |
+| `sessions.run` to completion | 33.86 ms | 27.96–39.06 ms |
+| Tool run to `tool.started` | 29.12 ms | 25.74–31.92 ms |
+| Tool run to `tool.completed` | 29.50 ms | 26.12–47.31 ms |
+| Tool run to completion | 38.96 ms | 37.07–58.24 ms |
+
+Across the two process starts, SDK import was 246–347 ms and Harness initialization was 27.8–28.5
+ms. Cold `terminal.prepare` varied substantially, from 261 to 1,158 ms; its description includes
+first socket-listener setup. Treat the warm path as the repeatable figure and cold preparation as a
+signal to instrument further, not as a stable estimate. Every run verified the persisted event
+sequence; the temporary state/data roots were removed.
+
+## CPU profile notes
+
+Profiles were captured separately from the comparison runs and are not included in their latency
+medians. A one-run Bun profile of Xingular during startup and streaming (16.19 s, 846 samples) had
+highest self-time in terminal output writing (`writeBuffered` 14.0%, Node `_write` 9.3%), key
+matching (`matchesKey` 5.6%), OpenTUI stdout draining (4.5%), and the terminal socket `send` (3.2%).
+This identifies output/key/event plumbing worth inspecting, but does not isolate one application
+function as the cause of input latency.
+
+A separate one-run Node profile of the Harness process (6.98 s, 5,576 samples) was 69% idle in the
+profiler, with `spawnSync` at 11.2% and `readdir` at 3.2%. This is consistent with a startup path
+that includes process and I/O waits rather than being dominated by one CPU-heavy JavaScript loop;
+it is not a phase-by-phase startup trace. Profiles are diagnostic single runs and profiling itself
+adds overhead.
+
+## Verification
+
+- `npm run typecheck` — passed.
+- `npm test` — passed: 150 test files, 1,140 tests passed, 3 skipped.
+- `npm run build` — passed.
+- `npm run prove` — passed all 15 standalone proof cases.
+- `npm run profile:terminal-input` — passed; 120 local draft-control socket requests, p50 0.022 ms,
+  p95 0.053 ms. This measures the socket path, not key-to-screen rendering.
+- `profile-terminal-latency.py --real --targets pi` — rejected before launch as intended; `--real`
+  is restricted to one Xingular run.
+- `python scripts/verify-terminal.py` — **failed** during `/settings` at a narrow terminal width.
+  The verifier expected `Esc close` on the last row; the observed footer was truncated to
+  `Enter change · type to search · Tab/`. This is a terminal behavior verification failure, not a
+  performance measurement. No product UI code was changed as part of this audit.
+
+## Conclusions and follow-up
+
+- **Steady typing:** competitive with OpenCode at 160×45, especially for streaming p95; history
+  does not increase Xingular's measured p95. Xingular still trails Pi on idle and burst p95, and
+  has higher CPU than Pi while typing/streaming.
+- **Fresh start:** the clearest gap. Xingular takes about 2.8 s to first visible output and uses
+  about 392 MiB at the initial screen. The runtime benchmark makes warm Harness preparation look
+  inexpensive, but cold preparation is variable. Break startup into Node CLI, Harness account and
+  context setup, terminal preparation, Bun launch, and first render before attributing or optimizing
+  the gap.
+- **Next measurements:** add phase markers for fresh startup and process-by-process RSS; repeat on a
+  slower machine; investigate burst input alongside `matchesKey`/output writes; and triage the
+  narrow `/settings` footer verification failure separately.
+
+## Limits
+
+One arm64 machine and a dirty worktree; no clean-commit A/B or slower-device run. The loopback stream
+is regular and excludes network/provider delay. PTY/pyte timing excludes physical terminal paint.
+The compact-screen and question results are single runs. CPU profiles are single instrumented runs.
+The runtime benchmark's session is injected and deterministic, so it measures Harness runtime and
+persistence costs, not real model inference or the complete Pi AgentSession startup path.

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.