@xingular/harness 1.2.0 → 1.3.1-unstable.0

package/docs/architecture/00-overview.md

@@ -134,7 +134,7 @@ Modules with no member of their own: `variant/` (functions over the variant stor
 | Letter | The harness owns |
 |---|---|
 | **E** Execution | Isolated account folders, the Pi session, the terminal launch spec |
-| **T** Tools | History, trajectory, Wiki notes, skill loading, `ask_user`, the run checklist, the connected-apps broker, the tool gate |
+| **T** Tools | History, trajectory, Wiki notes, skill loading, `ask_user`, the run todo list, the connected-apps broker, the tool gate |
 | **C** Context | The compiler, stable prefix and updates, the versioned variant (c1–c8), skills, on-demand Wiki notes |
 | **L** Lifecycle | Run state, interrupt, recovery, approvals and questions, subagents, refinement |
 | **O** Observability | Validated run events saved per run; usage counters |

package/docs/architecture/01-extension-points.md

@@ -50,7 +50,7 @@ harness forwards to the policy and never reads.
 ## Invariants
 
 - **INV-EXT-1** There are seven extension points. Adding, removing or changing the shape of one is
-  an architecture change (proposal required).
+  an architecture change; update this page and affected contracts in the same change.
 - **INV-EXT-2** Every extension point is optional. The harness runs with none of them supplied.
 - **INV-EXT-3** An extension point carries data or decisions the application owns. It never
   carries an application's name or a branch for one application (`INV-BND-3`).

package/docs/architecture/02-sessions-and-runs.md

@@ -13,7 +13,7 @@ records everything the run does as validated events.
 |---|---|---|
 | `Sessions` | `sessions/sessions.ts` | Starts a turn: `run(input: SessionRunInput)`, `provide(provider)`. Builds the gate. |
 | `runTurn`, `piSessionFactory`, `loadResources` | `sessions/runner.ts` | Opens the Pi session, loads resources in a fixed order, streams events, settles the run. |
-| compaction checkpoint | `sessions/compactionCheckpoint.ts` | Restores the active request's bounded goal, checklist and plan instructions to model context after compaction. |
+| compaction checkpoint | `sessions/compactionCheckpoint.ts` | Restores the active request's bounded goal, todo list and plan instructions to model context after compaction. |
 | `RunRegistry`, `ActiveRun` | `sessions/registry.ts` | Live runs: `emit`, `requestApproval`, `requestAnswer(s)`, `onInterrupt`, `onSteer`, `finish`; `listen` for observers. |
 | run store functions | `sessions/runStore.ts` | `saveRun`, `updateRun`, `persistEvent`, `appendEvent`, `readEvents`, `markInterruptedRuns`, `runFamily`, `listRuns`. |
 | `RunRecord`, `RunEvent`, schemas | `sessions/contracts.ts` | The one contract every session shares. |
@@ -55,7 +55,7 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `message.completed`, `message.steered`, `tool.started`, `tool.completed`, `retry.started`,
   `retry.ended`, `compaction.started`, `compaction.ended`, `approval.requested`,
   `approval.resolved`, `question.requested`, `question.answered`, `extension.notice`,
-  `reaction.added`, `agent.message`, `checklist.updated`, `artifact.added`, `file.changed`, `usage.updated`,
+  `reaction.added`, `agent.message`, `todo.updated`, `artifact.added`, `file.changed`, `usage.updated`,
   `account.status`, `status.changed`, `failed`, `completed`. Each has a payload schema in
   `runEventPayloadSchemas`.
 - **Workspace root** (`RunRecord.workspaceRoot`) is the canonical root whose filesystem effects
@@ -76,9 +76,10 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   across alternatives; generation quality is guidance, not a schema guarantee. Old events remain
   valid without a data rewrite; readers with the old bounds must update before accepting larger
   sketches. `question.answered` and `QuestionAnswer` are unchanged.
-- **Checklist** (PROP-0006): `checklist.updated` carries the whole list the model last wrote with
-  `checklist_write`, `{ items: { text, status: pending | in_progress | completed }[] }`, at most 50
-  items. The latest event replaces every earlier one; `checklistOf(events)` reads it.
+- **Todo list** (PROP-0006, renamed by PROP-0045): `todo.updated` carries the whole list the model
+  last wrote with `todo_write`, `{ items: { text, status: pending | in_progress | completed }[] }`, at
+  most 50 items. The latest event replaces every earlier one; `todoOf(events)` reads it. The
+  pre-rename `checklist.updated` is still read so old runs keep their list, and is never written.
 - **`RunRecord`** fields are listed in `sessions/contracts.ts`. `mode`, `harness`, `sessionType`,
   `worktreeId`, `attachmentCount`, `exitCode`, `handoffId` and `trigger` belong to the
   application: stored and returned, and only `mode` and `trigger` are read.
@@ -97,12 +98,22 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `results` for the host (`sessions.spawnSubagent` is a compatibility alias). Child runs have
   `relation: 'subagent'` and `parentRunId`. Nesting defaults to 1, at most 3 (`subagentDepth`).
   The child's record carries `title`, the short name the parent gave it (PROP-0030).
+  `spawn_subagent { continue: <runId> }` (`subagents.spawn { continue }`) continues a child that
+  stopped before finishing as a new child run with `continueFrom`. It reopens the first link's
+  history folder and keeps the earlier child's session id, profile, title, account, variant version
+  and frozen capability set, which must still lie within the parent's; `agent` and `tools` are
+  refused with it, and the newest link of a chain is the one continued (ADR-0043). Children an
+  earlier reply left stopped are delivered before the next reply's first request, each with a
+  note that it can be continued; a stopped child that was continued is reported through its
+  continuation. Every run record carries the launch `model` and `effort`, superseded by the model
+  the session opened with.
 - **Agent profiles** (PROP-0029). `agent` names a profile: built-in (`worker`, `explorer`),
   `<data root>/agents/<name>.md`, `<project>/.xingular/agents/<name>.md`, or a c5 definition of
   the parent's variant, later sources winning (`agents/profiles.ts`). A profile narrows the
   child's tools and plugins (`agents/narrow.ts`), may choose its variant, model and effort, and
   frames it with a "Your role" section. The child's record carries `profile`; the spawn result
-  carries `agent` and any `unavailableTools`. A run that may spawn lists every profile in its
+  carries `agent` and any `unavailableTools`. `main` is reserved for the main agent's row: no
+  profile file or variant definition may take it. A run that may spawn lists every profile in its
   `subagents` section.
 - **Plan mode** (`plan: true`). The stable system prompt is unchanged. An attended plan run may
   include `ask_user` and `spawn_subagent` / `wait_subagents`, subject to the caller's frozen
@@ -122,15 +133,15 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   The reply ends with one `<proposed_plan>` block.
 - **Compaction checkpoint** (PROP-0033, ADR-0032). After compaction, an active run's model context
   receives a bounded, ephemeral checkpoint with the current user request and the latest validated
-  checklist or applicable plan instructions, when either is available to restore. It is re-added to
+  todo list or applicable plan instructions, when either is available to restore. It is re-added to
   each request while that run continues;
   its state is cleared when the run settles or the session branch changes. The message changes no
   tools, permissions, run events or native history. An interrupted run still uses the durable
-  checklist and normal continuation path.
+  todo list and normal continuation path.
 - **Continuation** (PROP-0007). `continuationOf(root, runId, sessionDir?)` (`runs.continuation`)
   says whether a stopped run can be continued: `resumable`, a `reason` when not (`not_found`,
   `active`, `completed`, `no_history`, `history_missing`), the exact native history to reopen,
-  the pinned account, variant version and capability set, the checklist, unanswered approvals and
+  the pinned account, variant version and capability set, the todo list, unanswered approvals and
   questions, the last tool and whether it finished, and subagents that did not finish.
   `SessionRunInput.continueFrom` starts a **new** run from it: it reopens that history, records
   `resumedFromRunId`, pins the same account, variant version and capability set (anything different
@@ -138,7 +149,8 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `continuation_unavailable`). If the earlier snapshot includes `ask_user`, an automatic or
   refinement-triggered continuation fails with `continuation_mismatch` rather than narrowing it.
   Empty text defaults to "Continue from where you stopped.", and the new run adds
-  a dynamic `continuation` section (order 26) saying where the earlier run stopped. The next run
+  a dynamic `continuation` section (order 26) saying where the earlier run stopped and that its
+  unfinished subagents can be continued with `spawn_subagent { continue }`. The next run
   without `continueFrom` withdraws it. `Recovery.interruptedRunIds` lists the runs `open` marked
   interrupted.
 - **Worktrees** (PROP-0016). When `run.worktreeId` names a worktree in the Harness registry
@@ -203,7 +215,9 @@ is approved but remains in progress; no completed cross-surface catalog is impli
   and never applied or relayed.
 - **INV-RUN-4** A restarted harness never restarts model work. On `open`, runs left active are
   marked `interrupted` unless another live process owns them (`owner.json`). Recovery of a
-  subagent needs the same account, caller, working folder and history branch. Continuing is always
+  subagent needs the same account, caller, working folder and history branch; the history branch
+  (owner marker and native history id), not the host's session id, ties a parent to an earlier
+  one. A stopped subagent is continued only by its parent, through `spawn_subagent { continue }`. Continuing is always
   a new run with `continueFrom`; it pins the earlier run's account, variant version and capability
   set, and the earlier run's record is never reopened. The application asks for it, or the earlier
   run's work-slice policy does when the reply stopped at its budget (PROP-0041); a run started
@@ -225,11 +239,15 @@ is approved but remains in progress; no completed cross-surface catalog is impli
   plan may include `ask_user`, `spawn_subagent` and `wait_subagents`, subject to the frozen caller
   capabilities; newly resolved normal, automatic, probe, improver and reflection runs omit
   `ask_user`. Plan-mode spawning requires a named profile whose effective explicit tool and plugin
-  allowlists qualify for read-only research. The child inherits plan mode and is narrowed to the
-  intersection of the parent's frozen capabilities, the profile and the plan research set; it has no
+  allowlists qualify for read-only research. The prompt lists only profiles whose intersection with
+  the parent's frozen tools and plugin contributions includes a research evidence tool. An omitted
+  `tools` override inherits that safe intersection; an explicit override can only narrow it. The
+  child inherits plan mode and is narrowed to the intersection of the parent's frozen capabilities,
+  the profile and the plan research set; it has no
   connectors, user questions, writes, commands or nested subagents. The plan run itself may run
-  Bash only in the OS-enforced read-only scope (PROP-0043, ADR-0038). The gate refuses unsafe calls
-  before approvals, and the service rechecks before launch. The terminal activates plan-eligible
+  Bash only in the OS-enforced read-only scope (PROP-0043, ADR-0038); research children cannot run
+  commands. Generic browser actions and connected-app calls remain unavailable in plan mode. The
+  gate refuses unsafe calls before approvals, and the service rechecks before launch. The terminal activates plan-eligible
   tools only for a plan request, then restores its normal set. Provider-cache effects of the tool-list
   difference are not assumed (page 04, `INV-PRM-8`).
 - **INV-RUN-9** Subagent results reach the parent at native turn boundaries, at most once
@@ -245,28 +263,39 @@ is approved but remains in progress; no completed cross-surface catalog is impli
   surface's visible transcript and selected references. It excludes hidden reasoning and attachment
   bytes, never reads the main native history, and never changes or steers the parent. Its own run
   record and events use the normal store contract (PROP-0019).
-- **INV-RUN-13** A reply is a bounded work slice (PROP-0041). The foundation defaults are 160 tool
-  calls, 40 minutes and 320 000 new tokens, whichever comes first. The token count covers new input,
-  cache writes and output, never the cached prefix: a few large reads pass any small cap before
-  useful work, so the cap is a safety net, not the bound. At the limit the guard ends the slice and
-  refuses the next tool call with a request for `checkpoint_write`; a handoff call is never refused,
-  including when it is the first call past the limit, and another tool ends the reply. A reply that ends this way is `interrupted` with terminal reason `slice_complete`, and one
-  the stall guard ends is `stalled`. The stall guard identifies a call by its name and every
-  argument, names a repeated call once and ends the reply on the next repeat, and counts afresh in
-  each reply, so a checklist a reply rewrites as its steps complete is not a repeat. A new run
-  continues it only up to the policy's slice cap, only
-  after a slice that changed a file, passed a check or recorded a finished item, and never after a
-  checkpoint that is `blocked`. A run may turn the guard off with `workSlice.enabled: false`, and a
-  launch may set `XINGULAR_WORK_SLICE=off` for every run in that process; with it off a reply has no
-  boundary — no checkpoint, no continuation, no stall notes — and ends only when the model stops or a
-  person interrupts.
+- **INV-RUN-13** A reply is a bounded work slice (PROP-0041). The foundation defaults are 320 tool
+  calls and 60 minutes, whichever comes first, with no new-token limit (PROP-0044). A token cap is
+  available with `workSlice.maxNewTokens`, counted on new input, cache writes and output and never on
+  the cached prefix: a few large reads pass any small cap before useful work, so the tool calls and
+  the clock are the bound and the token count is only a ceiling for whoever asks for one. At the
+  limit the guard refuses the next tool call. When `checkpoint_write` is available, it requests a
+  checkpoint and leaves handoff calls callable; otherwise a plan-research child must stop with a
+  concise partial research report, and the runner derives a checkpoint from run evidence. A
+  non-handoff tool call after the refusal ends the reply. A budget-ended reply is `interrupted` with
+  terminal reason `slice_complete`; a reply ended by a stall guard is `stalled`.
+  The targeted stall guard identifies calls by name and every argument; three identical calls cause
+  one refusal, and a repeated trigger ends the reply. A Bash check that fails twice is a trigger. The
+  guard counts only successful native `edit`/`write` results (`isError === false`) with a path toward
+  the four-edit per-path churn limit; the next edit is refused, and a repeated trigger ends the
+  reply. Failed or blocked edits do not count. A successful edit/write clears failed-check counts,
+  identical Bash-check repeat counts and the pending nudge, but leaves edit counts and other
+  repeated-call counts intact. A passing check clears edit counts. The general 25-call file/check
+  no-progress trigger is removed. `todo_write` is bookkeeping: it is exempt from repeated-call
+  detection and does not reset loop state, but counts toward the tool-call budget. Third-compaction
+  thrash detection remains. Plan-research children without `checkpoint_write` receive the configured
+  bound without a new capability and do not auto-continue. A new run continues it only up to the
+  policy's slice cap, only after a slice that changed a file, passed a check or recorded a finished
+  item, and never after a checkpoint that is `blocked`. A run may turn the guard off with
+  `workSlice.enabled: false`, and a launch may set `XINGULAR_WORK_SLICE=off` for every run in that
+  process; with it off a reply has no boundary — no checkpoint, no continuation, no stall notes — and
+  ends only when the model stops or a person interrupts.
 - **INV-RUN-14** A run event stream carries `checkpoint` (the handoff `checkpoint_write` records or
   the harness derives from the run's own evidence when the model wrote none) and `heartbeat`
   (steps, elapsed time, last tool, compactions, slice, and the call budget). A heartbeat older than
   five minutes while the owner process lives marks the run `interrupted` with reason `stalled`; a
   run that never emitted one keeps the 30-minute silence rule. The watchdog never restarts work.
 - **INV-RUN-12** A post-compaction checkpoint is a bounded context projection of the active request,
-  the latest validated checklist and applicable plan instructions. It is compiled by
+  the latest validated todo list and applicable plan instructions. It is compiled by
   `prompt/compile.ts`, supplied only to model requests in the active run, and never persists hidden
   reasoning or changes permissions, stable prompt text, native history or run-event schemas. Its
   in-memory state is cleared when the run settles or the active session branch changes
@@ -290,13 +319,15 @@ Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (super
 [ADR-0022](../decisions/ADR-0022-plan-only-question-tools.md),
 [ADR-0023](../decisions/ADR-0023-contextual-side-question-runs.md),
 [ADR-0026](../decisions/ADR-0026-contextual-question-wireframes.md),
-[ADR-0033](../decisions/ADR-0033-plan-mode-research-delegation.md).
+[ADR-0033](../decisions/ADR-0033-plan-mode-research-delegation.md),
+[ADR-0039](../decisions/ADR-0039-progress-aware-stall-guards.md).
 
 ## Native session names (PROP-0010)
 
 `session_name({ name: string })` adds or revises the current Pi session's name in embedded
-and terminal execution. The agent names meaningful work early and revises it when the overall
-objective changes, including a manual name. Agent-submitted names are imperative sentences
+and terminal execution. The agent calls it once before its first other tool call when a request
+needs tools or changes state, and revises it only when the overall objective changes, including a
+manual name. Agent-submitted names are imperative sentences
 of at most six whitespace-separated words; whitespace is normalized, and empty names,
 terminal escapes, non-whitespace controls and longer names fail without writing. Identical
 names are a no-op. Pi's native session-info history is the only storage; continuation and

package/docs/architecture/04-prompt.md

@@ -16,7 +16,7 @@ keeps provider caching effective across turns.
 | `render(env, pack)` → `string` | One string for a session that takes a single prompt. |
 | `sessionLaunch(env, caller, launch, historyFile, variant)` → `{ system, update, pack }` | SDK sessions: stable prefix plus an update with only the dynamic sections that changed since the last delivered snapshot. |
 | `deliveredSnapshot(sessionFile)` | Reads the last delivered snapshot on the active history branch; a compaction forces a fresh one. |
-| `renderCompactionCheckpoint` | Compiles a bounded current-request, checklist and plan-state message for post-compaction model requests. |
+| `renderCompactionCheckpoint` | Compiles a bounded current-request, todo list and plan-state message for post-compaction model requests. |
 | `saveForSession`, `copyToRun` | Terminal sessions keep the pack they started with and copy it to each run. |
 | `record`, `load`, `packPath` | The pack each run was given, at `runs/<id>/context.json`. |
 | `toolGroups`, `fit`, `clip` | The tool manifest by group; cutting text to a budget at a paragraph boundary. |
@@ -37,8 +37,9 @@ guidance in that section explains when delegation is worth its overhead, profile
 self-contained briefs, independent parallel work, and parent ownership of integration. Plan mode
 lists only effective profiles eligible for read-only research and requires a named profile; keeping
 this section dynamic leaves the stable system prompt unchanged across modes. The `tools`
-section has a Progress paragraph whenever `checklist_write` is available: it asks for a checklist
-early and kept current, then requests a final update before the reply. Only fully completed work is
+section has a Progress paragraph whenever `todo_write` is available: it asks for `todo_write` before
+the first other tool call when work has several steps, asks for the list to stay current, then
+requests a final update before the reply. Only fully completed work is
 marked completed; unfinished or blocked steps remain accurate (PROP-0006).
 
 The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
@@ -81,7 +82,7 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
   `references` is always resent when present, because it belongs to the current request.
 - After successful compaction, the foundation checkpoint extension detects the compacted context and
   uses `renderCompactionCheckpoint` to append one hidden, ephemeral context message to each model
-  request while the active run continues, when a checklist or applicable plan instructions exist.
+  request while the active run continues, when a todo list or applicable plan instructions exist.
   It contains only the current request and available state. It is not written to native history, and its state is
   discarded when the run settles or the branch changes.
 - The session appends the update as a hidden custom message and saves its snapshot in the
@@ -154,7 +155,8 @@ sections), `src/sessions/planMode.ts` (`plan` section).
 
 ## Session naming guidance (PROP-0010)
 
-The Session tool group describes `session_name` when available: name meaningful work early
-with an imperative sentence of at most six words, and revise when the objective changes.
+The Session tool group describes `session_name` when available: call it once before the first
+other tool call when a request needs tools or changes state, with an imperative sentence of at
+most six words, and revise only when the objective changes.
 This is fixed foundation guidance. The current name stays in native session metadata and
 the terminal snapshot; it is never interpolated into the stable system prompt.

package/docs/architecture/06-plugins-and-capabilities.md

@@ -134,13 +134,17 @@ metadata or availability:
 | Foundation | Accounts, sessions and run recording, prompt and variant validation, gate, plugin loading/trust/attachments, resource browser, server and terminal frameworks | Release-owned infrastructure and security contracts |
 | World | Web search/read tools, browser tools, page annotations | The isolated browser engine and network policy remain Foundation services |
 | Memory | Wiki, history and trajectory | Storage and run records remain Foundation-owned services |
-| Automation | Subagents, ask-user, checklist, lessons and refinement | Run lifecycle, capability narrowing and approval gate remain Foundation-owned |
+| Automation | Subagents, ask-user, todo, lessons and refinement | Run lifecycle, capability narrowing and approval gate remain Foundation-owned |
 | Integrations | Connected apps/MCP and Hub | Connector credentials and plugin installation remain behind Foundation services |
 | Operations | Doctor, worktrees and usage | Diagnostics, repository operations and usage analytics remain Harness-managed services |
 
-## Terminal resource inspection
+## Terminal plugin and resource inspection
 
-The unified browser joins saved plugin/contribution metadata with actual session skills and tool
-registration. A saved on/off state does not prove a resource loaded; origins and owners distinguish
-same-name resources. Protected install/remove, settings, attachment and trust actions call the
-existing services. No second discovery or enablement mechanism is introduced (PROP-0013).
+The broad `/harness` browser joins saved plugin/contribution metadata with actual session skills and
+tool registration. A saved on/off state does not prove a resource loaded; origins and owners
+distinguish same-name resources. `/plugins` is a focused local manager with Plugins, Trust and
+Packages tabs. It uses the existing plugin services for switching, trust, settings, package install,
+update and removal. `/hub` is a distinct Community catalog surface; it does not load code or add a
+second loader. Hub-owned package removal through `plugins.remove` delegates to Hub so the exact
+receipt and its resources stay consistent. No second discovery or enablement mechanism is
+introduced (PROP-0013, PROP-0047).

package/docs/architecture/07-tools-and-gate.md

@@ -16,7 +16,7 @@ person without letting remembered per-tool grants widen that boundary.
 | `dispatch` | `tools/dispatch.ts` | One entry point for every History, Wiki and skill call, from a Pi tool, the server or a terminal. |
 | `harnessTools` | `tools/harnessTools.ts` | The definitions as `ToolSpec`s for one session. |
 | `askUserTool` (`ask_user`) | `tools/askUser.ts` | Stops an attended plan run and asks up to five related questions with choices and concise 1–2 word labels; absent from newly resolved normal runs. |
-| `checklistTool` (`checklist_write`) | `tools/checklist.ts` | Writes the run's whole checklist as a `checklist.updated` event (PROP-0006). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `checklist` telemetry call. The prompt's Progress group asks the model to keep it current and write one final update before replying; unfinished work is not automatically marked complete. |
+| `todoTool` (`todo_write`) | `tools/todo.ts` | Writes the run's whole todo list as a `todo.updated` event (PROP-0006, renamed by PROP-0045). Read-only for the gate, so plan mode allows it. Terminal sessions register the same tool; it reaches the run through the `todo` telemetry call. The prompt's Progress group asks the model to call it before the first other tool call when work has several steps, keep it current, and write one final update before replying; unfinished work is not automatically marked complete. The pre-rename `checklist.updated` event is still read, never written. |
 | `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
 | `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
@@ -26,7 +26,7 @@ person without letting remembered per-tool grants widen that boundary.
 Harness tools: `get_capabilities` (read-only current-run discovery), `history_search`, `history_read`,
 `trajectory_search`, `trajectory_read`, `wiki_search`, `wiki_read`, `wiki_list`, `wiki_write`
 (not in the default set), `skill_load`, `ask_user` (attended plan runs and pinned continuations only),
-`checklist_write`. Broker:
+`todo_write`. Broker:
 `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
@@ -76,6 +76,18 @@ never replayed after partial effects. Full Permission is the explicit eligible-r
 Unsupported or unavailable sandbox enforcement fails closed. A side-question run has an empty
 capability set and no tools (PROP-0019).
 
+**Windows** has no write-boundary sandbox the harness can use, so the Bash tool treats every
+command there as an outside request: a human-only one-call approval (or an eligible Full
+Permission answer), then the command runs once without a sandbox. Plan-mode Bash is refused,
+because a read-only scope cannot be enforced. Commands run in Git Bash when it is installed
+(`%ProgramFiles%\Git\bin\bash.exe`, then `bash.exe` on `PATH`, never the WSL launcher in
+`System32`), otherwise in PowerShell (`pwsh.exe`, then Windows PowerShell). The tool keeps the name
+`bash`; its description names the shell. Native `edit` and `write` run their atomic helper with
+Node directly, without an OS guard: the target is still canonicalized, authorized, revalidated and
+replaced by rename, and outside targets still need their approval, but a junction or symlink swap
+between the check and the rename is not prevented
+([ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md)).
+
 ## The gate, per call
 
 For native `edit` and `write`, the canonical target check is added to policy scope before approval;
@@ -96,6 +108,7 @@ policy.authorize(call) throws           ─► refuse
 outside native file target              ─► human-only one-call approval; eligible Full Permission may answer
 Bash workspace scope                    ─► hard-link scan, OS sandbox, run once
 Bash outside scope                      ─► pre-execution human-only approval, then run once unconfined
+Bash on Windows (no sandbox)            ─► as outside scope; plan-mode Bash refused
 trigger probe, improver, reflection or unattended ─► refuse anything requiring a person
 run.requestApproval(...)                ─► standing approvals may answer where eligible, else the person
   denied                                ─► refuse; never replay a command
@@ -131,6 +144,8 @@ the switch and global tools.
   Full Permission switch can answer automatically under its existing restrictions. In plan mode, Bash
   runs only in the read-only scope (PROP-0043): no writes but a discarded temp folder, no network,
   no signals outside the sandbox, no macOS mach services; Full Permission and `outside` never apply.
+  On Windows, which has no sandbox, every Bash call takes the `outside` path and plan-mode Bash is
+  refused (ADR-0042).
 - **INV-GATE-4** Refinement runs (`probe`, `improver`) never ask a person; what would need one is
   refused, never queued (`INV-REF-4`).
 - **INV-GATE-5** SDK tools are registered only if their names are in the run's frozen capability
@@ -155,6 +170,7 @@ the switch and global tools.
   same choice as `!outside <command>`. Full Permission is the only standing boundary bypass and
   remains subject to host policy, authorization, read-only, plan, unattended, probe, improver and
   reflection restrictions. The rule does not protect against a peer process running as the same user.
+  On Windows the atomic replacement runs without an OS-enforced scope (ADR-0042).
 
 ## Data
 
@@ -164,14 +180,17 @@ the switch and global tools.
 
 `src/tools/*.ts`, `src/web/*.ts`, `src/sessions/sessions.ts`, `src/sessions/runner.ts`,
 `src/sessions/workspaceBoundary.ts`, `src/sessions/initialBash.ts`, `src/core/workspaceBashTool.ts`,
-`src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`, `src/sessions/approvals.ts`,
-`src/sessions/policy.ts`. Decision: [ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md).
+`src/core/shell.ts`, `src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`,
+`src/sessions/approvals.ts`, `src/sessions/policy.ts`. Decisions:
+[ADR-0036](../decisions/ADR-0036-workspace-write-operation-boundary.md),
+[ADR-0042](../decisions/ADR-0042-windows-shell-without-sandbox.md).
 
 ## Session naming (PROP-0010)
 
 `session_name` (`tools/sessionName.ts`) binds to the current native session. It maintains
 only Pi session metadata and is explicitly plan-safe, while still subject to capability
-selection and the host policy. The terminal registers the same definition through its Pi
+selection and the host policy. The prompt asks for it once before the first other tool call when
+a request needs tools or changes state. The terminal registers the same definition through its Pi
 bridge; standalone policy permits naming without approval. See page 02 for validation and
 persistence. It is a foundation tool, not mutable variant data.
 
@@ -181,3 +200,10 @@ persistence. It is a foundation tool, not mutable variant data.
 intersect current capabilities, and execute tool calls through the existing gate. Calls that
 require an additional per-call approval report blocked; batch diagnostic consent does not grant
 standing permission. No raw tool inputs, results, or screenshots enter diagnostic findings.
+
+A live check may also run one command the harness wrote itself, when the capability it diagnoses is
+a native Pi tool rather than a harness tool: the shell check runs `printf` through the same
+workspace root, hard-link scan and write-boundary sandbox as a Bash call, and reports only the exit
+status. It passes the gate first, and a diagnostic never widens the boundary — Full Permission,
+an outside-workspace request and a host bypass are all refused for it — so a boundary that stops
+the command before the shell starts is reported as blocked with the boundary's own reason.

package/docs/architecture/09-accounts-and-connectors.md

@@ -38,7 +38,10 @@ skills, prompts, rules and Pi packages.
 - **`apps.expose(tools)`** offers the application's own tools through the broker, which is how a
   terminal session reaches them.
 - **Hub.** `hub.list`, `get`, `preview`, `install`, `uninstall`, `readDocument`. Pi packages need
-  an exact npm version or a full Git commit. Documents are saved as inert JSON.
+  an exact npm version or a full Git commit. Documents are saved as inert JSON. The `/hub` Catalog
+  view filters Community entries for display; the service and other callers retain the full catalog.
+  Installed shows receipts from every channel. On page entry, cached/bundled content is shown before
+  a remote refresh, and origin, refresh time and failure status remain visible (PROP-0047).
 
 ## Invariants
 
@@ -62,7 +65,10 @@ skills, prompts, rules and Pi packages.
   nothing of it is stored.
 - **INV-MCP-4** Hub installation grants no attachment, trust, credential or permission. Writes
   are serialized; existing registry files are never overwritten; uninstall removes only the exact
-  receipt's resources and revokes its attachment choices.
+  receipt's resources and revokes its attachment choices. Every removal route for a Hub-owned Pi
+  package, including `plugins.remove`, goes through Hub's receipt-owning uninstall operation. A
+  floating plugin-package update must not change a Hub-owned package; replacement uses an explicit
+  exact catalog version (PROP-0047).
 
 ## Data
 

package/docs/architecture/10-server-protocol.md

@@ -40,7 +40,9 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   `plugins.describe`.
 - `refine.start` takes `{ task, k?, mode?, improver?, executor?, baseVersion?, retainWorkspaces?, id? }`;
   `refine.candidates` returns each execution with `workspace: string | null` (page 05, PROP-0002, PROP-0003).
-- `runs.checklist { runId }` returns the run's latest checklist, `[]` when it wrote none (PROP-0006).
+- `runs.todo { runId }` returns the run's latest todo list, `[]` when it wrote none (PROP-0006,
+  renamed by PROP-0045). `runs.checklist` is the deprecated pre-rename alias.
+- `runs.continuation` returns `todo`; `checklist` remains a deprecated mirror of it for one release.
 - Run records include optional nullable `workspaceRoot`, the canonical root whose files a run may
   modify by default (page 02). New Harness runs set it; older records may omit it. Hosts must
   tolerate the additive field and must not nominate or widen the root.
@@ -49,15 +51,18 @@ harness → host   { v: 1, id, call, params }          host → harness   { v: 1
   and refuses an existing file; `agents.remove { cwd?, name, scope }` deletes a person's own file.
   `subagents.spawn` takes `agent` as a profile name and returns `agent` and `unavailableTools`
   (PROP-0029). It takes an optional `title` (at most six words); without one the child's title is
-  the first line of its brief (PROP-0030).
+  the first line of its brief (PROP-0030). With `continue: <runId>` it continues a stopped child of
+  this conversation instead (no `agent` or `tools`; `brief` and `title` optional) and returns
+  `continued`, the run it continued (ADR-0043).
 - `runs.continuation { runId, sessionDir? }` returns a `Continuation` (its `checkpoint` is the last
   work-slice handoff), and `sessions.run` accepts `continueFrom` (page 02, PROP-0007) and `workSlice`
   (PROP-0041). `harness.status` reports `recovery.interruptedRunIds`.
 - `workSlice { enabled?, maxToolCalls?, maxMinutes?, maxNewTokens?, maxSlices?, continue? }` on
-  `sessions.run` bounds that reply; absent uses 160 calls, 40 minutes, 320 000 new tokens, 8 slices and
-  automatic continuation. A token cap counts new input, cache writes and output, never the cached
-  prefix. `enabled: false` turns the guard off for that run; `XINGULAR_WORK_SLICE=off` in the
-  launching process turns it off for every run in it, and nothing is persisted. The policy is
+  `sessions.run` bounds that reply; absent uses 320 calls, 60 minutes, no new-token cap, 8 slices and
+  automatic continuation. A token cap, when set, counts new input, cache writes and output, never the
+  cached prefix (PROP-0044). `enabled: false` turns the guard off for that run;
+  `XINGULAR_WORK_SLICE=off` in the launching process turns it off for every run in it, and nothing is
+  persisted. The policy is
   carried into the continuation. A value outside its range is refused with `invalid_request` before
   the run record is written.
 - The run-event stream adds `checkpoint` (the bounded handoff) and `heartbeat` (steps, elapsed time,
@@ -185,9 +190,11 @@ from preparation, never from the request.
 | `terminal.usage.summary\|limits` | `{ scope, period, timezoneOffsetMinutes }` / `{ refresh? }` | Existing usage service result, scoped to this terminal's account and project |
 | `terminal.usage.headers` | `{ provider, status, headers }` | `{}`; only limit-bearing headers, throttled, stored as an account limit reading |
 
-Protected `plugins.install { source }` and `plugins.remove { pluginId }` delegate to the package
-service. Optional matching callbacks extend `PluginControl`; hosts without them receive a clear
-unsupported-operation error. No protocol version or persisted schema changes.
+Protected `plugins.install { source }`, `plugins.update { pluginId? }` and
+`plugins.remove { pluginId }` delegate to the package service. Removing a Hub-owned package routes
+through Hub's receipt-aware uninstall; a floating update refuses Hub-owned packages, while an
+update-all skips them. Optional matching callbacks extend `PluginControl`; hosts without them
+receive a clear unsupported-operation error. No protocol version or persisted schema changes.
 
 ## Worktrees (PROP-0016)
 

package/docs/architecture/11-terminal.md

@@ -43,7 +43,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
   per-tool grants do not widen it, and command output never triggers approval or replay.
 - The terminal compiles its prompt once (`compile` + `render`) and keeps that pack; each run
   records a copy (page 04). The shared compaction checkpoint extension reintroduces the active
-  request and latest checklist into post-compaction model context until the run settles.
+  request and latest todo list into post-compaction model context until the run settles.
 - Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
   shared tool alongside its read-only set and restores the normal set on success, failure or
   interruption. There is no terminal-only question alias (PROP-0040).
@@ -156,19 +156,29 @@ on close. No command text is sent to the conversation model. See [Doctor](../doc
 
 ## Resource browser (PROP-0013)
 
-`/harness` owns shared navigation for Foundation, Variant, Skills, Plugins, Connections, Tools
-and Library. `/skills`, `/plugins`, `/connections` (`/mcp`), `/tools`, `/hub` and `/components`
-are shortcuts into that browser. Current availability comes from the live resource loader and
-active tool registry, independently of saved configuration and the latest variant head.
+`/harness` owns broad navigation for Foundation, Variant, Skills, Plugins, Connections, Tools and
+Library. `/skills`, `/connections` (`/mcp`), `/tools` and `/components` are shortcuts into that
+browser. `/plugins` opens the focused local plugin manager (Plugins, Trust and Packages tabs); `/hub`
+opens the separate Community catalog (Catalog and Installed tabs). The Hub Catalog shows Community
+entries across supported types; Installed retains receipts from every channel with its channel
+visible. Registry/document entries offer bounded payload Preview; Pi packages do not. Current
+availability in `/harness` comes from the live resource loader and active tool registry,
+independently of saved configuration and the latest variant head.
 
 Every `terminal.browser.*` call requires the private control key, including bounded resource
-inspection, local imports, connection management and browser settings. Package install/remove use protected
-`plugins.install|remove`. These are adapters to the existing services, not another loader,
-attachment store, gate or secret store. Browsing neither executes plugin code nor connects MCP.
+inspection, local imports, connection management and browser settings. Direct plugin package
+install/update/remove and attachment/trust/settings actions use protected `plugins.*`; Hub catalog
+list/install/uninstall use protected `hub.*`. Hub-owned package removal keeps the receipt and
+resource ownership in the Hub service. These routes are adapters to the existing services, not
+another loader, attachment store, gate or secret store. Browsing neither executes plugin code nor
+connects MCP.
 The browser uses the full terminal with persistent section tabs (PROP-0014); wide screens keep
 inventory beside details, actions and content, while compact screens keep inline details under
-the same tabs. Other command pages remain centered except `/settings` and `/accounts`, which use
-full-screen page layouts. Accounts keeps Accounts/Pools tabs, search and account-service operations.
+the same tabs. The separate `/plugins` and `/hub` pages also use full-screen layouts with persistent
+section tabs, responsive inventory/details panes and their existing protected operations. Other
+command pages remain centered except `/settings`, `/accounts`, `/plugins` and `/hub`, which use
+full-screen page layouts.
+Accounts keeps Accounts/Pools tabs, search and account-service operations.
 Wide terminals show selected-account details beside the list; Enter or a primary click opens grouped
 actions in that inspector. Compact terminals replace the list with a full-page account detail view
 and its grouped actions. Enter opens the selected account; Escape returns to the list while
@@ -262,20 +272,24 @@ The annotate pane (PROP-0018) is a full-screen page beside the window being insp
 - **Other keys:** `s` sends the queue as one run of this session, confirming notes that came from a page-world script first; `x` takes a note out of the queue; `t` picks a window.
 - **Routes:** `terminal.annotations.target|attach|windows|selectWindow|inspect|stopInspect|next|queue|dequeue|confirm|send` act only on this terminal's session and need the control key.
 
-## Checklist (PROP-0006, PAR-001)
+## Todo list (PROP-0006, PROP-0045, PAR-001)
 
-Terminal sessions register the shared `checklist_write` tool. The extension validates each list
-with the same tool code and sends it as `checklist` telemetry; the controller emits it as
-`checklist.updated` on the active run, so `runs.checklist` and continuation read terminal runs too.
-The gate treats it as read-only, plan mode allows it, and terminal children inherit it. The
-transcript shows each write as a checklist block (`✓` done, `●` in progress (warning yellow), `○` pending) under a
-`Checklist · n of m done` header instead of a tool row; a failed or malformed call stays a tool row.
+Terminal sessions register the shared `todo_write` tool. The extension validates each list with
+the same tool code and sends it as `todo` telemetry; the controller emits it as `todo.updated` on the
+active run, so `runs.todo` and continuation read terminal runs too. The gate treats it as read-only,
+plan mode allows it, and terminal children inherit it. The transcript shows each write as a todo
+block (`✓` done, `●` in progress (warning yellow), `○` pending) under a `Todo · n of m done` header
+instead of a tool row; a failed or malformed call stays a tool row. `/todo` reads the latest
+non-side-question run of this terminal's native session and appends the same card as a snapshot,
+without a model request; an empty list is a one-line notice. `/checklist` remains its alias for one
+release.
 
 ## Work-slice checkpoint (PROP-0041)
 
-Terminal replies carry the same work-slice guard as structured runs: 160 tool calls, 40 minutes or
-320 000 new tokens, then a refusal that asks for `checkpoint_write`. The extension registers the shared
-tool and sends it as `checkpoint` telemetry, which the controller records as `checkpoint` on the
+Terminal replies carry the same work-slice guard as structured runs: 320 tool calls or 60 minutes,
+with no new-token limit by default (PROP-0044), then a refusal that asks for `checkpoint_write`. The
+extension registers the shared tool and sends it as `checkpoint` telemetry, which the controller
+records as `checkpoint` on the
 active run, so an App reading the same session sees the handoff. Terminal replies are not
 auto-continued: at the boundary the person decides, which is what the terminal's own turn model
 already does. The run record says `interrupted` with terminal reason `slice_complete` (or `stalled`
@@ -288,13 +302,13 @@ boundary at all; it is not persisted, so the next launch without it restores the
 During an active parent run, the terminal polls a private read-only monitor once per second. It
 projects the flat set of child and nested-child runs with task, status, elapsed time, the latest
 tool name, the child's agent profile (name and colour, PROP-0029), the title the parent gave it
-(PROP-0030), counts from the child's own checklist, the pinned account label, effective model and
+(PROP-0030), counts from the child's own todo list, the pinned account label, effective model and
 effort, and cumulative usage totals. Model and effort come from the volatile launch selection; the
 latest provider-reported model supersedes the launch model when usage is available. Usage is an
 explicit projection of token, cache, cost, request-count and context-window totals. Per-request
 payloads and reasoning summaries do not enter the monitor. The child's own `session_name` is not
 projected; it names the child's session, not its row. Tool summaries, other arguments, output and
-checklist item text never enter the monitor. The latest completed tool name remains visible across
+todo item text never enter the monitor. The latest completed tool name remains visible across
 one-second snapshots until new tool or response activity replaces it. The monitor exposes no
 controls to steer or stop children.
 
@@ -302,15 +316,26 @@ The live rows sit under the status line, after one blank row, with no heading. E
 order: the status mark (`○` queued, a running row that shows the working spinner's frame in the profile's colour (warning for a copy of the parent), `●` waiting in the accent,
 `✓` done, `✕` failed, `!` stopped), the profile name in its colour (`subagent`, muted, for a copy
 of the parent), the title the parent gave the child (PROP-0030), and `n of m tasks` when the child
-keeps a checklist. Active rows come first, at most three, then `+N more · /subagents`; a narrow
+keeps a todo list. Active rows come first, at most three, then `+N more · /subagents`; a narrow
 terminal cuts the title first. `/subagents` opens the searchable full roster, with a colored
 profile and normal-color title on its first line, then muted account, model, effort and usage
 metadata on its second line. One blank row separates each two-line entry. Narrow rows truncate this
 lower-priority summary without hiding the title.
 At parent settlement, the terminal makes a final monitor read and keeps the latest parent's rows
-visible until the next parent run starts. The projection remains volatile and read-only, is scoped to
-the latest parent run in the terminal session, and is cleared on session replacement or terminal
-disposal. It is not a persisted event or public server method.
+visible until the next parent run starts.
+
+The monitor also projects the parent run itself as a `main` row (profile `main`, a reserved name,
+in the theme's primary colour) with the same account, model, effort, usage, activity and todo
+fields. The `/subagents` page pins it first and counts only children in its header; the rows under
+the status line omit it, since the status line already describes the main agent.
+
+Every turn marks its run on the native branch (`xingular-subagent-owner`), and `ready` sends those
+owners. When a conversation opens or is switched to with no run active, the monitor is rebuilt from
+the branch's latest top-level run in this folder and its descendants, by folding their saved events
+with their final status. Runs a stopped process left active were already marked `interrupted`.
+The rows show under the status line and on the page until the next parent run starts (ADR-0043).
+The projection remains read-only and scoped to one parent run; a switch to a conversation with no
+such run clears it, as does terminal disposal. It is not a persisted event or public server method.
 
 ## Agent profiles (PROP-0029)