@xingular/harness 1.2.0 → 1.3.1-unstable.1

package/docs/README.md

@@ -17,6 +17,9 @@ change the binding architecture or describe implemented capabilities.
 
 | ID | Record | Type | Status | Related |
 |---|---|---|---|---|
+| ADR-0047 | [A link a person clicks opens with the system's handler](decisions/ADR-0047-links-open-with-the-os-handler.md) | Decision | Implemented in the Harness, the terminal and the App; acceptance not certified | [10 Server protocol](architecture/10-server-protocol.md), [parity register](parity.md) |
+| ADR-0046 | [Hash-bound plugin proposal review](decisions/ADR-0046-hash-bound-plugin-proposals.md) | Decision | Harness API and model proposal tool implemented; review surfaces pending | [06 Plugins](architecture/06-plugins-and-capabilities.md), [parity register](parity.md) |
+| ADR-0045 | [Release-owned plugin-authoring skill](decisions/ADR-0045-default-plugin-authoring-skill.md) | Decision | Implemented as an on-demand resource | [06 Plugins](architecture/06-plugins-and-capabilities.md) |
 | PROP-0026 | [Connect structural sketch lines in the terminal display](architecture/proposals/PROP-0026-connected-sketch-display.md) | Proposal | Implemented; working tree and isolated fixtures verified | [ADR-0027](decisions/ADR-0027-connected-sketch-display.md), [11 Terminal](architecture/11-terminal.md), [parity register](parity.md) |
 | ADR-0027 | [Project structural ASCII sketch lines into connected terminal borders](decisions/ADR-0027-connected-sketch-display.md) | Decision | Accepted; working tree and isolated fixtures verified | [PROP-0026](architecture/proposals/PROP-0026-connected-sketch-display.md), [14 Surfaces and parity](architecture/14-surfaces-and-parity.md) |
 | FW-0001 | [Agent Modes, starting with Router Agent Mode](future-work.md#fw-0001-agent-modes-starting-with-router-agent-mode) | Future work | Candidate; requires architecture proposal before implementation | [Architecture glossary](architecture/README.md#glossary), [Feature guide](features/README.md#planned-agent-modes) |

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,24 @@ 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
+  the parent's variant, later sources winning (`agents/profiles.ts`). A switched-on package's
+  profiles (page 06) then fill names nobody else took; the run resolves them once at start into
+  `packageProfiles`, and its children resolve their profiles from that list. 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 +135,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 +151,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 +217,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 +241,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 +265,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,16 +321,22 @@ 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 normally 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. When a top-level attended session starts unnamed, the harness also
+derives a provisional name from a substantive first request before the first model request;
+greetings, thanks and short conversational replies stay unnamed. The model may revise the
+provisional 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
 reopen preserve it. Each child names only itself. There is no additional model request or
-run-event schema. The normal capability selection and host gate apply; `harnessTools: false`
+run-event schema. The normal capability selection and host gate apply; a refused or failed
+provisional name leaves the session unnamed and never fails the run. `harnessTools: false`
 omits the tool. Plan mode permits it as session metadata maintenance.

package/docs/architecture/03-variants.md

@@ -60,9 +60,7 @@ The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness
 - **INV-FND-2** A variant changes only by committing a new validated version (`commit` →
   `validate`, `INV-VAR-2`), and a refinement moves a head only when a person adopts
   (`INV-REF-6`). There is no other door.
-- **INV-VAR-1** A variant is the only thing in the harness that shapes an agent's
-  instructions. The application adds its own sections through `Launch` (page 01); no other
-  harness code adds instruction text.
+- **INV-VAR-1** Variant instructions are versioned per scope. The application adds its own sections through `Launch` (page 01). The release-owned `plugin-authoring` skill is also available on demand in structured and terminal sessions, including existing variants; its body is not always-on. A variant skill with the same name takes precedence. It is shipped as a package resource and does not mutate pinned versions.
 - **INV-VAR-2** Every saved version is validated (`commit` → `validate`). An invalid variant is
   refused with every problem listed.
 - **INV-VAR-3** A version is never edited. A change is a new version; `restore` moves the head

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. |
@@ -28,8 +28,7 @@ A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
 
 ## Section order
 
-`SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `guardrails` 40, `memory` 45, `references`
-50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
+`SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `sessionState` 30, `guardrails` 40, `memory` 45, `references` 50, `subagents` 64, `scripts` 66, `wiki` 80, `tools` 90, `reporting` 95. Application sections
 sit among them by their `order`; plan mode uses `plan` at 25. Ties keep insertion order.
 When a run may spawn, the dynamic `subagents` section lists every profile it can start (built-in,
 global, project and variant c5 names) and replaces the variant's own list (PROP-0029). Normal-mode
@@ -37,10 +36,19 @@ 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).
 
+`session-state` is a built-in dynamic section at order 30 when a top-level run supplies it. It
+names the current session or says “unnamed”, shows this run's todo (empty at the start) and a
+previous run's list as context, and says whether this is the first turn. It describes only tools
+in the frozen set: the name line appears only with `session_name`, and the todo line only with
+`todo_write`. It never enters the stable prefix. Structured sessions deliver it through
+`sessionLaunch` and the changed-section rule; the terminal appends the same text as a request-time
+custom message.
+
 The fixed `harness-identity` section says `You are an AI agent running in <productName>.` and uses
 `env.productName` (default `Xingular Agent`). `Launch.standard: { cwd, project?: { name } | null }` requests shared role and working-folder
 sections from `prompt/standard.ts`; the compiler supplies common connections, file and annotation
@@ -81,7 +89,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
@@ -113,8 +121,8 @@ file SecretStore with a host Keychain. See [parity](../parity.md).
   instructions. SDK sessions use `sessionLaunch`; terminal sessions use `compile` + `render`.
 - **INV-PRM-2** The system prompt holds only stable text: identity, role, the variant's sections, the
   harness's reporting guidance, tool guidance and the tool manifest. Changing state never enters it.
-- **INV-PRM-3** `references`, `wiki`, and every section the application marks `dynamic` are
-  delivered as context updates in native history, never in the system prompt.
+- **INV-PRM-3** `session-state`, `references`, `wiki`, and every section the application marks
+  `dynamic` are delivered as context updates in native history, never in the system prompt.
 - **INV-PRM-4** An update carries only changed dynamic sections, so an unchanged turn appends
   nothing. A compaction on the active branch forces the full snapshot again.
 - **INV-PRM-5** The pack only describes tools the caller can call (the frozen capability set).
@@ -149,12 +157,15 @@ what this page states is binding. Adopting parts of that draft is an architectur
 ## Source map
 
 `src/prompt/compile.ts`, `src/sessions/sessions.ts` (calls `sessionLaunch`),
-`src/terminal/terminals.ts` (calls `compile` + `render`), `src/variant/materialise.ts` (variant
-sections), `src/sessions/planMode.ts` (`plan` section).
+`src/terminal/terminals.ts` (calls `compile` + `render`), `src/sessions/sessionState.ts`
+(the native name reader and state shape), `src/variant/materialise.ts` (variant 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.
+the terminal snapshot; it may appear in the request-scoped `session-state` update, but it is never
+interpolated into the stable system prompt.

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

@@ -3,7 +3,7 @@
 ## Purpose
 
 A *plugin* is a bundle with a title, a description and contributions: instructions, skills,
-commands, tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it is;
+commands, subagent profiles (`agent`), tools, connections, code (a Pi extension) and themes. A Pi package is a plugin as it is;
 so are the harness's own parts, the application's parts, a person's registry, the folder every
 account shares, and what a working folder brings. This part decides what a session loads, who has
 what switched on, which code may run, and what reaches one caller. A *capability set* is the
@@ -22,6 +22,7 @@ callable result for one run.
 | `FIRST_PARTY_PLUGINS` | `plugins/firstParty.ts` | `output-trim`, `budget-guard`: inline extensions shipped switched off. `lessons`: switched off; its contribution turns on reflection after a run (page 08, PROP-0008) and loads no Pi code. |
 | `Hooks` | `plugins/hooks.ts` | Runs a package's hooks file after a write. |
 | install / trust | `plugins/install.ts`, `plugins/trust.ts` | Install through Pi's package manager with scripts off; trust code by hash. |
+| proposals | `plugins/proposals.ts` | Validate and store inert proposals; preview, reject or accept a hash-bound review. |
 | inventory / api | `plugins/inventory.ts`, `plugins/api.ts` | `plugins.list`, `plugins.inventory`, attach, trust. |
 | capability api | `capabilities/api.ts`, `capabilities/types.ts` | `list`, `resolve`, `toolIntersection`, `inventory`, `attach`. |
 | run snapshot | `capabilities/runSnapshot.ts` | `freezeRun`, `loadRun`, `capabilitySet`. |
@@ -29,8 +30,9 @@ callable result for one run.
 ## Contracts
 
 - **Loading.** `Plugins.loading({ cwd, agentDir, caller, contributions, install? })` returns
-  `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `builtins` (legacy shape; no Pi CLI built-ins selected), `hooks`,
-  `found`, `detached`, `projectCode`, `packageCode`. A session opens Pi with its own discovery off
+  `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `profilePaths`, `builtins` (legacy shape; no Pi CLI built-ins selected), `hooks`,
+  `found`, `detached`, `projectCode`, `packageCode`. `profilePaths` are read by the harness for
+  subagent profiles (page 02); Pi is never given them. A session opens Pi with its own discovery off
   and only these paths; a terminal receives them as `--extension`, `--skill`,
   `--prompt-template` and `--theme` after `--no-extensions --no-skills --no-prompt-templates
   --no-themes`. Pi still reads `AGENTS.md` and `SYSTEM.md` itself.
@@ -45,10 +47,39 @@ callable result for one run.
 - **Attachments.** `config/plugin-attachments.json` holds `global`, `agents`, `projects` (each
   `{ on, off }`) and `settings` per plugin. The narrowest scope that says something wins: agent,
   then project, then everywhere. With no entry an item keeps its default.
-- **Package metadata.** A Pi package may declare `"harness": { "extends": [...], "hooks": "./hooks.mjs", "commandPrefix": "my-tools" }`.
+- **Package metadata.** A Pi package may declare `"harness": { "extends": [...], "hooks": "./hooks.mjs", "commandPrefix": "my-tools", "agents": "./agents" }`.
+  A package without a `package.json` name is named, described and versioned by the first of
+  `plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, so an agent plugin
+  written for other harnesses installs as it is.
+- **Package subagent profiles.** An installed package's agents folder (`agents/` unless
+  `harness.agents` names another) brings each Markdown file whose frontmatter has a `name` and a
+  `description` as an `agent` contribution (at most 50). It is text: it needs no trust and follows
+  its switch like a skill. The profile is named by its frontmatter, not its file. Fields only other
+  harnesses understand are dropped (`agents/profiles.ts`, `parsePackageProfile`): their tool names
+  are translated (`Read`→`read`, `Glob`→`find`, …), a model without a provider is left to the
+  parent, `plugins` and `variant` are never taken, and a tool list of which nothing translates
+  keeps the child read-only. A package profile never replaces a built-in, person's, project's or
+  variant's profile of the same name; the listing reports it as a problem instead.
   `commandPrefix` is optional; in the terminal, commands otherwise use a normalized package name as
   their owner prefix. Prefixes use lowercase letters, digits and hyphens, starting with a letter;
   `plugin` and `skill` are reserved. See page 11 for the command route and collision rules.
+- **Plugin authoring.** `plugin_propose` creates a pending proposal, not an installation. The
+  release-owned `plugin-authoring` skill is available on demand in structured and terminal sessions;
+  a pinned variant's skill of the same name wins. It adds no trust or permission
+  ([ADR-0045](../decisions/ADR-0045-default-plugin-authoring-skill.md)).
+- **Proposal review.** `plugins/proposals.ts` validates a lowercase package name, nonempty description,
+  and 1–100 UTF-8 text files (256 KiB each, 1 MiB total). It accepts `README.md`, extensions
+  (`.ts`, `.js`, `.mjs`), Markdown skills, prompts and agents, and JSON themes in their respective
+  directories; paths must be safe and cannot contain `.git` or `node_modules`. A
+  `skills/<name>/SKILL.md` needs matching name and nonempty description frontmatter. The Harness
+  generates `package.json`; it is not supplied by the proposal. Preview revalidates the stored data
+  and computes SHA-256 over name, description, generated manifest and sorted file entries. Accept
+  and reject require the current preview hash and pending status; stale reviews fail.
+  Acceptance rechecks after adoption and listing, refuses an existing package name or already-trusted
+  identical package code, stages and publishes under `<data root>/plugins/<name>`, clears old
+  attachment decisions for that package and explicitly switches it off globally. It grants no code
+  trust or permission; reject retains the proposal as rejected. These are trusted caller review
+  operations, not model tools. See [ADR-0046](../decisions/ADR-0046-hash-bound-plugin-proposals.md).
 - **Hooks.** A package declares `"harness": { "extends": [...], "hooks": "./hooks.mjs" }`. Events:
   `wiki.page.saved`, `history.run.ended`. A hook has 30 seconds; its errors are kept in
   `plugin-hooks.json`. `ctx.call(connection, tool, args)` reaches only a connected app that is on
@@ -114,6 +145,7 @@ callable result for one run.
 ```text
 <data root>/config/plugin-attachments.json     (registry-enabled.json read until the first change)
 <data root>/plugins/<name>/                     packages kept with the data; removal moves to trash/plugins/
+<data root>/plugin-proposals/<id>.json          proposed text, hash and review status
 <state dir>/plugin-trust.json                   trusted code, by hash
 <state dir>/plugin-registered.json              what each extension registered last time
 <state dir>/plugin-hooks.json                   hooks and their last run
@@ -134,13 +166,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,9 +16,9 @@ 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). |
+| `annotationsPart` (`page_notes_list`, `page_notes_read`) | `annotations/part.ts` | Read-only world tools over the page notes a person shared with the session or agent (PROP-0017, PROP-0048). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | gate | `sessions/sessions.ts::gate`, `sessions/runner.ts` | `ToolGate { ask, check }`, loaded as the last extension (`xagent-approvals`). |
 | `Approvals`, `decide`, `grant`, `approvalKey` | `sessions/approvals.ts` | Standing approvals. |
@@ -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`, `plugin_propose`. Broker:
 `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
@@ -45,6 +45,17 @@ when plan mode is active it reports the plan's allowed tool set. `sessions/planM
 the shared read-only allowlist. Host sessions use this Harness tool rather than defining a duplicate.
 It reports availability, never permission, and every call remains subject to the gate.
 
+## Plugin proposal security
+
+`plugin_propose { name, description, files }` is a write-classified Harness tool, subject to the
+normal capability and per-call gate, and creates only a pending proposal in the Harness data root.
+It does not accept, install, enable or trust a plugin. Proposal text is untrusted, including skill
+instructions; preview and human review are needed before acceptance. Acceptance is a separate
+trusted-caller API, bound to the reviewed content hash; it does not execute package code, grant
+trust or bypass the loader, attachment controls, capability restrictions or gate. Text contributions
+can load once enabled without code trust, so review their instructions as well as executable files.
+See page 06 and [ADR-0046](../decisions/ADR-0046-hash-bound-plugin-proposals.md).
+
 ## Native file paths
 
 The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
@@ -76,6 +87,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 +119,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 +155,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 +181,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,16 +191,23 @@ 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
-bridge; standalone policy permits naming without approval. See page 02 for validation and
-persistence. It is a foundation tool, not mutable variant data.
+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. When a top-level attended session starts unnamed, the
+harness also derives a provisional name from its first substantive request and sets it through
+Pi before the first model request; a host gate refusal or a failed write leaves the session
+unnamed and never fails the run. The model may revise the provisional name. 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.
 
 ## Diagnostic probes
 
@@ -181,3 +215,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