@xingular/harness 1.1.1 → 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,6 +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, 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. |
@@ -27,15 +28,18 @@ records everything the run does as validated events.
 
 1. Validate the input (`run.id`, `sessionId`, `text`; an `initialBashCommand` only on a new
    interactive user turn).
-2. Select the native history (`selectHistory`) and resolve the account (`accounts.resolve`).
+2. Resolve a continuation when requested; reuse its pinned root or derive one from its recorded
+   working directory. For a new run, resolve and pin the root from the effective `cwd` (after
+   worktree selection). Select the native history (`selectHistory`) and resolve the account
+   (`accounts.resolve`).
 3. Resolve the caller's capabilities, intersect with any narrower requested set, and **freeze**
    them for the run (`capabilities/runSnapshot.ts::freezeRun`).
 4. **Pin** the variant once (`variant/materialise.ts::materialise`).
 5. `saveRun` with status `queued`, the account, `harnessScope` and `harnessVersion`.
 6. Compile the prompt (`sessionLaunch`, page 04): a stable system prompt and an optional context
    update.
-7. `runs.start` the live run; build the tool list (broker, harness tools, the plan-eligible
-   `ask_user`, subagent tools, provider tools) and the gate.
+7. `runs.start` the live run; build the tool list (broker, Harness tools including read-only
+   `get_capabilities`, the plan-eligible `ask_user`, subagent tools, provider tools) and the gate.
 8. Open Pi through the `SessionFactory`, with resources loaded in order: disk extensions chosen by
    the harness, variant extensions, inline extensions, and the gate last.
 9. Record `nativeSessionId`, register the run with `Subagents`, start `runTurn`, and return
@@ -51,9 +55,17 @@ 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
+  native writes and default-scope Bash may modify: the nearest Git repository or worktree above its
+  effective working directory, otherwise that canonical directory. New runs pin it; continuations
+  reuse it. Older records may omit it, in which case a continuation derives it from the recorded
+  `workingDirectory`. The filesystem root itself cannot be selected as a workspace, because it
+  would collapse the write boundary. Native writes revalidate the target and atomically replace it
+  inside an OS write scope; Bash scans for external hard-link aliases and runs in the same pinned
+  boundary (page 07).
 - **Question sketches** (PROP-0025, ADR-0026; originally PROP-0024, ADR-0025). `question.requested` may include `uiSketch: true`
   and `sketch` text on each choice. If enabled, every choice must have a sketch; otherwise no
   choice may carry one. A sketch is 1–24 LF-separated lines, at most 80 printable ASCII characters
@@ -64,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.
@@ -85,23 +98,50 @@ 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`, subject to the caller's frozen capabilities; the gate refuses everything
-  outside `PLAN_READ_ONLY_TOOLS`, provider tools marked `readOnly`, and calls a provider marks
-  `planModeSafe`. The plan instruction arrives as a dynamic section; for UI-related plans it asks
-  the model to explore distinct design directions, compare trade-offs and recommend one, using
-  contextual `uiSketch` questions when helpful. The reply ends with one `<proposed_plan>` block.
+  include `ask_user` and `spawn_subagent` / `wait_subagents`, subject to the caller's frozen
+  capabilities. Delegation is limited to named profiles whose effective tool and plugin allowlists
+  qualify for read-only research; the child inherits plan mode and cannot write, run commands, ask
+  the user, use connectors or spawn children. The gate refuses unsafe calls before approvals and the
+  subagent service rechecks profile eligibility before launch. Other calls must be in
+  `PLAN_READ_ONLY_TOOLS` (including `get_capabilities` when frozen for the run), be provider tools
+  marked `readOnly`, or be explicitly classified by `planModeSafe`. Model-issued `bash` is allowed
+  and runs in the sandbox's read-only scope: no writes except a discarded temp folder, no network,
+  nothing that widens the scope; the gate refuses `outside` requests and `PLAN_BASH_DENIED` commands
+  (PROP-0043). The dynamic plan instruction
+  requires an opening `Goal` or `Summary`, evidence-grounded findings when useful, and task-scaled
+  steps and verification. A small fix stays concise without omitting its
+  outcome or check; cross-cutting work uses ordered steps. It uses alternatives only when requested
+  or materially useful; contextual `uiSketch` questions clarify real choices.
+  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
+  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
+  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
@@ -109,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
@@ -120,18 +161,52 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
 - **Usage** (`usage.updated`). `inputTokens` is uncached input; `cacheReadTokens` and
   `cacheWriteTokens` are separate; `outputTokens` includes `reasoningTokens`. Totals are
   cumulative for the run, not the native session. `contextTokens` is the latest request's size.
+  The derived usage ledger (`usage_requests`, page 08) copies these requests for
+  `/usage:analysis`; run events remain the only source of truth.
+- **Limit snapshots** (`account.status.limits`). A provider reading carries a window or balance,
+  its reset, and its source. It is produced by the usage limits service from provider response
+  headers or a documented provider endpoint (page 09), stored in the account's state, and never
+  inferred from a made-up cap.
 - **Provider reasoning summaries.** For supported Responses API families, when reasoning is
   enabled the runner requests a `detailed` summary and records only the provider's explicit summary
   (bounded to 4,000 characters) in request-level usage. This does not change reasoning effort or
   guarantee a provider will return a summary; raw reasoning is not used as a substitute.
 
+## Session controls and command runs (PROP-0040)
+
+`commands/registry.ts` is the browser-safe core command catalogue, shared by front ends.
+`commands.list` combines it with effective plugin, extension, prompt and skill routes (page 10).
+A listed route is not proof that its surface passes acceptance.
+
+`sessions/control.ts` owns saved-history operations: tree, navigation without a summary, fork,
+clone, rename, last reply and JSONL export. A `SessionRef` names `sessionDir`, optional
+`sessionFile` and optional `cwd`; the resolved JSONL must be inside that directory. Navigation
+records a `xingular-navigation` entry; choosing a user message returns its text for editing and
+moves before it. Fork and clone create history in an absolute `targetDir`.
+
+`SessionRunInput.command` (also `TurnParams.command`) is one of:
+
+- `{ name: 'compact', instructions? }`
+- `{ name: 'navigate', entryId, summarize: boolean, instructions? }`
+- `{ name: 'export', path }` (absolute `.html` path)
+
+It replaces prompt submission and skips the normal context update. It requires saved history and
+cannot combine with plan mode, continuation, automatic execution, initial Bash or images. It uses
+normal account/variant/capability pins, events and cancellation. Front ends must fence history
+mutations against active work; the current raw saved-history helpers do not themselves establish
+that fence. Stable native entry IDs must connect host transcript projection to navigation/fork,
+not positional message counts. A host can route `/history` to Harness `sessions.navigate` and
+navigate the same saved session; it must not substitute a fork. Shared session catalog registration
+is approved but remains in progress; no completed cross-surface catalog is implied (PAR-008).
+
 ## Invariants
 
-- **INV-RUN-1** A run pins one account, one variant version and one capability set when it
-  starts. None of them changes during the run. A pinned account that cannot be used fails the
-  run; it is never swapped (`INV-ACC-2`). A side-question run is the explicit exception for the
-  variant: it pins no variant and uses the fixed Harness instruction plus a redacted main-run
-  context projection (PROP-0019).
+- **INV-RUN-1** A run pins one account, one variant version, one capability set and one canonical
+  `workspaceRoot` when it starts. None changes during the run. A continuation reuses the prior
+  root, deriving one from `workingDirectory` only for a legacy record without the field. A pinned
+  account that cannot be used fails the run; it is never swapped (`INV-ACC-2`). A side-question
+  run is the explicit exception for the variant: it pins no variant and uses the fixed Harness
+  instruction plus a redacted main-run context projection (PROP-0019).
 - **INV-RUN-2** A run's capability set is written once (`freezeRun`). A resumed or duplicate launch
   with a different set fails with `capabilities_frozen`. A child run's set is the intersection of
   its parent's, its profile's tools and plugins, and what it asked for; it never widens.
@@ -140,9 +215,14 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   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
-  a new run the application asks for with `continueFrom`; it pins the earlier run's account, variant
-  version and capability set, and the earlier run's record is never reopened.
+  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
+  without a person (`automatic`), a plan, a subagent, a session command or a worktree never
+  continues itself.
 - **INV-RUN-5** Unattended runs (`automatic: true`) load no extension found on disk, read no
   context files, and never ask a person: anything that would need approval is refused. A variant's
   own trusted plugins still load, except for side-question runs, which have no variant or plugin
@@ -156,45 +236,98 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
 - **INV-RUN-7** Token accounting follows the usage contract above. Changing what a field means is
   an architecture change.
 - **INV-RUN-8** Plan mode keeps the stable system prompt but has mode-specific tools: an attended
-  plan may include `ask_user`, subject to the frozen caller capabilities; newly resolved normal,
-  automatic, probe, improver and reflection runs omit it. The terminal activates `ask_user` and
-  `ask_user_question` only for a plan request, then restores its normal set. Plan refusals happen
-  before approvals and no approval can lift them. Provider-cache effects of the tool-list difference
-  are not assumed (page 04, `INV-PRM-8`).
+  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 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); 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
   automatically (typed receipts in native history). A parent joins outstanding children before it
   completes.
 - **INV-RUN-10** An initial Bash command is allowed only on a new interactive user turn (not
-  automatic, plan, resumed, continuing, relation, probe or improver runs), must match the leading `!` command
-  in the text, and passes the same gate as model-issued Bash.
+  automatic, plan, resumed, continuing, relation, probe or improver runs), must match the leading `!`
+  command in the text, and passes the same gate as model-issued Bash. It is workspace-scoped by
+  default; the explicit terminal syntax `!outside <command>` requests the same human-only,
+  pre-execution outside-scope approval as the Bash tool and runs the command at most once.
 - **INV-RUN-11** A side-question run is independent, tool-free and temporary. It receives only a
   bounded, redacted projection of the main run's effective prompt and public events plus the
   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 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 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
+  (PROP-0033, ADR-0032).
 
 ## Data
 
-`<data root>/runs/<id>/`: `run.json`, `events.jsonl`, `owner.json`, `subagents.json`,
-`context.json`, `caller.json`, `capabilities.json`, `mcp-context.json`. Native history lives in
+`<data root>/runs/<id>/`: `run.json` (including the optional, legacy-compatible `workspaceRoot`),
+`events.jsonl`, `owner.json`, `subagents.json`, `context.json`, `caller.json`, `capabilities.json`,
+`mcp-context.json`. Native history lives in
 the session directory the caller passes (`sessionDir`), owned by Pi. Side-question native history
 uses a one-use OS temporary directory, removed when the run settles; its tracked run and events
 remain in the ordinary run store.
 
 ## Source map
 
-`src/sessions/*.ts`, `src/capabilities/runSnapshot.ts`, `src/tools/spawnSubagent.ts`.
+`src/sessions/*.ts`, `src/capabilities/runSnapshot.ts`, `src/core/workspaceBashTool.ts`,
+`src/core/workspaceSandbox.ts`, `src/core/workspaceWriteOperations.ts`, `src/tools/spawnSubagent.ts`.
 Decisions: [ADR-0002](../decisions/ADR-0002-native-subagent-lifecycle.md) (superseded),
 [ADR-0003](../decisions/ADR-0003-shared-asynchronous-subagents.md),
 [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-0026](../decisions/ADR-0026-contextual-question-wireframes.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,11 +16,13 @@ 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, 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. |
 
-All in `prompt/compile.ts`. A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
+Assembly is in `prompt/compile.ts`; shared standard-section data is in `prompt/standard.ts`.
+A `ContextPack` holds `sections: Section[]` (each with `id`, `title`,
 `body`, `sources`, `budget`, `size`, `cut`), `toolGroups`, `harness` (scope and fingerprint),
 `profile`, `compiledAt` and `delivery` (`systemSectionIds`, `updatedSectionIds`).
 
@@ -29,14 +31,23 @@ All in `prompt/compile.ts`. A `ContextPack` holds `sections: Section[]` (each wi
 `SECTION_ORDER`: `harnessIdentity` 5, `system` 25, `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, `subagents` lists every agent profile it can start (built-in, global,
-project and the variant's c5 names) and replaces the variant's own list (PROP-0029). The `tools`
-section has a Progress paragraph whenever `checklist_write` is available: it asks for a checklist
-early and kept current, because the person follows work from it (PROP-0006).
+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
+guidance in that section explains when delegation is worth its overhead, profile selection,
+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 `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
-`env.productName` (default `Xingular Agent`). Host-provided identity and role sections remain
-separate, so an embedding application can still describe its agent and task.
+`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
+guidance for the effective tools. Terminal preparation defaults to standard sections (explicit
+`standard: null` opts out); the host interactive path requests the same sections. Hosts may add
+attributed add-on and task context, not a duplicate standard role or connection policy (PROP-0040).
 
 Budgets (characters): variant sections 30,000 each (already capped at save, so never cut here);
 references 12,000; Wiki pointer 2,500; tools 8,000; reporting 2,000; application sections their
@@ -69,17 +80,34 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
   `dynamic: true`.
 - An update lists only the dynamic sections that changed, and announces a withdrawn one.
   `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 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
   message details (`xingularContext`); recording a pack does not mark it delivered.
 - Terminal sessions use `compile` + `render` once, pass it as `--append-system-prompt`, and keep
   that pack for the life of the session.
-- Read-only native file guidance states that absolute and `~` paths work when the operating system
-  permits access, names the configured data root, and describes the working folder as a default
-  location. Edits and commands remain subject to the gate.
+- Native file guidance states that absolute and `~` paths work for reads when the operating
+  system permits access, names the configured data root, and describes the working folder as a
+  default location. Native writes and Bash filesystem effects default to the run's pinned project
+  or worktree root; outside file targets require one-call approval, and Bash is sandboxed unless
+  the eligible user explicitly enables Full Permission. Edits and commands remain subject to the
+  gate.
 - A side-question launch attributes its fixed no-tool instruction to the `side-questions` plugin.
   Its launch suppresses tool guidance entirely. The main run's effective prompt and current context
   update are included in the separately bounded, redacted context message (PROP-0019).
 
+## Launch parity status (2026-11-19)
+
+Shared section generation is present in source; `surfaceParity.test.ts` checks compiler equality.
+That does not verify actual prepared launches, registered schemas, credentials, variant pins or
+provider-cache reuse. PROP-0040 also requires one Harness-owned interactive default for roots,
+variant scope and credential backend. Adoption and runtime acceptance remain in progress; explicit
+roots/scopes and continuation pins take precedence. Matching `--data` alone cannot reconcile a
+file SecretStore with a host Keychain. See [parity](../parity.md).
+
 ## Invariants
 
 - **INV-PRM-1** The prompt is assembled only in `src/prompt/compile.ts`. Nothing else builds model
@@ -99,9 +127,20 @@ compile ──► pack ──► stable sections ──► system prompt (+ "Con
 - **INV-PRM-8** Whether a prompt or callable tool-list change keeps the provider's cache is measured
   with real requests from the application, only with the account owner's permission. Tests do not
   stand in for it.
-- **INV-PRM-9** Native file guidance describes the existing OS-permission boundary accurately:
-  absolute and `~` paths are valid for read-only file tools; the working folder is not a sandbox.
-  Side-question runs with no callable tools omit tool guidance.
+- **INV-PRM-9** Native file guidance describes the boundary accurately: absolute and `~` paths
+  are valid for read-only file tools, which remain bounded by OS permissions rather than the
+  workspace root. Native file writes and Bash filesystem effects are workspace-scoped by default;
+  the working folder itself is not the boundary. Side-question runs with no callable tools omit
+  tool guidance.
+- **INV-PRM-10** Compaction checkpoints are assembled by this compiler, bounded, and delivered only
+  as ephemeral context while their active run continues. They do not change the stable system prompt
+  or native history, and do not carry hidden reasoning (PROP-0033, ADR-0032). A work-slice handoff is
+  the same kind of bounded projection: the `checkpoint` event is rendered into the continuation
+  section by `continuationBody`, never into the system prompt (PROP-0041).
+- **INV-PRM-11** The Progress group names `checkpoint_write` when it is in the frozen capability
+  set, with the same budget as the other tool guidance, and says only that a bounded reply records a
+  handoff when its budget is reached. It does not describe the limits themselves, which the guard
+  states at the boundary.
 
 ## Relation to DESIGN-0001
 
@@ -116,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

@@ -17,7 +17,7 @@ callable result for one run.
 | `Plugins` (`loading`, `loaded`) | `plugins/plugins.ts` | Chooses the paths a session or terminal loads; records what each extension registered. |
 | discovery | `plugins/discover.ts` | Finds items with Pi's own resolver, which runs no extension code. |
 | attachments (`load`, `save`, `attached`, `decided`, `set`) | `plugins/attachments.ts` | The one store of what is switched on, per scope. |
-| `BuiltinPluginRegistry`, `BuiltinPluginModule` | `plugins/builtinRegistry.ts`, `plugins/builtin.ts` | Registers built-in modules and their descriptors, world parts, server handlers and terminal command metadata. |
+| `BuiltinPluginRegistry`, `BuiltinPluginModule` | `plugins/builtinRegistry.ts`, `plugins/builtin.ts` | Registers built-in modules and their descriptors, world parts, server handlers and plugin-owned terminal commands. Harness core commands live in `commands/registry.ts`, shared by both surfaces. |
 | `HARNESS_PLUGINS` | `plugins/builtin.ts` | Descriptor view of the registered Harness parts and feature plugins. |
 | `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. |
@@ -29,14 +29,26 @@ callable result for one run.
 ## Contracts
 
 - **Loading.** `Plugins.loading({ cwd, agentDir, caller, contributions, install? })` returns
-  `extensionPaths`, `skillPaths`, `promptPaths`, `themePaths`, `builtins` (terminal only), `hooks`,
+  `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
   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.
+- **Surface metadata (PROP-0040).** `PluginDescriptor.surfaces` and `Plugin.surfaces` optionally
+  carry `{ preferred: 'host', terminal: 'fallback' | 'unavailable', note: string }`.
+  `plugins/surfaces.ts` formats the note and badge. Inspection explains what the host adds and
+  what the terminal does instead; this is not a category, attachment switch or permission.
+- **Shared resources (PROP-0040).** Both surfaces load Harness-selected resources and enabled
+  first-party hooks, including output trim and budget guard. Terminal preparation exposes these
+  through its protected bridge. Pi CLI-only llama.cpp, codemode, tool-search and MCP built-ins are
+  not selected or advertised as extra terminal capabilities. This does not remove Harness MCP.
 - **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" }`.
+  `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.
 - **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
@@ -48,7 +60,10 @@ callable result for one run.
   capability. Automatic or refinement-triggered continuations with it are rejected rather than
   weakening the frozen set. The `side-questions` descriptor owns the fixed instruction for the
   restricted side-question run; it has no tools, providers, connectors, subagents or variant code
-  (PROP-0019).
+  (PROP-0019). In plan mode, delegation is limited to research children: the resolved profile must
+  have explicit tool and plugin allowlists confined to the research set, and the child's frozen
+  capabilities are intersected with the parent and profile. A profile name or its instructions alone
+  never grants eligibility (INV-RUN-8).
 
 ## Invariants
 
@@ -78,9 +93,11 @@ callable result for one run.
   parts are required and refuse to be switched off; switching something on grants no permission.
   A side-question run also has no variant plugin code or tool guidance (PROP-0019).
 - **INV-PLG-10** Every Harness-managed built-in feature is registered by `BuiltinPluginRegistry`.
-  Its descriptor, world tools, server handlers and terminal command metadata share one owner. A
-  module's world part releases resources through the existing session and Harness lifecycle. This
-  registry does not load third-party Pi code or bypass its trust checks.
+  Its descriptor, world tools, server handlers and any plugin-owned terminal commands share one
+  owner. First-class Harness terminal commands are registered by the terminal command registry and
+  do not depend on a feature plugin's command metadata or attachment state. A module's world part
+  releases resources through the existing session and Harness lifecycle. This registry does not
+  load third-party Pi code or bypass its trust checks.
 - **INV-PLG-11** Built-in plugin categories are a documentation ownership taxonomy. They are not a
   `PluginDescriptor` field, a public response field or a second attachment scope.
 - **INV-CAP-1** A capability set only narrows. `intersect` never adds access; a run's set is
@@ -117,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 and worktrees | Diagnostics and repository operations remain Harness-managed services |
-
-## Terminal 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).
+| Operations | Doctor, worktrees and usage | Diagnostics, repository operations and usage analytics remain Harness-managed services |
+
+## Terminal plugin and resource inspection
+
+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).