@xingular/harness 1.0.0 → 1.2.0

package/docs/parity.md

@@ -0,0 +1,134 @@
+# 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 | — |
+| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; bounded plan/checklist context is restored after compaction | plan request, PlanCard; shared Harness checkpoint behavior | parity | — |
+| 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; 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 with scroll and copy | side-question dock through the shared service | parity | — |
+| Approvals and standing approvals | `sessions/approvals.ts` | `approvals.*` | decision dock, `/permissions` | approvals dock, settings | parity | — |
+| Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 80×24 source sketch viewport; connected structural projection with high-confidence boundary normalization (PROP-0026, PROP-0028) | plan-mode form accepts the same 80×24 ASCII source contract with literal preview and accessible overflow; no typography change required | parity; terminal projection verified in isolated fixtures | — |
+| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030), `subagents.*`; plan mode allows only named eligible read-only research profiles | `/subagents` page and live rows under the status line (mark, profile, parent-set title, `n of m tasks`); 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.*` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
+| Run checklist | `tools/checklist.ts` | `checklist_write`, `runs.checklist`; terminal `checklist` telemetry | registered in terminal sessions and their subagents; each write shows as a checklist block in the transcript; a subagent row shows its `n of m tasks` | not shown | terminal done; App planned | 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` | `checkpoint_write`, `workSlice`, `runs.continuation.checkpoint`, `checkpoint`/`heartbeat` events | guard on every terminal reply with the shared tool; 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` | `skill_load` | `$name`, `/skill:name`, browser Skills tab | Capability, composer | parity | — |
+| Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | resource browser | Capability | parity | — |
+| 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 | — |
+| Isolated browser | `browser/` | shared `browser_*` schemas | isolated world tools, headed on request, `/settings` Browser tab | native WebKit: navigate, tabs, visible-text read and page scroll without refs; unsupported operations refuse explicitly | partial; native backend gap | PAR-015 |
+| Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` pane (also `/annotate:annotate`), `/annotate:notes` saved list | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | parity in the working tree; 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` page; `/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/` | `harnesses.*`, `refine.*` | browser Variant tab (read-only), `xagent refine` | Harness screen | 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 |
+| Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` page (Limits tab) | 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_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
+| Shared files vault | — | `files_*` (host tools) | none | Files | host only | PAR-007 |
+
+## 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 |
+| `/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 | Stops the focused session's reply | 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 |
+| `/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` | Plugins page | Opens Capability plugins | Not certified per command |
+| `/hub` | Hub browser | Opens Capability 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 | 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-001 | Checklist absent from the App | The terminal registers the tool and renders a checklist block; the App renders it too. |
+| 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 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
+| 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 Harness owner | Decide each: computer control stays host-backed (terminal shows unavailable); 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. |
+| 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. |
+| 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-015 | Native WebKit browser-tool coverage | The shared browser schema is wider than the native backend. Native WebKit supports navigation, tabs, visible-text reads and scrolling without refs. Accessibility snapshots, snapshot-ref interactions (including click/type/select/ref-scroll), browser screenshots, 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

@@ -2,8 +2,8 @@
 
 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. This document describes the candidate until registry publication is
-verified.
+versions remain unchanged. The npm registry published 1.0.0 as the stable baseline; this file
+remains its release notes.
 
 ## Included
 

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

@@ -0,0 +1,47 @@
+# Xingular Harness 4.0.0
+
+This major release builds on the published 1.0.0 baseline. It extends Harness-owned terminal
+surfaces and adds generic worktree and page-annotation capabilities; it also changes the built-in
+terminal command namespace, documented below. Earlier published versions remain available.
+
+## Included
+
+- Managed Git worktrees for sessions and the terminal, with leases, guarded setup scripts, handoff,
+  pruning, restoration, and bounded snapshots that preserve uncommitted work.
+- Web annotations and queued comments, including capture, review, resolution, sharing, and delivery
+  through Harness methods and terminal `/annotate:` and `/annotate:notes` pages.
+- A unified terminal resource browser with persistent full-screen sections for browser tabs,
+  plugins, skills, connectors, variants, and other Harness resources.
+- A full-screen `/history:trajectory` Runs/Events browser with searchable event details, selected-event
+  JSON, and a responsive split-pane layout.
+- Additional terminal controls for browser settings, plugin settings, and subagent activity.
+- Fix Node 22 SQLite parameter binding in recall and run indexes, and guard worktree Git calls
+  against early child-process exits while writing input.
+- Updated architecture and parity documentation for Harness capabilities and their terminal and
+  host surfaces.
+
+## Installation and requirements
+
+Use `npm install --global @xingular/harness@4.0.0`, then `xagent`. Node 22.19 or later is required.
+The interactive terminal also 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.
+
+## Compatibility
+
+The new server methods are additive. The published executable is `xagent`, replacing the earlier
+`xharness` candidate command without a compatibility alias; scripts using that candidate name must
+be updated. All plugin-owned terminal commands use `/<owner-prefix>:<command>`: for example,
+`/subagents:subagents`, `/history:trajectory`, `/doctor:doctor`, `/worktrees:worktree`, and
+`/annotate:annotate`. The annotation prefix root `/annotate:` opens the default capture pane, and
+`/annotate:notes` opens saved annotations. Existing `/plugin:<command>` and former bare required-plugin
+forms remain hidden compatibility aliases for one release. Existing session, variant, account, plugin,
+and browser contracts remain in place. Install this exact version or use the `latest` tag; historical
+versions remain available.
+
+## Verification scope
+
+The Harness CI suite, standalone proof, App typecheck/tests/layer check/Rust tests, and App UI
+consistency check must pass for the reviewed release candidate. The release tag workflow separately
+builds and smoke-tests the exact tarball on its supported operating systems before publishing it
+with npm provenance.

package/docs/releases/README.md

@@ -1,36 +1,46 @@
 # Release procedure
 
-1. Review and commit completed Harness changes on release/1.0.0. Review App compatibility changes
-   separately. Preserve old tags and exclude outputs, external references and caches.
-2. Run npm run ci and the required App checks on unrestricted macOS/Linux runners. Install Bun
-   1.4.2 and use Node 22.19.0 for the release build. Do not waive failing checks.
-3. Run npm run release:pack. The unique output folder contains the candidate tarball, inventory,
-   SHA-256 checksum and npm integrity. Run npm run release:smoke -- <tarball> --terminal for a fresh
-   dependency installation and packaged SDK/server/terminal checks. --offline reuses the checkout's
-   installed dependency tree and is only a local smoke check, not fresh-install acceptance.
-4. Run npm run release:preflight. Verify npm scope ownership and trusted-publisher settings for
-   tanntnny/xingular-harness, workflow release.yml, direct publishing enabled. No login is started
-   automatically. Existing 1.0.0 or an unreachable registry blocks publication.
-5. Present the exact commit, candidate inventory/hash, notes and check results for approval. Pushing
-   v1.0.0 triggers publication; do not push the tag before this approval. Preserve historical tags.
-6. After approval, push the reviewed commits and tag. The workflow runs both OS checks, packages
-   and tests one candidate, then publishes that same tarball with OIDC provenance and --tag latest.
-   No local publishing token is needed. It verifies registry integrity/provenance and creates a
-   GitHub release. Inspect registry state before retrying any failed publication.
+1. Review and commit the completed Harness changes on the active release branch. Review App
+   compatibility changes separately. Preserve old tags and exclude outputs, external references,
+   and caches.
+2. Run `npm run ci` and the required App checks. Require green CI on Ubuntu and macOS; install Bun
+   1.4.2 and use Node 22.19.0. Do not waive failing checks.
+3. Run `npm run release:pack` and inspect the candidate inventory, SHA-256 and npm integrity. Run
+   `npm run release:smoke -- <tarball> --terminal` for a fresh-install SDK/server/terminal check;
+   `--offline` is only a local smoke check, not fresh-install acceptance.
+4. Run `npm run release:preflight`. Verify npm scope ownership and trusted-publisher settings for
+   `tanntnny/xingular-harness` and `release.yml`, with direct publishing enabled. Configure the
+   GitHub `npm-publish` environment with required reviewers. No login is started automatically; an
+   already-used version, unreachable registry, or missing publishing configuration blocks release.
+5. Candidate approval is a pre-tag gate. Present the exact clean commit, candidate inventory,
+   SHA-256, npm integrity, release notes and check results for approval. Do not create or push the
+   matching `v<version>` tag until the person explicitly approves that candidate.
+6. After candidate approval, push the reviewed commit and matching tag. The workflow reruns CI on
+   both OSes, builds one candidate, and smoke-tests that exact tarball on both OSes. Before approving
+   the protected `npm-publish` environment, compare the uploaded candidate's commit, SHA-256 and npm
+   integrity with the approved local candidate; stop if they differ. This environment approval is a
+   separate publication gate. The publish job publishes that same tarball with OIDC provenance and
+   `--tag latest`, then verifies registry integrity/provenance and creates a GitHub release. No local
+   publishing token is needed. Inspect registry state before retrying any failed publication.
 
 A published version cannot be replaced. Corrections require a later version. This package's
 intentional 1.0.0 reset does not rewrite historical decisions or claim an ordering above older
 2.x–5.x development versions. Publication status and local evidence belong in the candidate report.
 
-## Current preparation evidence
+## Historical 4.0.0 candidate evidence
 
-Local package inspection and the offline-dependency consumer smoke check pass. App compatibility
-checks pass (592 renderer tests, 40 sidecar tests, 240 Rust tests with one ignored, and type/layer/UI
-checks). A focused Harness run has 100 passing tests and the standalone proof passes. The full
-Harness run is blocked by sandbox IPC and native HEIC encoding restrictions. The public GitHub
-repository and absence of a remote v1.0.0 tag were verified through the connected GitHub service.
-The npm registry and trusted-publisher settings could not be verified from this environment.
+The following report records a prior candidate and registry snapshot; it is not evidence for the
+1.2.0 candidate or a description of the current release gates.
 
-The release branch must run unrestricted CI and a fresh-install smoke check before a release-tag
-approval is requested. Branch upload itself is a separate approval because it shares the source
-with GitHub and starts CI; it does not publish npm. No local test failure is waived by this note.
+At the time, local checks on that candidate source passed: Harness `npm run ci` (typecheck, 134 test
+files with 1,004 passing tests and 3 skipped, plus the standalone proof); App typecheck, `npm test`
+(566 renderer tests, 47 sidecar tests, and 7 dev-signing tests passed with 1 skipped), layer check,
+and Rust tests (168 passed, 1 ignored); and App UI consistency. The registry snapshot listed 1.0.0 as
+`latest` and 4.0.0 as unused. Its clean-tree preflight, exact-tarball packaging and fresh-install
+smoke test passed. The package-owner verification of npm trusted-publisher configuration for
+`tanntnny/xingular-harness` and `release.yml` was still required; `npm login` does not verify that
+setting. These results and registry values are historical.
+
+At that time, the workflow ran full CI and exact-tarball smoke on Ubuntu and macOS before publishing.
+The current workflow and approval gates are described above. No local test failure was waived by the
+historical report.

package/docs/study/00-index.md

@@ -11,10 +11,18 @@ written and the claim moves to checked behavior. Cite material as
 
 ## Focused notes
 
+- [Proactive autonomy and three feature directions](proactive-autonomy.md) — scheduled initiative,
+  a human-readable agenda, UI repair, cleanup and product experiments; fresh
+  [proactive-system evidence](autonomy-sources.md) and
+  [autonomous-engineering evidence](autonomous-engineering-sources.md). Research hypotheses,
+  not an accepted architecture change.
 - [`/btw` side-question comparison](btw-comparison.md) — this terminal, the App-owned
   side question, and checked-out external implementations.
 - [Harness feature-gap review](feature-gap-review.md) — task/goal management, long-running work,
   memory, execution isolation, verification, and observability gaps against the studied peers.
+- [Why a long run takes hours](STUDY-0003-long-horizon-runs.md) — measured diagnosis of two 70–97
+  minute replies (447 and 266 tool calls, 5 and 2 compactions, zero assistant text), what other
+  harnesses do about it, and the fixes proposed in [PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md).
 
 ## Sources
 

package/docs/study/STUDY-0003-long-horizon-runs.md

@@ -0,0 +1,210 @@
+---
+id: STUDY-0003
+title: Why a long run takes hours — measured diagnosis of two long sessions
+status: measured-diagnosis; fix proposed in PROP-0041
+created: 2026-10-26
+updated: 2026-10-26
+related:
+  - PROP-0033
+  - PROP-0041
+---
+
+# Why a long run takes hours
+
+**Answer.** Neither session was looping on a single action — both kept changing files and running checks. But both ran as **one unbroken reply**: 448 and 274 tool calls, 5 and 2 context compactions, and a single assistant message at the very end, or none at all. The 75-minute session produced one final report and said **"release is still blocked"**. The other was **still running at 114 minutes when measured, with 448 tool calls and not one word to the person**. 41 of those minutes were three Playwright runs, 25 of them on two timeouts, and 55 minutes were 307 model requests averaging 10.7 s each over a ~140k-token context.
+
+The loop is in the **shape of the reply**, not in the goal. The fix is not a better prompt; it is a bounded reply, a durable checkpoint, and a loop guard. [PROP-0041](../architecture/proposals/PROP-0041-bounded-work-slices.md)
+proposes them.
+
+## What was measured
+
+Both sessions are ordinary records under the dev data root
+(`~/.xingular-harness-dev/data/runs/<id>/`), read together with their native Pi session. Nothing was
+re-run; every number below comes from `events.jsonl`, `run.json` and the native `*.jsonl`.
+
+| | A — "Finish App Harness parity integration" | B — "Complete secure Harness release candidate" |
+|---|---|---|
+| Run | `64cdd5f0` | `2d62eaec` |
+| User text that started it | "continue where you left of" | "continue where left of" |
+| Started / last event | 17:50:43Z / 19:44:57Z at the cut, still active | 18:27:46Z / 19:42:40Z |
+| Wall clock | **114.3 min at the cut, still running** | **74.9 min** |
+| How it ended | no end: the same reply was still going | one final report, `completed` |
+| Recorded state afterwards | `running` | `completed` |
+| Model requests | 307 | 197 |
+| Model time | 3299 s (55.0 min), mean 10.7 s, p90 20.0 s | 2924 s (48.7 min), mean 14.8 s, p90 30.4 s |
+| Tool calls | 448 | 274 |
+| Tool time | 3491 s (58.2 min), 51 % of the run | ~1420 s (23.7 min), 32 % |
+| Reads | 163 over 96 paths (`host.rs` 11×) | 101 over 56 paths (`verify-terminal.py` 6×) |
+| Edits | 61 over 35 files (`app.test.ts` 10×) | 78 over 30 files (`07-tools-and-gate.md` 9×) |
+| Identical repeated calls | 42 instances, 20 signatures | 10 instances, 5 signatures |
+| Billed tokens | 18.85 M input + 25.01 M cache read | 16.70 M input + 12.94 M cache read |
+| Output tokens | 221 k, of which 175 k reasoning (79 %) | 205 k, of which 173 k reasoning (84 %) |
+| Cost recorded by the harness | $2.23 | $1.66 |
+| Compactions inside the run | **5**, at 255 852–269 591 tokens | **2** (7 across the 5-hour thread) |
+| Cold re-sends (no cache read, >20 k input) | 9 requests, 1.58 M uncached tokens | 9 requests, 1.51 M uncached tokens |
+| Assistant text inside the run | **0 characters** | **0 characters until 74.9 min**, then one 2 028-character report |
+| Approvals | 49, all remembered, 0.0 s wait | 2, both remembered |
+
+Run A was still producing events while this was written (314 model requests at 19:48Z); every number
+for it is frozen at 19:44:57Z, 114.3 minutes in. Run B had already settled.
+
+### Where run A's 114 minutes went
+
+| Bucket | Time | Share |
+|---|---|---|
+| Model requests (307) | 55.0 min | 48 % |
+| Bash (129 calls) | 57.6 min | 50 % |
+| — three Playwright runs: 600 s timeout, 900 s timeout, 986 s success | 41.4 min | 36 % |
+| Reads, edits, searches, subagent waits | ~0.5 min | 1 % |
+| Unaccounted idle | ~1.2 min | 1 % |
+
+The harness was busy for 98.5 % of the wall clock. Nothing was hung; the reply was simply too long,
+and every step paid full-context latency. The same browser suite ran three times because it timed out
+twice without narrowing itself, and each retry cost the full command budget.
+
+That 986-second command is also why a heartbeat matters: from request 306 at 19:27:56 to request 307
+at 19:44:29 there is **no event for 16.6 minutes**. A busy run and a wedged one look identical on the
+record.
+
+### Was it progressing?
+
+Yes, measurably:
+
+- 57 `file.changed` events in A at a steady rate (13, 6, 9, 6, 4, 9, 10 per ten minutes), longest gap
+  between changes 23.6 min; 74 in B, longest gap 17.5 min.
+- 57 successful test/typecheck commands in A; 28 of 129 Bash calls failed and were retried.
+- The checklist moved (B: 3 of 7 items completed across 9 checklist writes, and items were added as
+  gaps were found).
+- B's last message is a real report: what changed, which checks passed (1 255 Harness tests, 586 App
+  tests, 185 Rust tests), and what remains blocked. That is genuine incremental work with an honest
+  ending — after 75 minutes and 274 tool calls.
+
+But the same data shows the waste:
+
+- 42 calls in A were byte-identical repeats of an earlier call; 20 distinct signatures were repeated.
+- `host.rs` was read 11 times; `07-tools-and-gate.md` was edited 9 times as the checklist reworded
+  what "done" meant.
+- Run B read its own trajectory 63 times and searched it 8 times — recovering, inside the run, state
+  that earlier compactions had dropped.
+- Neither session produced a commit. The worktree is still dirty: B's own report counts 119 tracked
+  changes and 267 untracked files, which failed release preflight's clean-tree check. So "continue
+  where you left off" had no unambiguous answer — the work is real, but it is not a deliverable.
+- A's checklist was rewritten 7 times (B's 9) and its items were reworded each time
+  ("Complete Harness launch…" → "Complete App commands…" → "Complete App shared-profile…" →
+  "Close profile-root migration…" → "Finish App shared-profile…"). That is scope drift, not a
+  maintained plan.
+
+So: **incremental work, at roughly half efficiency, with no visible progress and no way to stop
+cleanly.** A person watching saw tool rows for 75–114 minutes, then either a single report or nothing
+at all.
+
+## The mechanisms that are missing
+
+Measured against the code (all verified in this tree):
+
+| Mechanism | State in this tree | Consequence |
+|---|---|---|
+| Reply budget | Only the opt-in `budget-guard` plugin (`src/plugins/firstParty.ts:31,105-140`), **off by default** and a blunt stop: it refuses tools and terminates the reply with no checkpoint | One reply ran 114 min and 448 calls |
+| Checkpoint | PROP-0033's checkpoint exists (`src/sessions/compactionCheckpoint.ts`), but it restores only *goal + checklist + plan*, and `renderCompactionCheckpoint` returns `null` when there is no checklist (`src/prompt/compile.ts:196`) | No files, no failing commands, no decisions; A wrote no assistant text at all |
+| Compaction discipline | Pi compacts at ~94 % of the window; the harness only observes it (`src/sessions/runner.ts:470-478`) | 5 compactions in one reply, each a cold re-send; state rebuilt by re-reading files |
+| Command ceiling | Bash `timeout` is optional, "no default timeout" (`src/core/workspaceBashTool.ts:23`) | 41 minutes in three Playwright runs; 36 % of run A |
+| Loop / stall detection | None (`rg loop|stuck|repeat` finds nothing in `src/sessions`) | 42 duplicate calls; 9 edits to one document |
+| Liveness | Reconciliation runs only at startup and is keyed on the owner pid (`src/sessions/runStore.ts:228`); `owner.json` holds a bare pid | A run that stops producing events while its process lives is never settled, and a recycled pid can make a dead owner look alive. A long command already writes nothing for 16.6 minutes |
+| Progress visibility | No mid-reply text requirement; `REPORTING_GUIDANCE` shapes only the final reply | 0 characters in 114 minutes and counting for A; one message at 74.9 minutes for B |
+
+The layer boundary matters for the fix: task and goal lifecycle belong to the application
+(`docs/study/feature-gap-review.md:7,35`). Everything above is **run execution**, which the harness
+owns. PROP-0041 keeps it there.
+
+## What other harnesses do about this
+
+Fetched 2026-10-26; URLs are the primary sources.
+
+| Mechanism | Who | Trigger | What it prevents |
+|---|---|---|---|
+| Stop hook that blocks the turn from ending until a check passes, with a cap on consecutive blocks | [Claude Code](https://code.claude.com/docs/en/best-practices) | Turn end | "Looks done" endings and endless turns |
+| Auto-compaction thrash guard: after a few refills, stop compacting and report the offending oversized result | [Claude Code troubleshooting](https://code.claude.com/docs/en/troubleshooting) | Repeated compaction in one turn | Summarise–refill loops |
+| Post-compaction re-injection of the plan file and up to five recently touched files (path only above 5k tokens) | [Claude Code context window](https://code.claude.com/docs/en/context-window) | Compaction | State lost to the summarizer |
+| Tool-result clearing before summarisation | [Anthropic context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) | Context pressure | Unbounded context growth |
+| Subagents with a 1–2k-token return contract | [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents) | Model decision | Exploration flooding the main context |
+| `todo.md` recitation at the end of context; restorable compression (drop content, keep URL/path); keep failed actions | [Manus](https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) | Every step / compression | Goal drift, repeated mistakes |
+| Loop detection by hashing `toolName + args`, cycle length 1–5 repeated 5×, plus an LLM judge after 30 turns | [Gemini CLI loopDetectionService.ts](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/services/loopDetectionService.ts) | Every streamed tool call | Oscillation and repeated failing commands |
+| Stop hook with `loop_count` and `MAX_ITERATIONS = 5` | [Cursor](https://cursor.com/blog/agent-best-practices) | Turn end | Unbounded single turn |
+| `max_requeries = 3` on malformed or blocked actions | [SWE-agent config](https://swe-agent.com/latest/reference/agent_config/) | Action error | Infinite retry |
+| Repo map under a 1k-token budget (PageRank over the dependency graph) | [Aider repomap](https://aider.chat/docs/repomap.html) | Every request | Re-reading files to re-orient |
+| Auto-commit, lint and test after each edit | [Aider git](https://aider.chat/docs/git.html) | Each edit | Long stretches with no checkpoint |
+| Event-count condenser that keeps the first events | [OpenHands context condenser](https://docs.openhands.dev/sdk/guides/context-condenser) | History size | Cost and latency growth |
+| Pre/post-turn compaction phases and pre/post-compact hooks | [Codex compact.rs](https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/compact.rs) | Turn boundaries | Unpredictable compaction |
+| Truncate-then-summarise plan saved to memory because the window will truncate | [Anthropic multi-agent research](https://www.anthropic.com/engineering/multi-agent-research-system) | Context limit | Losing the plan |
+
+Two reference scales are worth stating plainly: Manus reports **~50 tool calls per task**, and
+Claude Code's published loop cap is **5 iterations**. Both runs here exceeded those by 5–9× inside a
+single reply that addressed the person once, at the end, or not at all.
+
+Context rot compounds it: performance degrades as input grows and is worst for content in the middle
+of a long context ([Chroma](https://www.trychroma.com/research/context-rot),
+[Lost in the middle](https://arxiv.org/abs/2307.03172)). A 250k-token context is therefore both slow
+and less reliable — the re-reads and reworded checklists are what that looks like.
+
+## What to adopt, in order
+
+1. **P0, configuration only, today.** Switch on `output-trim` (20 000 chars) and `budget-guard`
+   (120 requests) in the plugin attachments of the affected account/project. That alone caps the
+   reply and shrinks tool results. No architecture change, reversible per account and per project.
+2. **P0b, small foundation fixes.** A default Bash timeout that returns partial output, and a stall
+   watchdog keyed on heartbeat age rather than only the owner pid. Both are narrow and independent of
+   the slice design below.
+3. **P1, bounded work slices (PROP-0041).** A reply budget of 160 tool calls / 40 min / 320k new
+   tokens, a validated checkpoint at the boundary, and a continuation that starts from that
+   checkpoint. This is the structural fix.
+4. **P2, the checkpoint as state, not prose.** Bounded, evidence-linked (files, failing checks,
+   decisions, next step) and injected at every slice start and after compaction, so the model never
+   re-derives state by archaeology.
+5. **P3, deterministic loop guard.** Identical `tool + args` three times, the same command failing
+   twice, or 25 steps with no file change and no passing check: nudge once with the evidence, then
+   end the slice as `blocked`.
+6. **P4, command budget.** Hard ceiling, and long suites (Playwright, full CI) as background work
+   rather than 16 blocking minutes.
+7. **P5, compaction pipeline.** Clear old tool results first; summarise with restorable references
+   (path + line range); stop after three compactions in one reply and hand off instead.
+8. **P6, visible progress.** Record narration as `progress` events and a heartbeat with steps,
+   elapsed time, slice and compactions; show "next checkpoint in N steps" in both surfaces.
+
+## How to judge whether it worked
+
+Baseline from these two runs, to compare after PROP-0041:
+
+| Metric | Baseline |
+|---|---|
+| Time to first user-visible text | never (A) / 74.9 min (B) |
+| Tool calls per user-visible text | ∞ (A) / 274 (B) |
+| Longest reply | 114 min and counting / 448 calls |
+| Compactions per reply | 2–5 |
+| Repeated identical calls | 42 per 448 (9 %) |
+| Reads per distinct file | 1.7 (163/96), worst 11 |
+| Time in three Playwright runs | 36 % of run A |
+| Runs left `running` after owner death | 1 of 2 |
+
+A working slice policy should keep the longest reply under ~45 minutes, put text in front of the
+person at every boundary, hold compactions to at most one per slice, and never leave a run
+`running` after its owner is gone.
+
+## What this does not fix
+
+Model latency per token, the correctness of the work itself, or a task whose acceptance criteria
+were never written down. A slice boundary cannot invent a definition of done; it can only make the
+absence of one visible early.
+
+## Appendix: how to reproduce
+
+Read-only, from the dev data root:
+
+```sh
+R=~/.xingular-harness-dev/data/runs/64cdd5f0-da45-43a1-9130-89c54f298f21
+jq -r 'select(.type=="usage.updated") | .payload.request.durationMs' "$R/events.jsonl" | awk '{s+=$1/1000; n++} END {print n" requests, "s" s"}'
+jq -r 'select(.type=="tool.completed") | .payload.name' "$R/events.jsonl" | sort | uniq -c | sort -rn
+jq -r 'select(.type=="message.completed") | .payload.role' "$R/events.jsonl"
+```
+
+The assistant's own text lives in the native session named by `run.json`
+(`nativeSessionId`), as `message` entries whose `content` blocks have `type: "text"`.