@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/docs/architecture/proposals/README.md

@@ -1,16 +1,16 @@
 # Architecture proposals
 
-A proposal is required before any change that alters a contract, an invariant, a layer
-boundary, an extension point, or the storage layout described in [the specification](../README.md).
-The author writes it and stops; the user reviews it. Code and spec pages change only after the
-proposal is `Accepted`.
+Proposals are optional design records for changes to contracts, invariants, layer boundaries,
+extension points, or storage layout in [the specification](../README.md). They may be written before
+or alongside implementation, but do not gate code or spec changes. When a proposal is created, add
+it to the index and update its status as the work progresses.
 
 ## Status
 
 | Status | Meaning |
 |---|---|
-| `Proposed` | Written, waiting for the user. Nothing has changed. |
-| `Accepted` | The user approved it. Implement it and update the spec pages in the same change. |
+| `Proposed` | A draft design record; implementation status is tracked separately. |
+| `Accepted` | The user approved the design. Approval is not a prerequisite to implementation. |
 | `Implemented` | Code and spec pages match the proposal. Link the commit or ADR. |
 | `Rejected` | The user declined it. The file stays as a record. |
 | `Withdrawn` | The author dropped it before review. |
@@ -73,6 +73,11 @@ proposal is `Accepted`.
 | [PROP-0041](PROP-0041-bounded-work-slices.md) | Bounded work slices, a durable checkpoint, and a stall guard for long replies | Implemented; terminal card, App presentation and /slices open (PAR-004) | INV-RUN-2/3/4/12, INV-PRM-1/2/4/5/10, INV-GATE-2, INV-STO-3, INV-PAR-1/2, 02, 04, 07, 10–12, 14, parity | 2026-10-26 |
 | [PROP-0042](PROP-0042-usage-and-provider-limits.md) | Usage analytics and provider limits as a built-in capability | Accepted; implemented | INV-MEM-5/6, INV-STO-2, INV-SRV-1, INV-PLG-10, INV-ACC-3, 02, 06, 08–12, 14, parity, ADR-0037 | 2026-10-26 |
 | [PROP-0043](PROP-0043-read-only-plan-bash.md) | Read-only Bash in plan mode, enforced by the OS sandbox | Accepted; implemented | INV-RUN-8, INV-GATE-3/8, 02, 07, 11, terminal-tui, parity, ADR-0038 | 2026-10-26 |
+| [PROP-0044](PROP-0044-work-slice-defaults.md) | Raise the work-slice defaults to 320 tool calls and 60 minutes, with no token cap | Accepted; implemented | INV-RUN-13, 02, 10, 11, PROP-0041 | 2026-10-26 |
+| [PROP-0045](PROP-0045-rename-checklist-to-todo.md) | Rename the run checklist to todo and add the /todo command | Accepted; implemented | 02, 04, 06, 07, 10, 11, 14, parity, terminal-tui, README, PROP-0006 | 2026-10-26 |
+| [PROP-0046](PROP-0046-progress-aware-stall-guards.md) | Progress-aware stall guards and bounded plan research children | Implemented; ADR-0039 | INV-RUN-13, 02-sessions-and-runs.md, PROP-0041, terminal-tui.md, ADR-0039 | 2026-10-27 |
+| [PROP-0047](PROP-0047-plugins-hub-separation.md) | Separate local plugin management from Community Hub discovery | Implemented; ADR-0041 | INV-MCP-4, INV-TUI-2/4, INV-PAR-1/2, 06, 09, 10, 11, 14, terminal-tui.md, parity.md | 2026-10-27 |
+| [PROP-0048](PROP-0048-simple-annotate.md) | One annotate page, two actions, and easy app attach | Implemented; ADR-0044 | PROP-0018, 07, 10, 11, 13, terminal-tui.md, parity.md | 2026-10-27 |
 
 Numbers are four digits, start at `0001`, and are never reused.
 

package/docs/decisions/ADR-0039-progress-aware-stall-guards.md

@@ -0,0 +1,39 @@
+---
+id: ADR-0039
+title: Progress-aware stall guards and bounded plan research children
+status: Accepted
+created: 2026-10-27
+proposal: PROP-0046
+---
+
+# ADR-0039: Progress-aware stall guards and bounded plan research children
+
+## Decision
+
+Remove the global file-change/check no-progress trigger. Keep the targeted protections for repeated
+calls, repeated failing checks, per-path edit churn, compaction thrash, and the independent
+work-slice call/time budgets. Count edit churn only from successful native `edit`/`write` results
+with a path. A successful edit/write clears failed-check counts, exact Bash-check repetition counts
+and the pending nudge, but preserves edit counts and repeats of other calls; a passing check clears
+edit churn.
+
+Bound plan-research children with the configured work-slice policy without adding
+`checkpoint_write` or any other capability. When that tool is absent, a budget or stall refusal asks
+the child to stop and return partial findings; another tool call ends the reply, and the runner
+records an evidence-derived checkpoint. Children do not auto-continue. Plan-mode browser and
+connected-app restrictions remain unchanged.
+
+## Rationale
+
+Distinct reads are not evidence of a stall, and the former 25-call threshold imposed an arbitrary
+file/check-progress boundary. Tool results are the shared, observable signal for whether a native
+edit succeeded; treating failed or blocked attempts as edits would consume the churn allowance
+without changing code. Resetting check-retry state after a successful edit lets the same check run
+against changed input without weakening protection when code is unchanged. A derived checkpoint
+bounds read-only research children without widening their frozen capability set.
+
+## Consequences
+
+Long sequences of distinct reads are limited by the configured slice budget and targeted loop
+protections, not by missing file/check progress. No run-event schema, stored-data layout or server protocol changes are introduced; the terminal
+uses the same guard rules. See [PROP-0046](../architecture/proposals/PROP-0046-progress-aware-stall-guards.md).

package/docs/decisions/ADR-0040-architecture-change-workflow.md

@@ -0,0 +1,31 @@
+---
+id: ADR-0040
+title: Architecture changes do not require proposal approval first
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0040: Architecture changes do not require proposal approval first
+
+## Decision
+
+The architecture specification remains binding, and changes that alter its contracts, invariants,
+layer boundaries, extension points, or storage layout must update the affected specification pages
+in the same change. Such work does not require a proposal or user approval before implementation.
+
+Proposals remain optional design records. When used, they may be created before or alongside
+implementation and should be indexed and status-tracked. Add an ADR for a lasting architectural
+choice. Report existing code/spec drift and resolve relevant drift by updating both sides together
+within the requested scope.
+
+## Rationale
+
+A binding specification and same-change documentation keep implementation accountable to the
+architecture without making a separate proposal review a prerequisite to requested work. Optional
+proposals remain available when a design benefits from a written comparison or durable rationale.
+
+## Consequences
+
+Coding agents read the affected specification pages, implement the requested change, update the
+specification in the same change, and run relevant checks. Proposal status records design review or
+implementation progress but does not gate implementation.

package/docs/decisions/ADR-0041-plugins-hub-separation.md

@@ -0,0 +1,41 @@
+---
+id: ADR-0041
+title: Separate local plugin management from Community Hub discovery
+status: Accepted
+created: 2026-10-27
+proposal: PROP-0047
+---
+
+# ADR-0041: Separate local plugin management from Community Hub discovery
+
+## Decision
+
+- `/plugins` is the dedicated local installed-plugin manager: switching, code trust, settings, and
+  local package install, update and removal. It does not browse the public catalog.
+- `/hub` is a distinct public-catalog page. Its Catalog view shows Community entries across active
+  supported types; its Installed view shows receipts from every channel with the channel visible.
+  The broad `/harness` resource browser remains available.
+- Opening Hub shows cached or bundled entries first, then refreshes remotely. The page retains the
+  data origin, last-refresh time and any fallback/error status. Registry/document entries keep a
+  bounded payload Preview; Pi packages have no payload Preview.
+- A Hub-owned package cannot be silently floated by `plugins.update`. Removing it through
+  `plugins.remove` delegates to Hub's exact-receipt uninstall operation; Hub remains the writer of
+  its receipt and owned resources. Replacing it requires an explicit, exact catalog version.
+- Host presentations use the same filtering, refresh and receipt lifecycle while choosing their own
+  layouts. No new capability, loader, storage format or server response schema is introduced.
+
+## Rationale
+
+Local plugin management and public catalog discovery have different owners and different safety
+contracts. Separating the direct pages makes that visible without duplicating the services: local
+packages use the plugin manager, while Hub installs are pinned catalog releases with receipts. A
+Community-only catalog view also avoids presenting official items as community submissions, while
+retaining existing Official receipts for management.
+
+## Consequences
+
+The direct terminal and host routes have distinct screens, but `/harness` stays a broad resource
+browser. Catalog filtering is presentation-only; `hub.list` remains unfiltered for other callers.
+Existing receipts and plugin settings need no migration. The current public catalog has no
+Community Pi-package entry, so no Community plugin appears until a publisher adds one. See
+[PROP-0047](../architecture/proposals/PROP-0047-plugins-hub-separation.md).

package/docs/decisions/ADR-0042-windows-shell-without-sandbox.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0042
+title: Run Windows commands behind a per-call approval instead of a sandbox
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0042: Run Windows commands behind a per-call approval instead of a sandbox
+
+## Context
+
+Bash runs inside an OS write-boundary sandbox: `sandbox-exec` on macOS, bubblewrap on Linux
+(INV-GATE-3, INV-GATE-8). Windows has neither, and missing enforcement fails closed, so on Windows
+every Bash call, and every native `write` and `edit` (whose helper was launched through the same
+sandbox), failed before it started. The shell lookup also searched only `/bin/bash`. A harness
+installed from npm on Windows could not run a command or change a file.
+
+## Decision
+
+- **Shell.** On Windows, commands run in Git Bash (`%ProgramFiles%\Git\bin\bash.exe`,
+  `%ProgramFiles(x86)%\Git\bin\bash.exe`, then `bash.exe` on `PATH`, never the WSL launcher in
+  `System32`), otherwise in PowerShell (`pwsh.exe`, PowerShell 7 in Program Files, then Windows
+  PowerShell). The capability and tool keep the name `bash`, so capability sets, the gate, plan
+  lists and approvals are unchanged; the description names the shell.
+- **Bash.** Every Windows command takes the existing `outside` path: a human-only one-call approval
+  or an eligible Full Permission answer, then it runs once unconfined. Remembered tool grants never
+  answer it. Plan-mode (read-only) Bash is refused on Windows.
+- **Write and edit.** On Windows the atomic helper runs with Node directly. The target is still
+  canonicalized, authorized, revalidated, and replaced by rename; outside targets still need their
+  one-call approval. In-workspace writes do not ask.
+- `/doctor` reports the Windows shell as a warning that names it and the approval rule.
+
+## Consequences
+
+- The harness works on Windows right after `npm install`, with no Git or native helper required.
+- Windows commands are unconfined once approved. The guarantee comes from the person, not the OS.
+- On Windows, a junction or symlink swap between the write check and the rename is not prevented
+  by the OS. Atomic replacement still keeps a write from going through a hard-link alias.
+- A real Windows sandbox (restricted token and ACLs through a native helper) would let Windows use
+  the macOS/Linux rules again. It is not built.

package/docs/decisions/ADR-0043-parents-continue-stopped-subagents.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0043
+title: A parent continues its stopped subagents; the monitor shows the main agent and survives reopening
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0043: A parent continues its stopped subagents
+
+## Decision
+
+- `spawn_subagent { continue: <runId> }` (and `subagents.spawn { continue }`) continues a child that
+  stopped before finishing (`interrupted` or `failed`, with saved history). It is a new child run
+  with `continueFrom`. It reopens the first link's history folder
+  (`<parent sessionDir>/subagents/<first child run id>`) and keeps the earlier child's session id,
+  profile, title, goal, account, variant version and frozen capability set. That set must still lie
+  within the parent's ceiling; `agent` and `tools` are refused with `continue`. The id may name any
+  link of a chain: the newest link is the one continued, and an active or completed newest link is
+  refused.
+- The model decides. A subagent never continues itself, and a restarted harness never restarts
+  model work (INV-RUN-4). Children an earlier reply left stopped are delivered **before** the next
+  reply's first request: a hidden `xingular-subagent-results` message with a receipt, which says
+  each child can be continued. A stopped child that has a continuation is reported through that
+  continuation instead.
+- Recovery of an earlier parent's children is keyed on the native history branch: the owner
+  marker, the same native history id, account, agent, project and working folder. The Harness
+  session id is not compared, because a host may give each launch of one conversation a new one.
+- `main` is a reserved profile name. The terminal monitor projects the parent run itself as a
+  `main` row: account, model, effort, usage, activity and todo counts, like a child. The
+  `/subagents` page shows it pinned first; the rows under the status line omit it.
+- The terminal marks every turn's run on the branch (`xingular-subagent-owner`). When a
+  conversation opens with no run active, it rebuilds the monitor from the branch's latest parent
+  run in that folder and its descendants, by folding their saved events. The rows keep their final
+  status until the next run begins.
+- Run records carry the launch `model` and `effort` (the opened session's model supersedes the
+  selection), so a rebuilt row can show them.
+
+## Rationale
+
+Esc on a parent interrupts every child, and until now the next turn was told to start them again.
+That lost work that was saved on disk. Reopening a child's own history keeps every pin a run
+already has, so no capability or account can change, and leaving the choice to the model keeps
+INV-RUN-4.
+
+## Consequences
+
+The monitor stays a private, read-only terminal projection; no event or public method is added.
+Records written before this change have no `model` or `effort`, and their rebuilt rows show `—`.
+A person cannot continue a child from the page directly; they ask the parent.

package/docs/decisions/ADR-0044-annotations-pending-or-sent.md

@@ -0,0 +1,24 @@
+---
+id: ADR-0044
+title: An annotation is pending or sent; the agent's page-note tools are read-only
+status: Accepted
+created: 2026-10-27
+---
+
+# ADR-0044: An annotation is pending or sent
+
+## Decision
+
+- Every annotation a person makes in the inspector with a session is shared with that session at
+  once and is **pending** until sent. There is no queue to add to or take out of, and no "fixed"
+  state. Records written before keep working: `queued` reads as `pending`, `fixed` as `sent`.
+- The popover has two actions, Annotate and Annotate & send. A send sends every pending note of
+  the session as one message, optionally followed by the person's request (`/annotate:submit`).
+- `page_notes_mark_fixed` is removed. The agent reads annotations; only the person resolves them.
+- A held-back send is retried while the session is still busy after a run ends.
+- Built-in plugin commands may be `rootOnly`, so a namespace root is not listed twice.
+
+## Why
+
+People found three actions, a queue and a fix status too much to control, and the extra state is
+what made sends fail silently. See [PROP-0048](../architecture/proposals/PROP-0048-simple-annotate.md).

package/docs/decisions/ADR-0045-default-plugin-authoring-skill.md

@@ -0,0 +1,9 @@
+# ADR-0045: Release-owned plugin-authoring skill
+
+## Decision
+
+Ship plugin-authoring guidance as an on-demand Harness resource, selected for both structured and terminal sessions without changing variant versions. A pinned variant's skill of the same name takes precedence. The release supplies the resource in the package; the normal skill loader and Pi resource loader expose it. The guidance grants no trust or permissions.
+
+## Consequences
+
+Existing variants receive the guidance without migration. Its release-owned content can change with the installed Harness version rather than with a variant fingerprint. Only its name and description are advertised until requested; the body does not enter the always-on variant text. Proposal creation and hash-bound review are separate from the skill and are recorded in [ADR-0046](ADR-0046-hash-bound-plugin-proposals.md).

package/docs/decisions/ADR-0046-hash-bound-plugin-proposals.md

@@ -0,0 +1,20 @@
+# ADR-0046: Hash-bound plugin proposal review
+
+## Decision
+
+Keep model-authored plugin proposals as inert, bounded text in the data root. The model may create
+one through the gated `plugin_propose` tool; only a trusted caller may accept or reject it. Both
+decisions require the hash of the current revalidated preview. The hash binds the name, description,
+generated manifest and sorted file contents, not a person's identity or an authorization grant.
+Acceptance publishes a new package switched off, does not run its code or grant trust, and refuses
+an existing package name or identical already-trusted package code. Normal attachment, code trust,
+capability and approval checks remain separate.
+
+## Consequences
+
+Reviewers can inspect exactly the content a decision names, and stale or already-decided reviews
+are refused. Text can itself contain hostile instructions and may load when enabled without code
+trust; review must cover every contribution. Proposal records, including rejected ones, remain in
+the data root; device-local code trust remains in the state directory. This decision does not claim
+that a terminal or host review UI exists. See [06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[10 Server protocol](../architecture/10-server-protocol.md), and [PAR-017](../parity.md#gaps).

package/docs/decisions/ADR-0047-links-open-with-the-os-handler.md

@@ -0,0 +1,47 @@
+---
+id: ADR-0047
+title: A link a person clicks opens with the system's own handler, through one allowlist
+status: Accepted
+created: 2026-11-20
+---
+
+# ADR-0047: A link a person clicks opens with the system's own handler
+
+## Decision
+
+- `core/links.ts` holds the one link policy: `linkTarget` classifies a target without touching the
+  filesystem (`http`/`https`, `mailto`, `file`, an absolute path, or a relative path under a
+  supplied base), and `openableTarget` checks what a path names before anything is launched.
+- A path may be opened only when it is a regular file or a directory, is not an application bundle
+  or an installer, is not a launchable script kind (`.command`, `.sh`, `.bat`, `.pkg`, `.dmg`,
+  `.app`, …), and has no executable bit set. The last two matter because `xdg-open` runs an
+  executable file and `open` launches a bundle.
+- The address reaches `open` (macOS), `xdg-open` (Linux and the BSDs) or `rundll32.exe
+  url.dll,FileProtocolHandler` (Windows) as one argument, never through a shell.
+- `links.open` is a server method, so a host presents the same capability, and the terminal is the
+  reference surface: hovering a link recolours it, and the gesture the platform uses opens it —
+  Ctrl+click where a terminal reports the modifier, and the primary click on macOS, whose ⌘ the
+  terminal mouse protocol cannot carry. The opener is `HarnessOptions.linkOpener`, so a host with
+  its own native opener replaces the spawn and keeps the policy.
+- A link is a person's action. Nothing here is in `HARNESS_TOOLS`, so the gate, standing approvals
+  and redaction are not involved, exactly as with `variants.save`.
+- Both front ends show the hover state: the terminal repaints the hovered link's spans in
+  `theme.linkHover`, and the App uses the shared `--link-hover` token on `a:hover`. The App's
+  modifier is the platform's own: ⌘ on macOS, Ctrl elsewhere.
+
+## Rationale
+
+The terminal opened web links only, and the App opened web pages and stored documents in its
+sidebar while silently swallowing everything else — `mailto:`, folders, relative paths and unknown
+kinds. The allowlist existed three times (a terminal module, the App's TypeScript, and the App's
+Rust), which is the drift the parity rules exist to prevent. One policy in the Harness, used by
+both surfaces, is the smallest thing that makes a link behave the same everywhere.
+
+## Consequences
+
+A refused link is reported, never ignored: the terminal posts a notice and the App reports an
+error. Opening a document still hands its bytes to whichever application the system has associated
+with that kind, which is inherent to the request; the deny list and the executable-bit check are
+the boundary, not a sandbox. A host that wants different kinds to open replaces `linkOpener`, and
+an architecture change would be needed to let a model open a link on its own, because that would
+put an operating-system action inside the gate's reach.

package/docs/doctor.md

@@ -8,10 +8,23 @@ provider requests, token refreshes, browser launch, permission prompts or comput
 pass does not establish live connectivity. Other accounts show their saved status and timestamp.
 Providers without diagnostics report unverified. Disabled capabilities are not failures.
 
+The shell check reports which `bash` the session would run and whether the platform's
+write-boundary sandbox (sandbox-exec on macOS, bubblewrap on Linux) is installed, because a missing
+backend stops every Bash call before the command starts. It runs nothing. On Windows it reports a
+warning naming the shell (Git Bash or PowerShell) and that each command asks for approval, because
+Windows has no write-boundary sandbox; the live shell check reports unverified there, since a
+command would need a person to approve it.
+
 Press `l` to choose live checks, then review the account/model, destinations, possible charges and
 isolation notice. The model check makes one synthetic request with at most 64 output tokens;
 usage appears on a separate diagnostic run. Web checks fetch example.com and search for “example
-domain”. MCP checks connect/list only. Browser checks use a disposable headless profile and an
+domain”. The shell check runs one fixed command written by the harness (`printf`) in the working
+folder through the same root, hard-link scan and write-boundary sandbox a normal Bash call uses, and
+reports only the exit status: no model input is sent, no file is written and no network request is
+made. A diagnostic never widens the boundary, so Full Permission cannot change its result; when the
+boundary refuses before the shell starts (for example a hard-link alias in the workspace), the
+finding is blocked with that reason instead of claiming the shell is broken. MCP checks
+connect/list only. Browser checks use a disposable headless profile and an
 offline synthetic page; configured CDP attachment is blocked. Computer input is blocked unless the
 host supplies a disposable diagnostic surface; the current desktop host supplies readiness only.
 

package/docs/parity.md

@@ -22,26 +22,28 @@ implemented is not a parity claim; acceptance is tracked per command.
 | 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 | — |
+| Plan mode | `sessions/planMode.ts` | `plan: true` | `/plan`, Shift+Tab, plan card; bounded plan/todo 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 | — |
+| Workspace-scoped writes | `core/workspace.ts`, `sessions/workspaceBoundary.ts`, `core/workspaceBashTool.ts`, `core/workspaceSandbox.ts`, `core/workspaceWriteOperations.ts` | pinned non-root `RunRecord.workspaceRoot`; native `edit`/`write`; Bash scope | revalidated atomic native writes; external-hard-link scan and Bash sandbox (Windows: no sandbox, each Bash call asks once, plan-mode Bash refused; ADR-0042); complete escaped outside command in scrollable approval details (deny if too small); no output-triggered retry | same Harness gate and full approval action in scrollable App details; App policy can tighten scope; Full Permission remains the eligible explicit bypass | parity | — |
 | Side questions | `sessions/sideQuestions.ts` | `sideQuestions.start/read/interrupt`; terminal `terminal.sideQuestions.*` | `/btw` contextual dock 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 | — |
+| Opening a link | `core/links.ts` | `links.open`; `HarnessOptions.linkOpener` (ADR-0047) | hover shows the hand pointer and recolours the link, Ctrl+click (the primary click on macOS, whose ⌘ the mouse protocol cannot report) opens web, `mailto:`, file and folder targets with the system handler, a refused link posts a notice | ⌘-click on macOS and Ctrl+click elsewhere opens with the system handler, a plain click keeps the sidebar and falls back to the system for what it cannot show, `a:hover` uses `--link-hover` | implemented; acceptance not certified | — |
 | Questions (`ask_user`) | `tools/askUser.ts` | shared `ask_user` tool | plan-mode dock: strict aligned columns, bounded body scroll, 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 |
+| Subagents | `sessions/subagentService.ts` | `spawn_subagent` (requires `title`, PROP-0030; `continue` resumes a stopped child, ADR-0043), `subagents.*`; plan mode allows only named eligible read-only research profiles | `/subagents` page with the `main` row pinned first, and live rows under the status line (mark, profile, parent-set title, `n of m tasks`), both rebuilt from saved runs when a conversation reopens; plan-mode research delegation uses the same Harness gate | reply trajectory; plan-mode research delegation uses the same Harness gate | parity | — |
+| Agent profiles | `agents/profiles.ts` | `spawn_subagent { agent }`, `agents.list/get/create/remove`; terminal `terminal.agents.*`; package profiles through `Loading.profilePaths` | `/agents` page: browse, create, edit in `$EDITOR`, copy, delete; package profiles listed under "From a plugin" and switched on `/plugins` | Solo `/agents` lists profiles; profile details and management are not wired | partial | PAR-010 |
+| Run todo list | `tools/todo.ts` | `todo_write`, `runs.todo` (`runs.checklist` deprecated); terminal `todo` telemetry | registered in terminal sessions and their subagents; each write shows as a todo block in the transcript; `/todo` shows the current list; a subagent row shows its `n of m tasks` | `/todo` shows the current list on demand; each write is not rendered inline | terminal done; App shows it on demand | PAR-001 |
 | Continuation of a stopped run | `sessions/continuation.ts` | `continueFrom`, `runs.continuation` | not offered (`/resume` reopens history only) | not offered | planned | PAR-003 |
 | Bounded replies and checkpoints (PROP-0041) | `sessions/workSlice.ts`, `tools/checkpoint.ts`, `sessions/runner.ts` | `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 | — |
+| Plugins and Hub | `plugins/`, `hub/` | `plugins.*`, `hub.*` | full-screen `/plugins` local manager; separate full-screen `/hub` Community catalog with bounded registry/document Preview (no Pi-package Preview) | local Plugins manager; Community Hub with payload Preview for non-package entries | parity | — |
+| Plugin authoring and proposal review | `plugins/proposals.ts`, `tools/defaultSkills.ts` | `plugin_propose`, `plugins.proposals.*` | `/plugins` Proposals tab: preview, accept or reject | structured model tool and skill; review UI not implemented | partial; App review pending | PAR-017 |
 | Connected apps (MCP) | `mcp/` | `connections.*`, broker tools | resource browser Connections tab | Connections | parity | — |
 | Web search and page reading | `web/` | `web_search`, `web_fetch` | world tools | world tools | parity | — |
 | 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 |
+| Web annotations | `annotations/` (PROP-0017, PROP-0018, PROP-0038, PROP-0048) | `annotations.*`, `annotations.capture.*`, `page_notes_*` | `/annotate:` page (Annotate and All annotations tabs; DevTools app list and launch), `/annotate:notes`, `/annotate:submit`, `/annotate:clear` | website tab Annotate panel (inspector, queue to the focused thread, app windows through `annotations.capture.*`) | App behind PROP-0048 (queue methods removed); native WKWebView gestures unaccepted | PAR-011 |
 | Managed worktrees | `worktrees/` (PROP-0016) | `worktrees.*` | `--worktree`, `/worktree`, `xagent worktree` | Solo `/worktree` lists records only; Solo starts sessions in the project folder and has no worktree level | partial | PAR-012 |
 | Wiki notes (model tools) | `wiki/`, `tools/` | `wiki_*` | `Terminals.ownTools` registers Wiki-read tools through the session socket; `xagent-wiki` remains a person-facing shell utility | structured Harness tools | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
 | History and trajectory (model tools) | `history/` | `history_*`, `trajectory_*` | `Terminals.ownTools` registers model tools through the session socket; `/trajectory` page; `/history` navigates session branches | structured tools and trajectory views | implemented on both; acceptance not recertified | PAR-002: acceptance not recertified |
@@ -51,7 +53,7 @@ implemented is not a parity claim; acceptance is tracked per command.
 | 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 |
+| Provider limits | `usage/limits/` (PROP-0042) | `usage.limits` | `/usage:limit` (current account), `/usage:accounts` (all accounts) | not wired | terminal implemented; host planned | PAR-016 |
 | Session catalog (sessions per folder) | `sessions/` saved-history controls; shared catalog not implemented | `sessions.*` controls; no cross-surface catalog method | `/session` selects native Pi histories in the current folder | `/session` reads `bridge.agent.threads(SOLO_ID)`, maps each thread to its project folder, and filters by current effective account; `all` broadens only this App list | planned; catalogs differ | PAR-008 |
 | Folder choice and recent folders | project/worktree selection remains surface-specific | launch `cwd`, `--worktree`, `/worktree` | starts in launch folder; explicit worktree commands | Solo sidebar is Project › Session; new sessions use the project's folder, with no folder/worktree level | planned; no shared recent-folder picker | PAR-009 |
 | Computer control | — | `computer_*` (host tools) | unavailable, with reason | macOS bridge (host-backed) | host-backed | PAR-007 |
@@ -92,13 +94,13 @@ this fixed table.
 | `/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 |
+| `/plugins` | Full-screen local Plugins manager | Opens local Plugins manager | Not certified per command |
+| `/hub` | Separate full-screen Community Hub catalog | Opens Community Hub | Not certified per command |
 | `/components` | Components browser | Opens App Harness components | Not certified per command |
 | `/settings` | Terminal settings | Opens App settings | Not certified per command |
 | `/doctor` | Doctor checks, including explicitly confirmed live probes | Runs local readiness checks only | Not certified; App route does not expose live checks |
 | `/worktree` | Managed-worktree page and actions | Lists worktrees; Solo has no typed create/status/remove methods wired, and no worktree level | PAR-012; management actions unavailable; not certified |
-| `/subagents` | Live monitor and roster | Opens latest run's trajectory, not a dedicated subagent roster | Not certified; surfaces differ |
+| `/subagents` | Live monitor and roster with the `main` row, restored on reopen | Opens latest run's trajectory, not a dedicated subagent roster | Not certified; surfaces differ |
 | `/agents` | Browse/create/edit/copy/delete profiles | Lists profiles only; detail/create/remove methods are not wired into Solo | PAR-010; management actions unavailable; not certified |
 | `/log` | Harness diagnostics and current run events | Opens latest run's trajectory, not a separate log reader | Not certified; surfaces differ |
 | `/hotkeys` | Keyboard controls | Opens App shortcut settings | Not certified per command |
@@ -116,7 +118,8 @@ or live-model sketch quality.
 
 | 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-017 | Plugin proposal review surfaces | The terminal provides hash-bound review in `/plugins`; the App has no proposal review UI yet. |
+| PAR-001 | Todo list not rendered inline in the App | Both surfaces can show the current list: the terminal renders each write as a todo block and `/todo` shows a snapshot; the App's `/todo` shows a read-only list. The App still does not draw an inline block for each write. |
 | PAR-002 | Acceptance of terminal-model History/Wiki/skill tools | Source gap resolved: `Terminals.ownTools` registers History/trajectory, Wiki-read and skill tools over the session socket; `xagent-wiki` is a user-facing shell utility, not the model's only route. Acceptance has not been recertified in this documentation pass. |
 | PAR-003 | Continuation unused | `/resume` lists interrupted runs and continues one with `continueFrom`; the App offers Continue. |
 | PAR-004 | Refinement and adoption only in the App | Variant tab actions: start, candidates, adopt, trust. |
@@ -126,7 +129,7 @@ or live-model sketch quality.
 | 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-011 | Web annotations | Harness, terminal and App source done (PROP-0017, PROP-0018, 2026-10-24): the App calls `annotations.*`, imports its old notes once, uses the `page_notes_*` tools, and has the Annotate panel. Open: acceptance of the inspector and selection gestures in the running App's WKWebView. PROP-0038 (2026-10-25): both front ends share the page helper, so open shadow roots work in the terminal's capture browser and the App's tabs alike; composed text capture, save, resolve and reveal were exercised in an isolated App WKWebView, inspector clicks were not. PROP-0048 (2026-10-27): Harness and terminal moved to pending/sent with two popover actions, send-all with an optional request, clear, read-only page-note tools, and DevTools app discovery and launch; the App's Annotate panel still uses the removed queue methods and must follow. |
 | PAR-012 | Managed worktree management in Solo | Harness and terminal provide full worktree operations (PROP-0016). Solo `/worktree` lists records only: its renderer adapter does not wire typed `worktrees.create`, `status` or `remove` calls, and Solo session creation stays at the project folder with no worktree level. Handoff, branch, prune, restore and setup-trust actions are also absent from this Solo surface. |
 | PAR-013 | Expanded question wireframes and terminal layout | Closed by [PROP-0025 verification](evidence/terminal-question-wireframes/README.md): four-size production PTY acceptance covers aligned compact columns, body scrolling, pinned controls, Shift+arrow sketch panning and live resizing. Host contracts accept 80×24 literal ASCII sketches (1,943 bytes); six isolated browser tests include exact-boundary content, accessible overflow and unchanged selection/answers. This is controlled fixture acceptance, not live-provider or native Tauri evidence. |
 | PAR-014 | Connected terminal sketch display | Closed by [PROP-0026 verification](evidence/terminal-connected-sketches/README.md) and extended by [PROP-0028 verification](evidence/terminal-wireframe-normalization/README.md): production PTY fixtures cover connected corners/tees, title-bearing rules, missing and whitespace-shifted side edges, internal table widths, frame-attached dividers, resize/panning and unchanged raw persistence/answers. Harness and host checks passed. Host literal rendering remains permitted; no host implementation change was required. This is fixture verification, not an every-font or live-model guarantee. |

package/docs/releases/1.3.0.md

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

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

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

package/docs/releases/README.md

@@ -2,12 +2,14 @@
 
 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.
+   and caches. Stable versions use `X.Y.Z`; unstable previews use `X.Y.Z-unstable.N` and publish
+   to npm's `unstable` dist-tag. Use a new, unused version for every publication.
 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.
+   `--offline` is only a local smoke check, not fresh-install acceptance. Unstable candidates go
+   through the same checks as stable releases.
 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
@@ -20,8 +22,9 @@
    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.
+   `--tag latest` for stable versions or `--tag unstable` for unstable previews, then verifies the
+   matching registry dist-tag, integrity and provenance and creates a GitHub release (marked
+   prerelease for unstable versions). 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
@@ -29,8 +32,8 @@ intentional 1.0.0 reset does not rewrite historical decisions or claim an orderi
 
 ## Historical 4.0.0 candidate evidence
 
-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 following report records a prior candidate and registry snapshot; it is not evidence for any
+current candidate or a description of the current release gates.
 
 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`