@xingular/harness 1.1.1 → 1.2.0

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, checklist 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
@@ -54,6 +58,14 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   `reaction.added`, `agent.message`, `checklist.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
@@ -93,11 +105,28 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
   carries `agent` and any `unavailableTools`. 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
+  checklist 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.
 - **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,
@@ -120,18 +149,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.
@@ -141,8 +204,11 @@ A session that cannot open ends its run as `failed` and returns `nativeSessionId
 - **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.
+  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,39 +222,75 @@ 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 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
+  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 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-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
+  `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).
 
 ## Native session names (PROP-0010)
 

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, checklist 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,22 @@ 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`
+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 `checklist_write` is available: it asks for a checklist
-early and kept current, because the person follows work from it (PROP-0006).
+early and kept 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 +79,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 checklist 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 +126,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
 

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
@@ -119,7 +136,7 @@ metadata or availability:
 | 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 |
 | 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 |
+| Operations | Doctor, worktrees and usage | Diagnostics, repository operations and usage analytics remain Harness-managed services |
 
 ## Terminal resource inspection
 

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

@@ -4,7 +4,9 @@
 
 A run's tools come from four places: the harness's own tools, the connected-apps broker,
 subagent tools, and the application's tool providers. Every call, whatever its source, passes one
-per-call gate that asks the application's policy, then standing approvals, then the person.
+per-call gate. Native writes also obey the run's pinned workspace boundary, with shell writes
+contained by an OS sandbox; the gate then applies application policy, standing approvals and the
+person without letting remembered per-tool grants widen that boundary.
 
 ## Components
 
@@ -14,39 +16,89 @@ per-call gate that asks the application's policy, then standing approvals, then
 | `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 because the user follows work from it. |
-| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030), `wait_subagents`. |
+| `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. |
+| `subagentTools` | `tools/spawnSubagent.ts` | `spawn_subagent` (requires a short `title`, PROP-0030) and `wait_subagents`; normal-mode descriptions guide selective, bounded delegation, while plan-mode spawns require a named eligible read-only research profile. |
 | `annotationsPart` (`page_notes_list`, `page_notes_read`, `page_notes_mark_fixed`) | `annotations/part.ts` | World tools over the page notes a person shared with the session or agent (PROP-0017). `page_notes_mark_fixed` records the agent's claim that it fixed a note it was sent; it never resolves a note or changes grants (PROP-0018). |
 | `webTools` | `web/tools.ts` | `web_search` (Brave, key from the secret store), `web_fetch` (checked public reads). An application provides them as a provider. |
 | 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. |
 
-Harness tools: `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:
+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:
 `mcp_list_tools`, `mcp_call_tool`. Native Pi tools: `read`, `grep`, `find`,
 `ls`, `edit`, `write`, `bash`.
 
+## Cross-surface registration (PROP-0040)
+
+The terminal registers Harness History/trajectory, Wiki-read and skill tools through
+`Terminals.ownTools` and dispatches them over the session socket; they are model tools, not merely
+shell commands. Enabled first-party hooks load through the protected `firstParty.list` bridge and
+`terminal/piExtension.ts`. Attended planning uses the shared `ask_user`; the terminal-only question
+alias is removed.
+
+`get_capabilities` is implemented as a read-only Harness tool. Structured sessions register it from
+the current run's frozen capability snapshot and live Pi tool/schema inventory. The terminal
+extension (`terminal/piExtension.ts`) registers the same schema from Pi's active and registered tools;
+when plan mode is active it reports the plan's allowed tool set. `sessions/planMode.ts` includes it in
+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.
+
 ## Native file paths
 
 The read-only `read`, `grep`, `find` and `ls` tools accept paths relative to the working folder,
-absolute paths, and `~` paths. The working folder is a default location, not a repository boundary;
-the operating system's access for the Harness process decides what can be read. The compiled file
-guidance names the configured data root. `edit`, `write` and `bash` continue through the existing
-gate and policy. A side-question run has an empty capability set and no tools (PROP-0019).
+absolute paths, and `~` paths. The working folder is a default location, not a read boundary; the
+operating system's access for the Harness process decides what can be read. The compiled file
+guidance names the configured data root. Each run pins `workspaceRoot`: the nearest Git root or
+worktree above its effective working directory, or the canonical working directory when there is no
+repository. The filesystem root itself is rejected because it would collapse the write boundary.
+`edit` and `write` resolve targets canonically, revalidate the pinned target at mutation,
+and atomically replace the directory entry in a helper process constrained by the OS sandbox. This
+prevents hard-link writes from changing another alias; normal file mode is retained where possible,
+but ACLs and extended attributes are not guaranteed to survive replacement. An outside target
+requires a human-only one-call approval (or an eligible Full Permission answer) and is not covered by
+remembered tool grants.
+
+Bash, including an initial `!` command, runs in an OS-enforced sandbox that permits broad reads but
+writes only inside the root. Before default-scope Bash, Harness scans the workspace for regular-file
+inodes with links outside it; an incomplete scan or possible external alias blocks the command, which
+must be repaired or copied. The sandbox also prevents its own processes from creating cross-boundary
+hard links; macOS denies hard-link creation entirely, including within the workspace. A local process
+outside Harness running as the same user is outside this protection.
+The Bash tool's optional `workspaceWriteScope` defaults to `workspace`; `outside` requests a
+human-only one-call approval before the exact command runs once with broader filesystem access. The
+approval shows the full escaped command in scrollable details and fails closed if the terminal
+cannot show both the details and the choices. The terminal uses `!outside <command>` for the same
+explicit request on a direct initial command.
+stdout/stderr never proves a sandbox denial: denial text cannot request approval, and a command is
+never replayed after partial effects. Full Permission is the explicit eligible-run bypass.
+Unsupported or unavailable sandbox enforcement fails closed. A side-question run has an empty
+capability set and no tools (PROP-0019).
 
 ## The gate, per call
 
+For native `edit` and `write`, the canonical target check is added to policy scope before approval;
+the registered tool can mutate only through the policy-bound atomic helper. Bash workspace scope
+scans for external hard links and then runs under the OS sandbox. An explicit outside scope is
+approved before execution and runs once; stdout/stderr never triggers approval or retry. The
+eligible Full Permission switch may answer the explicit request under its existing restrictions, but
+a remembered tool grant cannot.
+
 ```text
 child run and tool outside its snapshot ─► refuse
-plan mode and tool not research-safe    ─► refuse (before approvals)
+plan mode and tool/call not research-safe ─► refuse (including ineligible spawn profiles, outside-scope or denied Bash; before approvals)
+plan-mode Bash                          ─► read-only OS sandbox, never widened, run once
+canonicalize native write target / verify pinned root
 policy.scope(call)
   not allowed and (automatic or no approval possible) ─► refuse with reason
 policy.authorize(call) throws           ─► refuse
-allowed, not humanOnly, (automatic or not gated) ─► run
-trigger probe or improver               ─► refuse (nobody to ask)
-run.requestApproval(...)                ─► standing approvals may answer, else the person
-  denied                                ─► 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
+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
 policy.authorize(call) again            ─► run or refuse
 ```
 
@@ -60,23 +112,49 @@ the switch and global tools.
 
 - **INV-GATE-1** Every tool call of every run passes the gate. No tool source bypasses it,
   including extension-registered tools (which ask before every call) and the initial Bash command.
+- **INV-TOOL-9** `checkpoint_write` records one bounded handoff for the active run and is read-only
+  and plan-safe: no field changes files, and the record is the `checkpoint` run event (PROP-0041).
+- **INV-TOOL-10** Bash keeps one command budget on every surface: 120 seconds when the call says
+  nothing, 300 seconds as the ceiling without a `reason`, 900 seconds as the maximum, and a timeout
+  returns the partial output with a narrowing instruction instead of blocking the reply.
 - **INV-GATE-2** The gate is the last extension loaded, after disk, variant and inline extensions, so
   it sees the final input of every call.
-- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, then the policy's scope and
-  authorize, then standing approvals, then the person, then authorize again.
+- **INV-GATE-3** Order is fixed: capability and plan-mode refusals, canonicalize native file-write
+  targets, consult the policy's scope and authorize, combine mandatory outside-write approval with
+  that scope, then eligible standing approvals or the person, then authorize again. Native mutations
+  revalidate the authorized target and use atomic replacement inside an OS-enforced write scope.
+  Default Bash scans for external hard links, then runs only inside the OS sandbox. `workspaceWriteScope:
+  'outside'` requests human-only approval before running that exact command once with broader access.
+  Command output never proves a sandbox denial and never triggers approval or replay; earlier
+  side-effects are not repeated. The policy may tighten or deny a call, but cannot waive the boundary.
+  Outside file writes and broad Bash calls cannot use remembered per-tool approval; only the eligible
+  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.
 - **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
-  set (`INV-CAP-1`). The terminal may retain question-tool definitions in its private Pi inventory,
-  but normal mode deactivates them; a plan request activates only registered questions under its
-  plan-mode gate.
+  set (`INV-CAP-1`). `get_capabilities` is a read-only Harness tool on structured and terminal
+  surfaces; it reports the frozen callable set and does not grant access. The terminal may retain
+  question-tool definitions in its private Pi inventory, but normal mode deactivates them; a plan
+  request activates only registered questions under its plan-mode gate.
 - **INV-GATE-6** Tool attachment bytes never enter the run-event stream; only references are
   recorded.
 - **INV-GATE-7** Tool descriptions name the product with `{product}` (filled by `describeTool`),
   never an application's name (`INV-BND-2`).
-- **INV-GATE-8** Native read-only file access is bounded by process and operating-system
-  permissions, not by the repository root. Absolute and `~` paths are valid inputs. This does not
-  change the gate or permissions for writes and commands.
+- **INV-GATE-8** Native reads are bounded by process and operating-system permissions, not by the
+  workspace root; absolute and `~` paths are valid. Every run pins its canonical `workspaceRoot`.
+  Native `edit` and `write` mutations revalidate the authorized canonical target and atomically
+  replace it under an OS-enforced scope; outside targets require human-only one-call approval and
+  cannot use remembered tool grants. Default Bash scans the workspace for possible outside hard-link
+  aliases and is OS-sandboxed to write only inside the root while retaining broad reads; the sandbox
+  prevents its own processes from creating cross-boundary hard links, and macOS denies all hard-link
+  creation in the sandbox. An incomplete scan or missing
+  enforcement fails closed. An explicit `workspaceWriteScope: 'outside'` request is approved before
+  execution and runs once; command output never triggers approval or retry. The terminal exposes the
+  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.
 
 ## Data
 
@@ -85,7 +163,9 @@ the switch and global tools.
 ## Source map
 
 `src/tools/*.ts`, `src/web/*.ts`, `src/sessions/sessions.ts`, `src/sessions/runner.ts`,
-`src/sessions/approvals.ts`, `src/sessions/policy.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).
 
 ## Session naming (PROP-0010)