@xingular/harness 1.2.0 → 1.3.1-unstable.0

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,10 @@ 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 |
 
 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/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,22 +22,22 @@ 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 | — |
 | 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 | — |
+| 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.*` | `/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 |
+| 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 | — |
 | 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 |
@@ -92,13 +92,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 +116,7 @@ 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-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. |

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

@@ -29,8 +29,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`

package/docs/terminal-tui.md

@@ -1,6 +1,6 @@
 # Harness terminal frontend
 
-Status: current terminal behavior, checked against `@xingular/harness` 1.2.0. Last updated: 2026-11-19.
+Status: current terminal behavior, checked against `@xingular/harness` 1.3.0. Last updated: 2026-11-19.
 Decision: [ADR-0001](decisions/ADR-0001-owned-terminal.md),
 [ADR-0006](decisions/ADR-0006-opentui-only-terminal.md),
 [ADR-0009](decisions/ADR-0009-xharness-command.md),
@@ -93,9 +93,9 @@ The frontend is verified with a real isolated PTY and a loopback provider. Run
 `python3 scripts/verify-terminal.py --welcome-only --sizes 40x20,80x24,120x40` to check the empty
 welcome, product label, accent colors and `/help` transition. Run
 `python3 scripts/verify-terminal.py --composer-only` for recognized slash-command colors in the composer
-and a user bubble, unknown-command and argument colors, explicit-newline and soft-wrap checks of both
-prompt gutters, and normal/plan/Bash mode exclusivity. Run it with `--sizes 40x20,80x24,120x40` for
-compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
+and a user bubble, enabled-skill colors in the composer, unknown-token and argument colors,
+explicit-newline and soft-wrap checks of both prompt gutters, and normal/plan/Bash mode exclusivity.
+Run it with `--sizes 40x20,80x24,120x40` for compact through wide layouts. Use `--dialog-paste-only` to verify bracketed paste into a centered
 input dialog, `--file-completion-only` for filesystem completion and insertion,
 `--history-only` for active-session history across `/new` and `/session`, `--resume-only` for the full-screen searchable, unnumbered two-line saved-session picker, `--help-only` for `/help` replacing the welcome screen with grouped two-column output that wraps without per-command gaps, `--questions-only` for multi-select marker glyphs, recommended choices,
 selected-row and Continue/Submit colors, `--jump-latest-only` for scroll-away badge visibility and click-to-latest (screen-level click assertions use optional `pyte`), and choice-backed “Something else” answers, or `--thinking-only` for `/thinking` visibility toggles. The full suite covers a complete turn, `read`, `bash` approval, `ask_user_question` approval and picker, plugin overlay/widget/status
@@ -124,16 +124,24 @@ and a searchable `/subagents` page. The rows poll a private monitor route once p
 during a turn and make a final read at settlement. They sit one blank row below the status line, with
 no heading, and each reads: the status mark, the agent profile name in its colour (`subagent` for a
 copy of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` from the
-child's own checklist. At most three show, active first, then `+N more · /subagents`. The
+child's own todo list. At most three show, active first, then `+N more · /subagents`. The
 `/subagents` page uses a colored profile and normal-color title on the first line, then muted account,
 effective model, effort and cumulative usage metadata on the second. One blank row separates each
 two-line entry. The page also shows status, elapsed time and the latest tool name. Runtime metadata
 stays in the private terminal projection.
 Usage contains safe token/cache/cost/context totals, not per-request payloads or reasoning summaries.
 The projection is read-only, flat across nested descendants, and scoped to the latest parent run in
-this terminal session; finished rows remain visible until the next parent run starts. It is cleared
-on session replacement or terminal disposal. It never includes tool arguments (beyond the title),
-output or checklist item text.
+this terminal session; finished rows remain visible until the next parent run starts. The page also
+pins a `main` row for the parent run itself, with the same details; the rows under the status line
+leave it out. Reopening a conversation (a new launch, `/resume`, or a switch) rebuilds the rows from
+the branch's latest parent run and its saved child runs, with their final status, until the next run
+starts. A switch to a conversation without one clears them, as does disposal. It never includes tool
+arguments (beyond the title), output or todo item text.
+
+An interrupted or failed child keeps its saved conversation. The next reply is told which children
+stopped before it answers, and the parent continues one with `spawn_subagent { continue: <runId> }`,
+which reopens that child's own history with its profile and tools (ADR-0043). Esc therefore does
+not lose a child's progress.
 
 `/agents` opens the Agents page (PROP-0029): built-in, global, project and variant profiles with
 their tools, plugins, variant, model and instructions. Enter on a row edits a person's own profile
@@ -215,7 +223,7 @@ rule; then the work that followed. The summary is shown by default. Clicking eit
 shows it, and Ctrl+O shows every summary again. On a narrow screen the rule drops the click hint, then
 the token count. Earlier compactions in the same session keep their own rules and summary in place.
 Notices stay after the message they followed. The model sees the summary and recent messages plus a
-bounded, hidden checkpoint of the active request, checklist and plan instructions when available;
+bounded, hidden checkpoint of the active request, todo list and plan instructions when available;
 the checkpoint is regenerated for each post-compaction request until the run settles. The visible
 transcript remains a presentation of the full history, not the model context.
 Transcript entry ids follow positions in the displayed message list, so when a rebuilt list moves a
@@ -268,15 +276,20 @@ OSC 8 support. Inline and fenced code use a subtle panel fill with syntax colors
 list markers, tables, dividers and task-list markers use the existing titanium palette. Images
 display their alt text and are not fetched or rendered as image files.
 
-## Checklist block
+## Todo block
 
-`checklist_write` is registered in terminal sessions (PAR-001). Each call renders in the
-transcript as a checklist block: a status mark, `Checklist · n of m done`, then one line per item
-with `✓` (done, success colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim).
-Each row reserves a one-cell status column and one-cell gap; item text and wrapped lines share the
-same starting column. A call whose arguments are not a checklist, or that failed, stays an ordinary
-tool row. The prompt's Progress group asks the model to keep the list current and write a final
-update before replying; unfinished work remains unfinished rather than being marked complete.
+`todo_write` is registered in terminal sessions (PAR-001). Each call renders in the transcript as
+a todo block: a status mark, `Todo · n of m done`, then one line per item with `✓` (done, success
+colour), `●` (in progress, warning yellow, bold) or `○` (pending, dim). Each row reserves a one-cell
+status column and one-cell gap; item text and wrapped lines share the same starting column. A call
+whose arguments are not a todo list, or that failed, stays an ordinary tool row. The prompt's
+Progress group asks the model to keep the list current and write a final update before replying;
+unfinished work remains unfinished rather than being marked complete.
+
+`/todo` (alias `/checklist`) appends a snapshot of the current list: the same header and rows, with
+no status mark on the header, because it is not a tool call. It reads the latest non-side-question
+run of this terminal's native session and makes no model request; an empty list is a one-line
+notice.
 
 ## Blocks and pages
 
@@ -301,20 +314,36 @@ frontends draw that field from the same muted-blue selection palette (`selection
 explicit high-contrast text on it instead of the accent colour, so a choice reads the same in every
 list. Rules use the theme's `warning` and `dim` colors, so a custom theme restyles them.
 
-The Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills, Plugins,
-Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/plugins`, `/connections`
-(`/mcp`) and `/tools` open sections. `/hub` selects Discover and `/components` selects Library.
-The existing Accounts, Permissions, Settings, Trajectory and Log pages retain their own tabs.
+The broad Harness resource browser (PROP-0013) unifies Overview, Foundation, Variant, Skills,
+Plugins, Connections, Tools and Library. `/harness` opens Overview; `/skills`, `/connections`
+(`/mcp`), `/tools` and `/components` open sections. `/plugins` is a separate
+full-screen local manager with Plugins, Trust and Packages tabs; `/hub` is a separate
+full-screen Community catalog with Catalog and Installed tabs. Both keep a searchable
+inventory beside selected-item details on wide terminals, stacking details below the list
+on compact terminals. The existing Accounts, Permissions, Settings, Trajectory and Log
+pages retain their own tabs.
 
 `/settings` includes a Browser tab with the device-local **Private address access** setting. It is
 off by default. Enabling it asks for confirmation and allows agent browsing and annotation capture
 to reach localhost and private networks.
 
-Resource sections share Installed/Discover and source filters. Installed includes locally present
-resources; current-session availability comes only from the runtime loader and active tool registry.
-Discover uses the existing Hub with All/Community/Official filtering and an explicit remote refresh.
-No matching community entries is an empty result, never replaced with built-in resources.
-The view preserves search across source switches and restores section selection on return.
+Within the broad `/harness` browser, resource sections share Installed/Discover and source filters.
+Installed includes locally present resources; current-session availability comes only from the runtime
+loader and active tool registry. Discover uses the unfiltered Hub service with All/Community/Official
+filters and an explicit refresh. No matching Community entries is an empty result, never replaced with
+built-in resources. The view preserves search across source switches and restores section selection.
+
+The dedicated `/hub` Catalog shows Community entries across supported types only. Its Installed tab
+shows receipts from every channel with the channel labeled. On each page entry, cached/bundled entries
+appear first, then the remote catalog refreshes; the status keeps the origin, last-refresh time and any
+stale/error feedback visible. Manual refresh remains available. Catalog installs are pinned to the
+selected version, and Hub uninstalls remove only receipt-owned resources. Registry/document entries
+offer a bounded payload Preview; Pi packages have no JSON payload Preview.
+
+The `/plugins` manager keeps local switching, code trust and settings separate from public discovery.
+Its Packages tab adds local package installation, update and removal. Hub-owned packages remain pinned
+to exact catalog versions; removal goes through Hub receipt cleanup, and updating requires an explicit
+Hub version replacement.
 
 The browser fills the terminal (PROP-0014), with Overview, Foundation, Variant, Skills, Plugins,
 Connections, Tools and Library as persistent top tabs. The section dropdown and sidebar are removed.
@@ -329,8 +358,8 @@ Left/Right changes the focused tab or control; Enter on the tab strip returns to
 Ctrl+F focuses search. Escape returns from content to actions, returns to the list, clears search,
 then closes. Mouse clicks select tabs directly, activate resource actions and focus filters;
 wheel scrolling targets the list or inspector under the pointer. Other command pages keep their
-centered presentation; `/settings` and `/accounts` use full-screen page layouts. Closing the browser preserves
-the composer draft and attachments.
+centered presentation; `/settings`, `/accounts`, `/plugins` and `/hub` use full-screen page layouts.
+Closing the browser preserves the composer draft and attachments.
 
 Foundation explains fixed runtime ownership; it is read-only. Variant shows c1–c8 with the
 prepared version and current head separately. It previews pinned files from the preparation
@@ -384,16 +413,21 @@ Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi'
 queue until the active response settles, then runs by itself. Later messages remain behind it, even
 when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
 (`read`, `grep`, `find`, `ls`), web search/page reading, questions (`ask_user`, `ask_user_question`)
-and recall (history and Wiki reads, `memory_facts`). It may also delegate bounded research to a
-named profile whose effective tool and plugin allowlists qualify for research; the child inherits
-plan mode and receives only the intersection of the parent's frozen capabilities, profile and
-plan-research set. Children cannot write, run commands, ask the user, use connectors or spawn more
-children. Normal mode omits both question tools from the active set; the plan request enables
-registered questions and research delegation temporarily and restores the normal set when it settles,
-including on failure or interruption. Providers may mark individual calls as safe for research; every
-other call is blocked before approval. Edits, writes, shell commands, memory writes and connected-app
-tools remain unavailable to the parent and child. The plan instructions arrive as a request-scoped
-prompt section, which the next ordinary request withdraws.
+and recall (history and Wiki reads, `memory_facts`). The parent may also run Bash in the
+OS-enforced read-only sandbox: no network and no writes except a discarded per-command temporary
+directory (PROP-0043). It may delegate bounded research to a named profile whose effective tool and
+plugin allowlists qualify for research; the child inherits plan mode and receives only the
+intersection of the parent's frozen capabilities, profile and plan-research set. Children cannot
+write, run commands, ask the user, use connectors or spawn more children; they remain bounded by the
+configured work-slice policy without gaining `checkpoint_write`, and the Harness records an
+evidence-derived checkpoint if the child stops at a boundary. Normal mode omits both question tools
+from the active set; the plan request enables registered questions and research delegation
+temporarily and restores the normal set when it settles, including on failure or interruption.
+Providers may mark individual calls as safe for research; every other call is blocked before
+approval. Edits, writes, memory writes and connected-app tools remain unavailable to parent and
+child; generic browser controls are also blocked. Sandboxed read-only Bash is the parent's only
+plan-mode shell exception; children cannot run commands. The plan instructions arrive as a
+request-scoped prompt section, which the next ordinary request withdraws.
 
 Each mode keeps its own model and effort for the account. Every selection the person makes (the model
 picker, `/effort`, Shift+Up/Down, Ctrl+P) is saved against the mode it was made in, so Shift+Tab switches to that
@@ -699,12 +733,16 @@ normal-color title and a muted second line with relative activity time, `<projec
 file size separated by ` · `. One blank line separates each session. Enter resumes the selected
 session; account and folder scope checks
 remain enforced. Supplying an explicit path continues directly without opening the picker.
-The separate `$` palette completes enabled skill invocations; `/skills` always browses skills. `/help`
-renders the command list as one transcript entry, grouped under Core, Run, Model, Session, Inspect,
-Harness, Plugins and Prompts; command names and descriptions wrap in aligned columns, with no
-blank rows between choices. `/plugins` opens the browser with protected code trust and plugin settings actions. Settings use
-`plugins.configure`; on/off settings and bounded whole-number settings keep their existing ranges.
-Saved settings are read when the plugin next uses them and do not require a restart. The standalone
+The `$` palette completes enabled skill invocations using the same two-column palette as slash
+commands; `/skills` always browses skills. Choosing a skill inserts `$name ` without submitting.
+A recognized leading `$name` uses the blue accent in the composer, while its arguments, unavailable
+names and ordinary currency text keep the normal color. `/help` renders the command list as one
+transcript entry, grouped under Core, Run, Model, Session, Inspect, Harness, Plugins and Prompts;
+command names and descriptions wrap in aligned columns, with no blank rows between choices. `/plugins`
+opens the focused local manager; its Packages tab installs, updates and removes packages with protected
+Harness operations. Settings use `plugins.configure`; on/off settings and bounded whole-number settings
+keep their existing ranges. Saved settings are read when the plugin next uses them and do not require a
+restart. The standalone
 terminal no longer has separate `/login`, `/trust`, `/bug`, `/changelog`, `/share`, `/scoped-mode` or
 `/import` commands. `/btw <question>` (or `/side <question>`) starts a separate Harness run with the
 main run's effective instructions, visible conversation and redacted public tool inputs/results.
@@ -894,8 +932,9 @@ inherit that retained ledger.
 
 ## Agent-managed session names
 
-Agents can use `session_name({ name: string })` to name meaningful work early and revise
-its name when the objective changes. Names submitted by agents are short imperative
+Agents can use `session_name({ name: string })` to name work before their first other tool call
+when a request needs tools or changes state, and revise the name only when the objective changes.
+Names submitted by agents are short imperative
 sentences with at most six words. The agent may revise a manual name; `/name` remains
 available and manual names have no new word limit. Pi stores the name in native history,
 so resuming the same conversation restores it without another model request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "1.2.0",
+  "version": "1.3.1-unstable.0",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness built on recursive harnessing (Harness²): versioned eight-component variants, refinement from evidence, multi-account sessions, a compiled prompt, project notes, tools, and MCP",
   "repository": {

package/dist/sdk/tools/checklist.d.ts

@@ -1,9 +0,0 @@
-import { type ChecklistItem, type RunEvent } from "../sessions/contracts.js";
-import type { ActiveRun } from "../sessions/registry.js";
-import type { ToolSpec } from "./types.js";
-export declare const CHECKLIST_WRITE = "checklist_write";
-/** The checklist as the model reads it back. */
-export declare function describeChecklist(items: readonly ChecklistItem[]): string;
-/** The latest checklist a run wrote, or an empty list. */
-export declare function checklistOf(events: readonly RunEvent[]): ChecklistItem[];
-export declare function checklistTool(run: Pick<ActiveRun, 'emit'>): ToolSpec;