@xingular/harness 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,8 +1,49 @@
 # Changelog
 
-## 1.0.0 — release candidate
+## 1.2.0 — workspace safety and terminal capabilities
 
-- Establish the public stable baseline under Apache-2.0, with compiled ESM SDK modules and declarations. Preserve historical version tags; explicitly assign npm latest only after approval and successful validation.
+- Scope model-controlled file writes and Bash to the active project workspace by default; reject the filesystem root as a workspace. Native writes use revalidated atomic replacement; Bash fails closed on incomplete hard-link scans or unavailable sandboxing (macOS also blocks workspace-local hard links). Explicit outside-scope Bash requires approval before one execution, showing the complete escaped command; output never triggers approval or retry.
+- Let plan mode run Bash in a read-only OS sandbox (no writes except a discarded temp folder, no network, nothing that widens it), so plans can check claims with commands such as `git log` (PROP-0043).
+- Make plan mode evidence-grounded and allow bounded read-only research delegation. Rehydrate the active checklist and plan instructions after compaction, and retain the latest subagent status until the next run.
+- Give plugin-owned terminal commands stable owner namespaces and make Harness-owned routes first-class core commands. Prior command forms remain hidden compatibility aliases for one release; update scripts and keybindings to canonical routes.
+- Extend page annotations into open shadow roots while preserving existing document-only annotation targets. Closed shadow roots and frames remain unsupported.
+- Record each run's resolved workspace root as an additive run-record field; older records remain readable.
+- Add a searchable saved-session picker and composer history for user prompts, Bash commands and executed slash commands, restoring the draft, cursor, mode and attachments while browsing. Fix compact question-dock sizing/scrolling and narrow-page footer rendering.
+- Add reproducible PTY and session-runtime profiling plus [EXP-0003's baseline report](docs/experiments/EXP-0003-performance-audit/results.md); it measures 1.1.1 on a dirty worktree, not 1.2.0.
+- Update the pinned Pi runtime to 1.4.0, with the terminal adapter's private hooks and HTTP dispatcher chunk rechecked against it.
+- Fix the work-slice stall guard reporting a reply's own checklist updates as repeated work. A call's identity is its name and every argument, hashed, instead of six fixed field names that made every `checklist_write` look alike; the counts and the nudge start fresh in each reply, so a terminal session no longer carries a repeat from one reply into the next. Three identical calls are still named once, and a repeat after that still ends the slice.
+
+## 1.1.1 — agent profiles and named subagents
+
+The first published release of the 1.1 line, and npm `latest`. It follows the 1.0.0 baseline; earlier 2.x–4.x numbers keep their existing meaning and are not reused. The 1.1.0 tag was pushed, but its release run stopped before publishing, so nothing was published under 1.1.0. This release carries the same changes, plus the release-pipeline fixes below.
+
+- 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`.
+
+### Changes in 1.1.0
+
+
+- Add agent profiles (PROP-0029, ADR-0030). 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. New `agents.list|get|create|remove` methods, `RunRecord.profile`, and `agent`/`unavailableTools` on the spawn result. The prompt's `subagents` section lists every profile. The terminal's `/agents` page browses, creates, edits (in `$EDITOR`), copies and deletes them, and the terminal now passes its variant to subagents, so c5 names work there.
+- The terminal registers `checklist_write` (closing the terminal half of PAR-001), shows each write as a checklist block, and terminal subagents inherit it. The tool description and a new Progress paragraph in the prompt ask the model to keep a checklist for multi-step work, because the person follows progress from it. Each agent keeps its own checklist; there is no shared task pool.
+- The subagent rows move under the status line, after one blank row, and lose their heading. Each row shows the status mark, the profile name in its colour, the title the parent gave the child and `n of m tasks` from its checklist. `/subagents` shows the same fields.
+- Fix the transcript summary of `spawn_subagent`, which read the wrong argument names.
+- Subagents take a title the parent sets (PROP-0030). `spawn_subagent` requires `title`, at most six words; `subagents.spawn` takes an optional one, which defaults to the first line of the brief. The live rows, `/subagents` and the transcript's spawn row show the title instead of the child's session name or brief. `RunRecord.title` stores it.
+- A running subagent's row shows the working spinner in its profile's colour, and an in-progress checklist item shows a yellow dot.
+
+## 4.0.0 — breaking terminal command namespace, managed worktrees, and annotations
+
+- **Breaking terminal commands:** built-in plugin commands now use the `/plugin:` namespace. Existing `/doctor` and `/trajectory` commands become `/plugin:doctor` and `/plugin:trajectory`; update scripts and keybindings that invoke the old names. New feature commands are namespaced from their introduction.
+- Add Harness-managed Git worktrees for sessions and the terminal, including isolated creation, leases, safe setup scripts, handoff, pruning, and bounded snapshots of work before removal.
+- Add page annotations and queued page notes, with capture, review, resolution, sharing, and delivery through Harness methods and terminal `/plugin:annotate` and `/plugin:notes` surfaces.
+- Add a unified terminal resource browser with persistent full-screen sections for browser tabs, plugins, skills, connectors, variants, and other Harness resources.
+- Upgrade `/plugin:trajectory` to a full-screen Runs/Events browser with searchable event details, selected-event JSON, and responsive split-pane layout.
+- Expand terminal controls for browsing subagent activity and managing browser and plugin settings; document the terminal/host parity boundary.
+- Fix SQLite parameter binding for the supported Node 22 runtime and prevent early-exiting Git commands from raising an unhandled broken-pipe error.
+- Generalize release packaging, smoke checks, registry verification, and CI workflows to use the package version, and require a clean committed tree for release candidates.
+
+## 1.0.0 — stable baseline
+
+- Established the public stable baseline under Apache-2.0, with compiled ESM SDK modules and declarations. Preserved historical version tags and assigned npm latest after release validation.
 - Add /doctor with passive readiness inspection, selected live probes, cancellable reports and Node/RPC APIs.
 - Include the generic isolated browser backend and document its boundary with App browser UI and native computer control.
 - Add exact-tarball installation/consumer checks and a Bun-aware, two-OS release pipeline.
@@ -23,9 +64,9 @@
 
 ## 4.0.0 - 2026-10-22
 
-- Rename the published CLI executable to `xharness`; invoking it without a subcommand opens the OpenTUI terminal. The previous `xingular-harness` executable is removed, so scripts and shell aliases must be updated.
-- Name how refinement's executions run. `refine.start` (and `harness.refine.start`) accepts `executor: { model?, effort?, accountId?, poolId? }`, and `xharness refine run` accepts `--executor-model <id>` (`--model` still sets the improver). A host's own session settings win, then `executor`, then the account default, so a server client can pin the executor model without supplying a host. `summary.json` records `settings: { executor, improver }`. See PROP-0003.
-- Keep refinement workspaces on request. `refine.start` (and `harness.refine.start`) accepts `retainWorkspaces: true`, and `xharness refine run` accepts `--retain-workspaces`: each base, candidate and final execution's workspace is copied whole — binary files included — to `<data>/refine/<id>/rollouts/<label>/workspace/` before the host cleans it up. `refine.candidates` reports each execution's `workspace` path or `null`. Evidence, selection, reflection and the library never read these folders, so refinement stays answer-free; they exist so an outside measurement can grade what an execution produced. Off by default. See PROP-0002.
+- Publish the CLI executable as `xagent`; invoking it without a subcommand opens the OpenTUI terminal. The previous `xingular-harness` executable and interim `xharness` command are removed, so scripts and shell aliases must be updated.
+- Name how refinement's executions run. `refine.start` (and `harness.refine.start`) accepts `executor: { model?, effort?, accountId?, poolId? }`, and `xagent refine run` accepts `--executor-model <id>` (`--model` still sets the improver). A host's own session settings win, then `executor`, then the account default, so a server client can pin the executor model without supplying a host. `summary.json` records `settings: { executor, improver }`. See PROP-0003.
+- Keep refinement workspaces on request. `refine.start` (and `harness.refine.start`) accepts `retainWorkspaces: true`, and `xagent refine run` accepts `--retain-workspaces`: each base, candidate and final execution's workspace is copied whole — binary files included — to `<data>/refine/<id>/rollouts/<label>/workspace/` before the host cleans it up. `refine.candidates` reports each execution's `workspace` path or `null`. Evidence, selection, reflection and the library never read these folders, so refinement stays answer-free; they exist so an outside measurement can grade what an execution produced. Off by default. See PROP-0002.
 - Shape every final reply. The compiler adds a fixed `reporting` section ("Reporting your work", `REPORTING_GUIDANCE`, `SECTION_ORDER.reporting = 95`) to every pack, after the tools: answer or outcome first, then only the parts with content — Files (a table when three or more), Blocked, Worth a look, Check by hand, Next steps — and Markdown tables where several items share fields. A format the person, the application or the current mode asks for wins. The stable prefix changes once, so existing sessions miss the provider cache once. See PROP-0001 and ADR-0007.
 - Make typing in the OpenTUI terminal fast while idle and while a reply streams. Keys render on demand instead of on a fixed 60 Hz tick (idle p50 13.1 → 5.1 ms); the view is a reconciled Solid store, so a streamed delta updates its markdown block in place instead of rebuilding it; background updates are coalesced to one per frame (30 Hz during a run) while input publishes at once; finished messages and session statistics are cached. Streaming CPU fell from 73% to about 15% in the profile. See `docs/experiments/EXP-0002-opentui-typing-latency/`.
 - Never swallow keys typed while a question waits: a character the question dock does not use moves focus to the composer and is typed there. Previously such keys were dropped until the dock collapsed.

package/README.md

@@ -38,7 +38,8 @@ index](docs/README.md) links the architecture and other project records.
 ### Session options for applications
 
 - Interactive sessions offer `spawn_subagent` and `wait_subagents` by default. `subagents: null` disables them; `{ maxDepth }` configures native nesting (default one, maximum three), independently of the host caller depth. Unattended sessions remain disabled unless the host explicitly supplies subagent options. A frozen capability set can narrow these tools further.
-- `harness.subagents.spawn({ parentRunId, brief, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. It returns `{ runId, nativeSessionId }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
+- `harness.subagents.spawn({ parentRunId, brief, agent?, tools?, wait? })` opens a fresh child of the same caller with no wider capabilities. `agent` names an agent profile (below). It returns `{ runId, nativeSessionId, agent?, unavailableTools? }` once open; `wait: true` also waits for settlement. `harness.subagents.wait({ parentRunId, runIds? })` joins selected direct children, or the current children when omitted, and returns their outcomes. `results` reads the same bounded outcome records without waiting. RPC exposes `subagents.spawn`, `subagents.wait`, and `subagents.results`; `sessions.spawnSubagent` remains a compatibility alias.
+- **Agent profiles** (PROP-0029) are what a subagent starts from: the built-in `worker` (reads, edits, writes, runs commands) and `explorer` (reads only), a person's own `<data root>/agents/<name>.md`, a repository's `<project>/.xingular/agents/<name>.md`, and the variant's c5 subagents, later ones winning. A profile is Markdown with frontmatter (`description`, `color`, `tools`, `plugins`, `variant`, `model`, `effort`) and its body is the role. It only narrows the parent's tools and plugins. `listProfiles`, `resolveProfile`, `createProfile` and `removeProfile` (RPC `agents.list|get|create|remove`) read and write them, and the child's `RunRecord.profile` names the one it used.
 - The model's `spawn_subagent` returns immediately by default; `wait: true` returns an inline result. `wait_subagents` joins selected children. The SDK and standalone terminal share this execution service. Terminal calls use its private control channel, including when connected apps are disabled.
 - Parents receive results at native turn boundaries and join outstanding children before completing. Typed native-history receipts prevent duplicate automatic delivery; explicit waits can reread results. Ownership is recorded before startup so an explicit resume can recover even a lost spawn return. Startup reservations without a run become interrupted outcomes. A restarted Harness never restarts model work automatically. Recovery requires the same recorded account, caller, working folder, and selected history branch. Session IDs are opaque; consumers follow `parentRunId` and `relation`.
 - `providers: false` runs a session with the harness's own tools only.
@@ -66,7 +67,7 @@ import { createHarness } from '@xingular/harness'
 const harness = createHarness({
   dataRoot: '/path/to/data',        // variants/, library/, refine/, wiki/, registry/, runs/, index.sqlite
   stateDir: '/path/to/state',       // device-local: accounts, approvals, connections, sockets
-  productName: 'My App',            // how the harness names itself to a model (default 'Xingular Harness')
+  productName: 'My App',            // how the harness names itself to a model (default 'Xingular Agent')
   secrets,                          // SecretStore; defaults to an owner-only file in stateDir
   policy,                           // ToolPolicy: what a run may do, and what needs a person
   directory,                        // names for the ids the application uses
@@ -160,7 +161,8 @@ working folder brings.
   and `editor` become the run's question events; `notify`, `setStatus` and `setWidget` become
   `extension.notice` run events. What needs a terminal (custom components, key handlers, themes)
   does nothing. A tool an extension registered is offered to the model and asks before every
-  call. A command it registered runs when a message starts with it.
+  call. A terminal command runs as `/<owner-prefix>:<command>`; package extensions use their
+  normalized package name, or an optional `harness.commandPrefix` from `package.json`.
 - **The gate runs last.** In an SDK session it is an inline extension, loaded after those on
   disk. A terminal retains its final prepared `--extension` bridge argument; the owned frontend
   loads that bridge as the final trusted inline factory. A plugin that changes a tool call's
@@ -194,7 +196,7 @@ working folder brings.
   terminal process claims once (`control.claim`) and shares with its bridge in memory; the socket's
   `plugins.list` is open to the session, and `plugins.attach`, `plugins.detach`, `plugins.trust`
   and `plugins.untrust` refuse without that key. A change applies when the session restarts.
-  Outside a session, `xharness plugins list | show | install | remove | update | attach |
+  Outside a session, `xagent plugins list | show | install | remove | update | attach |
   detach | trust | untrust` acts directly, as the person who typed it; `trust` shows the files
   and wants a typed yes or `--yes`. It does not open the data root, so it settles no run.
 - **Unattended runs load no extension found on disk.** A variant's own trusted plugins still
@@ -263,7 +265,7 @@ After the CLI package is published to npm or your company's npm registry, instal
 
 ```sh
 npm install --global @xingular/harness
-xharness
+xagent
 ```
 
 The machine needs Node 22.19 or newer and Bun 1.3.14 or newer. Harness runs its own OpenTUI
@@ -296,7 +298,41 @@ terminal that cannot start. The harness runs `dist/terminal-opentui.js`, which u
 session runtime, accounts, command pages, approvals, questions, plugins and run records as the
 embedded SDK. See [the terminal guide](docs/terminal-tui.md).
 
-Building a checkout does not update an existing global `xharness` installation.
+### Worktrees
+
+Run `xagent --worktree` (or `-w [name]`) inside a git repository to start in a fresh managed
+worktree: a detached checkout under `<state dir>/worktrees/` that carries your uncommitted
+changes, copies ignored files named in `.worktreeinclude`, and runs the repository's
+`.xharness/worktree-setup` once you trust it (`xagent worktree trust-setup`). The 15 most recent
+managed worktrees per repository are kept; older ones are pruned, and unsaved work is kept as a
+snapshot you can restore. `/worktree` in a session, `xagent worktree <command>` in a shell, and
+the `worktrees.*` server methods offer the same actions: new, switch, create branch, hand off to
+or from the main checkout, remove, restore, prune and adopt. An application passes a worktree's id
+as `run.worktreeId` and the session works in it. See
+[PROP-0016](docs/architecture/proposals/PROP-0016-managed-worktrees.md).
+
+### Web annotations
+
+`/annotate:` (or `/annotate:annotate [url]`) opens a visible capture browser (its own window and profile, separate from the
+agent's browser). Annotate the whole page, select a passage, or click an element there, then write a
+comment in the terminal. `/annotate:notes` lists, edits, resolves, reveals and deletes annotations. An annotation is private
+until you share it with the session; its agent then reads it with `page_notes_list` and
+`page_notes_read`, with quoted page text marked untrusted. Annotations live in `<data root>/annotations/`
+and the `annotations.*` server methods give a host the same store. A host with its own web view
+runs the same page helper (`annotations.pageScript`). See
+[PROP-0017](docs/architecture/proposals/PROP-0017-page-annotations.md).
+
+`/annotate:` opens the inspector:
+- Hover a component in the browser or an app window, click it, and write a comment in the popover.
+- Then keep it as a note, add it to the agent's queue, or send it now. The agent reports back with `page_notes_mark_fixed`.
+- App windows work two ways:
+  - **DevTools port:** start an Electron app with `--remote-debugging-port=9229` and run `/annotate:annotate --app 9229`.
+  - **Page bridge:** for a macOS web view such as Tauri, run `/annotate:annotate --bridge` and load the script tag it shows while developing the app. Allow `http://127.0.0.1:<port>` in the app's `script-src` and `connect-src`.
+- A host drives the same flow with `annotations.capture.*`, and sends to its own sessions with `annotations.compose` and `annotations.delivered`.
+
+See [PROP-0018](docs/architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md).
+
+Building a checkout does not update an existing global `xagent` installation.
 To replace that command with this checkout, run `npm pack`, then install the exact tarball
 filename it prints with `npm install --global ./<tarball-filename>`. This is a local install;
 it does not publish a release. Close an already-running terminal session and launch the command
@@ -311,14 +347,31 @@ Pi supplies the persistent execution runtime, native history and rich content co
 existing isolated account, compiled context, approval gate, telemetry and Wiki/socket commands
 remain behind the terminal. No Pi `InteractiveMode` is constructed.
 
+Harness terminal commands stay unprefixed: `/doctor`, `/worktree`, `/trajectory`, `/subagents`,
+`/agents`, and `/mcp`. `/history` continues to navigate session branches. These commands are
+registered independently of feature-plugin command metadata. Other plugin-owned commands use
+`/<owner-prefix>:<command>`; for example, annotate a page with `/annotate:annotate
+https://example.com`, or open the default annotation pane with `/annotate:`. Former owner-qualified
+and `/plugin:<command>` routes for promoted Harness commands remain hidden compatibility aliases for
+one release; help and completion show only canonical forms.
+
 `/resume` stays inside the prepared account history and working folder. Cancel an active response
 before changing or reloading a session. Full OMP visual parity is not established by the current
-verification. `/accounts`, `/permissions`, `/plugins`, `/hub`, `/components`, `/settings`, `/trajectory`
-and `/log` each open their own centered page dialog with local tabs. `/permissions` reviews device-local Pi
-terminal grants and the Full Permission switch; tool grants apply across terminal sessions sharing this
-Harness state, and Full Permission requires confirmation. `/components` browses reusable skills,
-prompts and rules; a confirmed skill or rule addition creates a variant version for future sessions while
-the current terminal stays pinned. `/trajectory` opens recorded runs for the current native conversation,
+verification. `/harness` opens one browser for Foundation, Variant, Skills, Plugins,
+Connections (MCP), Tools and Library. `/skills`, `/plugins`, `/connections` (`/mcp`) and `/tools`
+open its sections directly; `/hub` opens Discover and `/components` opens Library. Resource
+sections share Installed / Discover, source filters, search and a detail inspector. Tab focuses
+controls, arrows change the focused choice, Ctrl+F returns to search and Escape goes back.
+Skills show actual session availability even with invocation shortcuts off. With shortcuts on,
+Use inserts `$name` into the draft without sending it; typing `$` also completes loaded skills.
+To keep an existing message and attachments, open Ctrl+K, choose Skills, then Use.
+Variant inspection distinguishes the pinned session version from the latest saved version.
+Adding a library skill or rule creates a validated version for future sessions.
+
+`/accounts`, `/permissions`, `/settings`, `/trajectory` and `/log` retain their own centered pages.
+`/permissions` reviews device-local Pi terminal grants and the Full Permission switch; tool grants
+apply across terminal sessions sharing this Harness state, and Full Permission requires confirmation.
+`/trajectory` opens recorded runs for the current native conversation,
 with event navigation and a detail inspector. `/log` shows a static, redacted snapshot of Harness
 diagnostics and run events for the current conversation; press Escape to close. See
 [terminal architecture and evidence](docs/terminal-tui.md),
@@ -336,7 +389,7 @@ command the model runs in the shell cannot make it.
 A running session stays on the account it started with. To use another account for this
 session, choose **Use for this session**: the terminal child restarts and the same conversation
 resumes on that account. Removing an account that a running terminal is using is refused. Only
-terminals in this process are counted, so an account used by another running `xharness` window can
+terminals in this process are counted, so an account used by another running `xagent` window can
 still be removed; that session then asks for another account the next time it starts.
 
 The installed standalone command defaults to `~/.xingular-harness/data` and
@@ -362,6 +415,7 @@ for integrations such as Xingular Agent/App.
   runs/<id>/        run.json, events.jsonl, context.json, caller.json, subagents.json (reserved child IDs)
   config/           what is switched on for whom (plugin-attachments.json),
                     settings the harness reads
+  agents/<name>.md  a person's agent profiles (a repository keeps its own in .xingular/agents/)
   index.sqlite      a rebuildable index of runs for recall (FTS5)
   projects.json     read only: the application owns it
 
@@ -402,7 +456,7 @@ cannot carry it. See the [terminal guide](docs/terminal-tui.md#bash-command-mode
 
 ## Curated Hub
 
-`xharness hub list [--refresh]`, `xharness hub show publisher/name@version`, and
+`xagent hub list [--refresh]`, `xagent hub show publisher/name@version`, and
 `hub install publisher/name@version` browse and install exact catalog versions. `/hub` offers the
 same review in the interactive terminal, using its private control key for installation. Both the
 terminal and embedding applications use `hub.list`, `hub.get`, `hub.preview`, `hub.install`,
@@ -451,18 +505,18 @@ Use `/doctor` in the terminal for local readiness checks and explicitly selected
 structured jobs are available through `harness.doctor` and `doctor.*` server methods. See
 [Doctor](docs/doctor.md) for coverage, consent, isolation, and provider callbacks.
 
-## Public 1.0.0 release candidate
+## Public package
 
-The public package is ESM: import from `@xingular/harness` or supported subpaths such as
+The package is ESM: import from `@xingular/harness` or supported subpaths such as
 `@xingular/harness/variant/seed`. JavaScript and declarations are shipped in `dist/sdk`; a
-TypeScript loader is not required. Node 22.19 or later is required. The interactive terminal
-also requires Bun (release builds use 1.4.2); the CLI reports its version with `xharness --version`.
+TypeScript loader is not required. Node 22.19 or later is required. The interactive terminal also
+requires Bun (release builds use 1.4.2); the CLI reports its version with `xagent --version`.
 Original project code is Apache-2.0. See LICENSE, NOTICE.md and THIRD_PARTY_LICENSES.md.
 
 A host providing its own browser tools sets `browser: false` on `createHarness` to disable the
 generic backend and prevent tool-name collisions. The desktop App uses this for shared tabs.
 The default standalone Harness keeps its isolated browser backend enabled.
 
-This candidate intentionally resets development numbering to 1.0.0 while preserving old versions.
-See [release notes](docs/releases/1.0.0.md) and [release procedure](docs/releases/README.md).
-Publication requires registry verification, green CI and approval of the candidate/tag push.
+See the [1.2.0 release notes](docs/releases/1.2.0.md), [1.1.1 release notes](docs/releases/1.1.1.md),
+and the [release procedure](docs/releases/README.md). Publication requires pre-tag review of the exact candidate, two-OS CI, a separate protected
+`npm-publish` approval, registry verification, and npm provenance.