@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,505 @@
+# 02 Sessions and runs
+
+## Purpose
+
+A *session* is a native Pi conversation. A *run* is one tracked execution interval of a session:
+one turn from a request to an outcome. The harness opens Pi for each run with a pinned account,
+a pinned variant, a frozen capability set, a compiled prompt and a gated tool list, then
+records everything the run does as validated events.
+
+## Components
+
+| Type | Module | Role |
+|---|---|---|
+| `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. |
+| `Subagents` | `sessions/subagentService.ts` | `spawn`, `wait`, `results`, delivery receipts, recovery. |
+| `SideQuestions` | `sessions/sideQuestions.ts` | Starts, reads and interrupts independent tool-free runs using bounded context from the main conversation (PROP-0019). |
+| plan mode | `sessions/planMode.ts` | `planSection`, `planRefusal`, `PLAN_READ_ONLY_TOOLS`. |
+| `Approvals` | `sessions/approvals.ts` | Standing approvals (page 07). |
+| history selection | `sessions/history.ts` | `selectHistory`: which native history file a run continues. |
+| `runIndex`, `pricing`, `reasoningSummaries`, `lineageJoin`, `extensionUi` | `sessions/` | Run listing, cost, provider summaries, parent/child joins, extension UI as run events. |
+
+## Runtime flow of `sessions.run`
+
+1. Validate the input (`run.id`, `sessionId`, `text`; an `initialBashCommand` only on a new
+   interactive user turn).
+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 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
+   `{ runId, nativeSessionId }`. The reply streams as run events.
+
+A session that cannot open ends its run as `failed` and returns `nativeSessionId: null`.
+
+## Contracts
+
+- **Run status:** `queued`, `running`, `waiting_for_approval`, `waiting_for_input`, `interrupted`,
+  `completed`, `failed`. The first four are active (`ACTIVE_STATUSES`).
+- **Run events** (`runEventTypeSchema`): `started`, `context.snapshot`, `message.delta`,
+  `message.completed`, `message.steered`, `tool.started`, `tool.completed`, `tool.refused`, `retry.started`,
+  `retry.ended`, `compaction.started`, `compaction.ended`, `approval.requested`,
+  `approval.resolved`, `question.requested`, `question.answered`, `extension.notice`,
+  `reaction.added`, `agent.message`, `todo.updated`, `checkpoint`, `heartbeat`, `artifact.added`, `file.changed`, `usage.updated`,
+  `account.status`, `status.changed`, `failed`, `completed`. Each has a payload schema in
+  `runEventPayloadSchemas`.
+- **Stop codes.** `terminalCode` is nullable for legacy records and identifies a recorded outcome independently of `terminalReason`. Structured sessions record `completed`, `user_abort`, `slice_budget`, `compaction_thrash`, `provider_error`, or `failed`; recovery can record `harness_restart`, `stalled` or `owner_gone`. Other shared codes include `terminal_attention`, `terminal_closed` and `parent_stopped`. Interrupted `status.changed` events may carry the code; failure codes map to a stop code. Legacy events without a code remain unknown.
+- **Queued-message dispatch.** Both front ends retain Pi's normal delivery behavior after success. Only an explicit user stop may release messages still queued when a reply is interrupted: send the oldest unconsumed steer first, then the oldest follow-up. Retry events are not settlement boundaries; provider failure, a retry that ultimately fails, and non-user interruption leave queued messages parked. A settled interruption alone is not proof of user intent.
+- **Compaction evidence.** Structured compaction starts include the latest known context tokens and window when available; ends include Pi’s `tokensBefore` when supplied. Tokens after compaction remain unknown unless reported.
+- **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).
+- **Workspace snapshot** (`RunRecord.workspaceSnapshot`, PROP-0052). Before the agent acts on a turn
+  a person typed (a structured session's own turn, or a terminal turn with text), the harness
+  records `{ kind: 'git-snapshot', repo, commit, omitted? }` when the working folder is in a git
+  repository: a commit of tracked edits, deletions and bounded untracked files (5 MB each, 100 MB,
+  10,000 files; `omitted` counts the rest) made through a throwaway index. The working tree, the
+  real index, HEAD and refs are not touched. A snapshot that fails or takes longer than two seconds
+  records nothing. Refinement replays the turn from it (page 05).
+- **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
+  per line (1,943 bytes maximum), with at least one visible character. Tabs, CR, other controls,
+  escape sequences and non-ASCII text are rejected. Whitespace, including interior blank lines and
+  trailing spaces, is preserved literally in the persisted request event. Tool guidance requests
+  detailed contextual UI wireframes on a fixed 80-column canvas, with actual panel/table structure
+  and neighboring elements consistent across alternatives. The terminal pads shorter rows to this
+  canvas for display; the schema still permits sketches shorter than 80 columns, so generation
+  quality remains guidance rather than a validation 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.
+- **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.
+- **Run details observations.** Optional `loadedSkills` records successful Harness `skill_load` calls during the run, not skill availability or native file reads. Optional `activatedPlugins` records observed activated extension plugin identities only when the loader can account for them; omission means unknown, including historical runs and unsupported boundaries. Empty arrays mean the corresponding observation found none.
+- **`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.
+- **Triggers the harness reads:** `user` (may carry an initial Bash command), `probe` and
+  `improver` (refinement, page 05), `reflection` (lessons, page 08). Runs with the last three are
+  never asked about: the gate refuses what would need a person, and they receive no question tool.
+  Only attended plan runs may newly receive `ask_user`.
+- **Side questions** (PROP-0019). `sideQuestions.start` creates a separate run with trigger and
+  relation `side-question`, a fresh native history, the selected account/model/effort, no variant,
+  and an empty frozen capability set. It combines the parent's persisted effective prompt and
+  public run events with the surface's visible transcript and selected references, after redaction
+  and fixed bounds. Hidden reasoning and attachment bytes are omitted. A supplied parent run must
+  belong to the supplied parent session. `sideQuestions.read` and `interrupt` require the side run's
+  session id. The run is not a subagent or continuation and never changes the parent.
+- **Subagents.** `spawn_subagent` / `wait_subagents` for the model; `subagents.spawn`, `wait`,
+  `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`).
+  A run also starts only a few children: by default at most four distinct child conversations, at
+  most two `worker`, three `explorer`, one of any other named profile and one with no profile. The
+  parent's `subagents` option overrides them (`maxChildren`, `maxByProfile`, `maxOther`,
+  `maxUnprofiled`), clamped to 0–50. The count covers this run and the runs it was continued from
+  (`resumedFromRunId`), so a work-slice continuation keeps the budget; it counts distinct
+  conversations, so continuing a stopped child uses no new slot, while a child whose startup
+  failed still counts. A concurrent spawn reserves its slot before it launches. A refused spawn is
+  an `invalid_request` whose message tells the model to do the work itself; no child run is
+  created.
+  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 switched-on package's
+  profiles (page 06) then fill names nobody else took; the run resolves them once at start into
+  `packageProfiles`, and its children resolve their profiles from that list. A profile narrows the
+  child's tools and plugins (`agents/narrow.ts`), may choose its variant, model and effort, and
+  frames it with a "Your role" section. The child's record carries `profile`; the spawn result
+  carries `agent` and any `unavailableTools`. `main` is reserved for the main agent's row: no
+  profile file or variant definition may take it. A run that may spawn lists every profile in its
+  `subagents` section.
+- **Plan mode** (`plan: true`). The stable system prompt is unchanged. An attended plan run may
+  include `ask_user` and `spawn_subagent` / `wait_subagents`, subject to the caller's frozen
+  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 asks the model to check whether the requested work
+  already exists before designing it, to name the evidence and stop when it does, and says that a
+  person's instruction not to plan outranks the mode's output shape. It also
+  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 encourages questions about material
+  user-owned decisions and important assumptions after discovery, including when a default exists.
+  For unresolved substantive UI or TUI layout and interaction choices, it defaults to contextual
+  `uiSketch` questions with meaningful alternatives; routine, specified, delegated or nonvisual
+  decisions do not require sketches. Both the dynamic section and compaction checkpoint have room
+  for the complete bounded plan instruction.
+  **Outcome contract (ADR-0077, superseding the repair criterion of ADR-0055, ADR-0057 and
+  ADR-0058).** Classify a
+  new final reply as exactly one of `plan_ready`, `blocked`, `no_plan`, or `invalid`. `plan_ready`
+  uses one complete `<proposed_plan>` block and is the only outcome that offers a plan card and
+  Implement. When a required user decision cannot be obtained because `ask_user` is unavailable,
+  `blocked` uses one complete nonempty `<plan_blocked>` block to report the blocker without asking
+  a free-text question or inventing the decision; it
+  is not a plan and never offers Implement. `no_plan` is an ordinary reply with no outcome block: it
+  says there is nothing to design, because the work already exists, the person declined to plan, or
+  no decision is needed. It is a valid conclusion, not a formatting failure, and it offers no card,
+  notice or warning and no second request. New final replies must not use `<plan_clarification>`
+  or free-text questions as a clarification channel. A block the model started and left unbalanced,
+  empty, duplicated or in conflict is `invalid`, not a guessed plan; tags inside fenced or inline
+  code are text, not outcomes. When clarification is needed and `ask_user`
+  is available, it blocks the active run for the answer, then that same run continues research and
+  planning.
+
+  Server and terminal use the same outcome classification and one bounded, hidden repair turn
+  in the same eligible attended top-level plan run, only for `invalid`. The repair asks for the
+  declared block to be finished or for the statement that there is nothing to plan; it does not
+  invent decisions or change the substance, and it may call `ask_user` when
+  available, blocking the active run for the answer. It is not a new user request, does not bypass
+  the plan gate, and is never attempted for a
+  plan-research child, command, probe, improver, reflection, other unattended run, interruption,
+  error or work-slice termination. A second invalid result ends repair: retain the original reply,
+  complete the run with a warning and no Implement choice. Preserve the existing plan tag, card,
+  run events, tool permissions and cached prompt boundary; old transcripts, including legacy
+  clarification blocks and untagged replies, remain intact and visible, not silently promoted to
+  plans. Do not require clients to understand a new event type.
+- **Compaction checkpoint** (PROP-0033, ADR-0032, ADR-0067). After a compaction that happens
+  during an active run, its model context receives a bounded, ephemeral checkpoint with the current
+  user request and the todo list or applicable plan instructions as they were at that compaction,
+  when either is available to restore. A run that starts from already-compacted history gets none:
+  its request, todo and plan are in live history. The checkpoint is built once per compaction and
+  re-added to each request at the same place, directly after the compaction summary, so each
+  request stays the previous one plus new items and provider caching keeps working. Later
+  `todo_write` calls in history supersede its list. 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 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
+  fails with `continuation_mismatch`; a run that cannot be continued fails with
+  `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 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
+  (`worktrees/`), the run works in that worktree's folder (the given `cwd` is replaced), holds a
+  lease on it (holder: the session id, with `git worktree lock`) until the run completes, fails or
+  is interrupted, and records the id. An id the registry does not know is stored and returned as
+  the caller's own field, as before. A terminal session holds its worktree for its whole life.
+- **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).
+
+## Live sessions (ADR-0083)
+
+A *live session* is a Pi session the harness keeps open between the runs of one conversation, so a
+later run reuses it instead of opening and loading a new one. `sessions/live.ts::LiveSessions` holds
+them, one per `run.sessionId`.
+
+- **Opt in.** `SessionRunInput.live: true` keeps the session open after the run and reuses an open
+  one. It is refused (`invalid_request`) for an unattended, child, nested, probe, improver or
+  reflection run, and refused with `session_busy` while another run of the session is using it.
+  Without `live` a run opens and disposes its own session, as before.
+- **Pins.** A live session serves a run only when everything the run pins equals what the session
+  was opened with: account and its config folder, variant scope and version, variant extensions and
+  skill paths, the frozen capability set, working folder, workspace root and history folder, plan
+  and plan-repair flags, the allowed, gated and bound tool names, the stable system prompt, model,
+  effort, the run-scoped extension names and whether provider tools are asked. A supplied history
+  file and native session id must be the session's own. Any difference closes the idle session at
+  the turn boundary and the run opens a fresh one on the same native history.
+- **Rebinding.** `piSessionFactory` reads the run's gate, bound tools, extension host and
+  plan flag through a binding that `PiSessionLike.rebind` replaces at the start of each run. The
+  run-scoped inline extensions (lineage join, subagents, compaction checkpoint, work slice, goal,
+  first-party hooks) are loaded in slots: a rebind removes the last run's handlers (Pi's `on`
+  returns the remover) and runs the next run's factory against the same extension. A session whose
+  run-scoped extension registers anything but handlers is not reusable. Between runs an extension
+  dialog is refused with `run_not_active`.
+- **One writer of the history.** A top-level run of the same session that is not live (a command
+  run, for example), and `sessions.navigate` or `sessions.rename` on its history folder, close an
+  idle live session first so nothing holds a stale copy of the file; while the live session is
+  replying they are refused with `session_busy`.
+- **Settling.** `runTurn` calls `TurnParams.release` instead of disposing the session. An idle live
+  session closes after 30 minutes (`SessionsOptions.liveIdleMs`), on `sessions.close`, or when the
+  harness closes.
+- **Follow-ups.** `sessions.followUp { sessionId, text }` starts the next run at once when the
+  session is idle, or queues the text (at most 20) for after the active run. The queue follows the
+  queued-message dispatch rule above: it is sent after a reply that completed or that the person
+  stopped, and parked after a failure or any other interruption; a work-slice continuation runs
+  first. A follow-up run repeats the last live run's input with its own text and no Bash, images,
+  command, continuation or goal. `runs.steer` steers the active run as before.
+- **Other run inputs a live client uses.** `newHistory: true` starts a new native history in
+  `sessionDir` (refused with `resume`, `continueFrom` or `command`). `hiddenNotes` (at most 8, each a
+  lower-case type and up to 20,000 characters) are saved as hidden messages before the request, as
+  the context update is. `planTools: 'active'` makes a plan run's frozen tool set the plan's own
+  (`planModeTools`), so the request carries only those tools; the default `gate` keeps every tool in
+  the request and refuses at the gate. An initial Bash command is accepted on a live turn that
+  resumes its history.
+- **Question dialogs.** `question.requested` may carry `dialog { kind: select | confirm | input |
+  editor, title, message?, placeholder?, prefill?, options? }` when a Pi extension's dialog asked it
+  (`sessions/extensionUi.ts`). A host may ignore it; the answer is the usual `QuestionAnswer`.
+- **Methods.** `sessions.live {}` → `{ sessions: LiveSessionStatus[] }`; `sessions.close { sessionId }`
+  → `{ closed, afterRun }` (a busy session closes when its run settles);
+  `sessions.followUp { sessionId, text }` → `{ runId } | { queued }`;
+  `sessions.followUp.clear { sessionId }` → `{ removed }`.
+
+## Invariants
+
+- **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.
+- **INV-RUN-3** Every run event is validated against its schema, redacted, persisted, and only then
+  relayed to listeners, in order. An event that arrives after the run settled is kept as evidence
+  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; 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
+  code and use an empty capability set (PROP-0019).
+- **INV-RUN-6** Only the harness writes `runs/<id>/`; an application reads it. `run.json`,
+  `events.jsonl`, `owner.json` and `subagents.json` are written only through
+  `sessions/runStore.ts`. Side files are written by their owning module: `context.json`
+  (`prompt/compile.ts`), `caller.json` (`sessions/sessions.ts`), `capabilities.json`
+  (`capabilities/runSnapshot.ts`), `mcp-context.json` (`mcp/service.ts`). Adding another writer
+  or side file needs a proposal. (See drift D-1.)
+- **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`, `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`). Pi records a tool-set change only with the next
+  request, so the terminal brackets each plan request with `xingular-plan-tools` entries (`begin`
+  carries the normal set it replaced, then `end`). Whenever Pi rebuilds the active tools from the
+  transcript (a new runtime, resume, switch, fork or tree navigation), `normalToolsForBranch` returns
+  the bracketed normal set if the last recorded set is a plan's, so a plan never leaks into normal
+  mode.
+- **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. 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 may be a bounded work slice (PROP-0041), but the foundation has no budget
+  (ADR-0081): the defaults are no tool-call limit, no time limit and no new-token limit (earlier
+  defaults: 320 calls and 60 minutes, PROP-0044). A caller that asks for one sets `workSlice` on a
+  run or `XINGULAR_WORK_SLICE` at launch; a token cap is counted on new input, cache writes and
+  output and never on the cached prefix. Everything below describes a reply that was given a limit,
+  and the three-compaction guard, which is not a budget, stays on. At the
+  limit the guard refuses the next tool call and asks the model to stop and report where it is; the
+  harness then writes the checkpoint itself from the reply's files, checks and todo list (the model
+  has no checkpoint tool since ADR-0069). A non-handoff tool call after the refusal ends the reply. A
+  budget-ended reply is `interrupted` with terminal reason `slice_complete` (ADR-0053), unless it
+  continues: a headless run as a new run (`continueSlice`), a terminal reply in place as its next
+  slice (ADR-0070), both up to `maxSlices` and never after a fruitless or blocked slice. The budget
+  covers the whole reply: Pi emits `agent_start` for every continuation (a slice continuation, delivered
+  subagent results, a plan repair), so the guard starts a new slice only on a person's message.
+  No call is refused for repeating: identical calls, a Bash check that keeps failing and repeated
+  `edit`/`write` results on one path are allowed as often as the work needs, because a distinct read
+  or another edit is not evidence of a loop. `todo_write` counts toward the tool-call budget and is
+  otherwise unconstrained. Third-compaction thrash detection remains: three context compactions in
+  one reply end it with the same handoff request. Plan-research children 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 —
+  and ends only when the model stops or a person interrupts. A reply the model ends on its own
+  settles as it ends (INV-RUN-15); in a goal, the goal loop (INV-RUN-16) continues it. A
+  continuation carries the todo it left (`continuation.ts`).
+- **INV-RUN-15** A reply the model ends settles as it ends (ADR-0075): the harness never sends it
+  back and never overwrites its status from the todo list. The todo list is progress, not a gate.
+  Only three things settle a reply otherwise: a person's interrupt (`interrupted`), the work-slice
+  guard (INV-RUN-13), and a goal's stop (INV-RUN-16) — a goal that ends blocked settles
+  `needs_person`, and one that ends on a limit, a pause or a stall settles `unfinished`, each with a
+  harness-written checkpoint. **No model judges an ordinary reply** (ADR-0072 removed ADR-0071's
+  every-reply completion check); only a goal's completion claim is checked (INV-RUN-16). Carrying
+  the request to completion is the prompt's job (`04-prompt.md`). There is no stop gate, no nudge
+  and no `XINGULAR_STOP_GATE` switch.
+- **INV-RUN-16** A goal is the person's opt-in long run (ADR-0072). Only a person's own top-level run
+  carries one (`sessions.run` `goal`, or `/goal` in the terminal); never a plan, command, unattended
+  or child run. While its status is `active`, a reply that would end continues in place (the goal
+  loop, `sessions/goalLoop.ts`) with the continuation prompt, counting a round. Statuses are
+  `active | paused | blocked | usage_limited | budget_limited | complete`; the person sets, edits,
+  pauses, resumes and clears, the system limits (`budget_limited` at 30 rounds or 8 hours by default;
+  `usage_limited` on a provider usage limit; `blocked` after three automatic rounds with no activity,
+  three with only failed commands, or a provider error), and the model may only claim `complete`,
+  report `blocked` after the same blocker on three consecutive goal turns, or `paused` at the person's
+  request. A `complete` is a claim: at the next settle the same model, at low effort and with a fresh
+  context, checks it against the objective and the transcript; `done` completes the goal, `continue`
+  keeps it active with the reason, and no model, an error or an unreadable answer accepts it. The
+  loop never stops a goal for a round without a tool call alone. A goal that ends `blocked` settles
+  the run `needs_person`; one that ends paused, limited or stalled settles it `unfinished`. The run
+  record keeps the goal as `goalMode`. `XINGULAR_COMPLETION_CHECK=off` accepts every claim unchecked.
+- **INV-RUN-14** A run event stream carries `checkpoint` (the handoff the harness derives from the
+  run's own evidence; runs written before ADR-0069 may hold one the model wrote) and `heartbeat`
+  (steps, elapsed time, last tool, compactions, slice, the call budget, and the names and oldest age of
+  the tools running at that moment). Every live reply emits a
+  heartbeat every 30 seconds, terminal replies included. 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. A heartbeat of a run with no work slice carries zero slice
+  counters. A reply whose heartbeat keeps arriving but which produces no
+  other event for fifteen minutes is a wedged turn, not a busy one: the harness ends it through the
+  native abort and records `interrupted` with reason `stalled`, and grants a reply whose oldest
+  running tool has run for thirty minutes the same ending. `runTurn` applies this to every run
+  (a structured session, a live session, the client terminal, an unattended run) with the same
+  windows (`sessions/stallWatch.ts`); the in-process terminal's controller applies it to its own
+  reply. A live session whose turn stalled is closed rather than reused, its queued follow-ups
+  parked for the next session, and closed under the turn after thirty seconds if the abort did not
+  unwind it (ADR-0083). A reply whose only running tools are
+  `wait_subagents` or `spawn_subagent` is judged by its children instead: each child has its own
+  clock (its last event other than a heartbeat; its running tools), and a child quiet for the same
+  windows is interrupted with reason `stalled`, so the wait returns and the parent carries on by
+  itself. The parent's own rule resumes if no child answers to its watch, or one ignored the stop for
+  five minutes (ADR-0078). An unanswered approval or question is never cut short. The watchdog never
+  restarts work (ADR-0054).
+- **INV-RUN-12** A post-compaction checkpoint is a bounded context projection of the active request,
+  the validated todo list and applicable plan instructions as of a compaction that happened during
+  that run. It is compiled by `prompt/compile.ts` once per compaction and placed, unchanged, directly
+  after the compaction summary in each later model request of 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, ADR-0067).
+
+## Data
+
+`<data root>/runs/<id>/`: `run.json` (including the optional, legacy-compatible `workspaceRoot` and
+the optional `workspaceSnapshot`),
+`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/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-0033](../decisions/ADR-0033-plan-mode-research-delegation.md),
+[ADR-0039](../decisions/ADR-0039-progress-aware-stall-guards.md),
+[ADR-0053](../decisions/ADR-0053-no-repeated-work-guard.md),
+[ADR-0054](../decisions/ADR-0054-terminal-reply-heartbeat-and-stall.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 normally calls it once before its first other tool call when a
+request needs tools or changes state, and revises it only when the overall objective changes,
+including a manual name. When a top-level attended session starts unnamed, the harness also
+derives a provisional name from a substantive first request before the first model request;
+greetings, thanks and short conversational replies stay unnamed. The model may revise the
+provisional name. Agent-submitted names are imperative sentences
+of at most six whitespace-separated words; whitespace is normalized, and empty names,
+terminal escapes, non-whitespace controls and longer names fail without writing. Identical
+names are a no-op. Pi's native session-info history is the only storage; continuation and
+reopen preserve it. Each child names only itself. There is no additional model request or
+run-event schema. The normal capability selection and host gate apply; a refused or failed
+provisional name leaves the session unnamed and never fails the run. `harnessTools: false`
+omits the tool. Plan mode permits it as session metadata maintenance.

package/docs/architecture/03-variants.md

@@ -0,0 +1,122 @@
+# 03 Variants
+
+## Purpose
+
+A **variant** is the part of the harness that is allowed to change: everything that shapes an
+agent's behaviour apart from the model, the application's own sections and the foundation
+(page 00). It is eight components (c1–c8, after Harness²). Each caller scope has
+content-addressed, validated, immutable versions of its variant and a head, the variant it runs
+now. A run pins one version. Refinement (page 05) proposes new variants; a person adopts them.
+
+What a variant may contain is fixed by the foundation: the surface (`PI_SURFACE`), the validator
+and the always-on cap. A variant can change what the agent is told and which skills, scripts,
+subagents and plugins it may load. It cannot change the prompt compiler, the gate, the run
+recorder, accounts or trust.
+
+Earlier documents called this the "harness tree" and its invariants `INV-TREE-n`; those are now
+`INV-VAR-n`.
+
+## Components
+
+The surface is `PI_SURFACE` (`variant/surface.ts`), the one surface this harness runs.
+
+| c | Component | Path in the variant | Reaches a run | Group |
+|---|---|---|---|---|
+| c1 | System prompt | `systemprompt.md` | always (prompt section `system`, order 25) | context |
+| c2 | Guardrails | `guardrails.md` | always (`guardrails`, 40) | context |
+| c3 | Memory | `memory.md` | always (`memory`, 45) | context |
+| c4 | Tool guidance | `tool_guidance.md` | always (appended to the `tools` section) | tool interface |
+| c5 | Subagents | `sub_agents/<name>/AGENT.md` | own context; instruction-only agent profiles, listed with the other profiles in `subagents` (64, PROP-0029) | orchestration |
+| c6 | Skills | `skills/<name>/SKILL.md` (+ `scripts/`) | on demand, loaded by Pi as skills | context |
+| c7 | Scripts | `scripts/<name>.py` or `.mjs` | on demand, listed in `scripts` (66) | tool interface |
+| c8 | Plugins | `plugins/<name>.ts` | inside the tool loop, as Pi extensions | middleware |
+
+| Type / function | Module | Role |
+|---|---|---|
+| `Variant` (path → text), `SurfaceSpec`, `ComponentInfo` | `variant/surface.ts` | The editable surface and its patterns. |
+| `validate`, `readVariant`, `writeVariant`, `diffSummary`, `applyEdit`, `autotrigger` | `variant/variant.ts` | Validation and editing. |
+| `commit`, `seed`, `restore`, `head`, `lineage`, `fingerprint` | `variant/store.ts` | Versions and the head. |
+| `tag`, `untag`, `tags`, `resolveRef`, `revertComponents`, `selects` | `variant/store.ts` | Names for versions, references, and taking components back from an earlier version (PROP-0052). |
+| `materialise`, `resolve`, `VariantChoice`, `Materialised` | `variant/materialise.ts` | Turns a version into prompt sections, skill paths and extension paths for one run. |
+| `VariantTrust` | `variant/trust.ts` | Which plugin code a person trusted, by hash; which scopes let probes run improver code. |
+| `seedVariant` | `variant/seed.ts` | A first variant for a scope. |
+| component library | `variant/components.ts` | Reusable skills, prompts and rules under `registry/` and built-in folders. |
+
+## Contracts
+
+- **`VariantChoice`**: `{ scope, version? }` (a scope's head or one version) or `{ dir, scope? }`
+  (a variant on disk, read and never written, such as a refinement candidate).
+- **Version source** (`VersionSource`): `seed`, `edit`, `refinement`, `import`, `restore`.
+- **Tuned for**: a version made by adopting a refinement records `tunedFor: { model }`, the model its
+  execution ran on. It is written once with the version and never changed.
+- **Tags**: `name → fingerprint` per scope. A tag is a label that can move to another version; it
+  is not a version and never changes one. A tag cannot be `head` or look like a fingerprint.
+- **Reference** (`resolveRef`): a fingerprint, a unique prefix of at least four characters, a tag,
+  or `head`.
+- **Revert** (`revertComponents`): a new version made from the head with the selected components
+  replaced by an earlier version's. A selector is a component (`c1`–`c8` or its id) or one item by
+  path prefix (`skills/review`, `sub_agents/reader`, `scripts/check.py`, `plugins/guard.ts`). It is
+  committed with source `edit` and passes the validator like any edit.
+- **Fingerprint**: first 16 hex characters of SHA-1 over sorted `path\0text\0` pairs.
+- **Validation** (`validate`) refuses a variant when: always-on text (c1–c4) exceeds 24,000
+  characters; a file is off the surface; a skill lacks `description:` or its `name:` differs from
+  its folder; a skill is never named in the always-on text; a subagent lacks `description:`; a
+  script does not compile; a plugin has no default export; an always-on file or skill invokes a
+  script that is not in the variant.
+
+## Invariants
+
+- **INV-FND-1** Only a variant mutates. No edit, improver session or adoption changes foundation
+  code, the surface, the validator or an invariant; those change by release, with a proposal.
+- **INV-FND-2** A variant changes only by committing a new validated version (`commit` →
+  `validate`, `INV-VAR-2`), and a refinement moves a head only when a person adopts
+  (`INV-REF-6`). There is no other door.
+- **INV-VAR-1** Variant instructions are versioned per scope. The application adds its own sections through `Launch` (page 01). The release-owned `plugin-authoring` skill is also available on demand in structured and terminal sessions, including existing variants; its body is not always-on. A variant skill with the same name takes precedence. It is shipped as a package resource and does not mutate pinned versions.
+- **INV-VAR-2** Every saved version is validated (`commit` → `validate`). An invalid variant is
+  refused with every problem listed.
+- **INV-VAR-3** A version is never edited. A change is a new version; `restore` moves the head
+  and appends to `restores.jsonl`.
+- **INV-VAR-4** A run resolves its variant once and pins it; a child run uses the same files even if
+  the head moves. A child whose agent profile names another variant resolves and pins that one when
+  it starts (PROP-0029). A later turn of a conversation uses the conversation's selected version.
+  That changes only by the person's own action in that session (adopting, restoring, reverting or
+  choosing a version) and only at a turn boundary; a head moved elsewhere is never followed
+  (PROP-0052, ADR-0065).
+- **INV-VAR-5** c8 plugin code loads only when its exact text is trusted (SHA-256 in
+  `variant-plugin-trust.json`). A changed file asks again. The one exception: a refinement probe may
+  run improver-written code for a scope whose person allowed it (`probeCode`), and adopting that
+  variant still requires the code trusted.
+- **INV-VAR-6** The always-on cap exists because every always-on character costs every run.
+  Raising it is an architecture change.
+- **INV-VAR-7** Variant code is synchronous (`INV-BND-4`).
+
+## Data
+
+```text
+<data root>/variants/<scope>/
+  versions/<fingerprint>/variant/<rel>
+  versions/<fingerprint>/version.json
+  head.json
+  lineage.jsonl
+  restores.jsonl
+  tags.json                 name → fingerprint (PROP-0052)
+<state dir>/variant-plugin-trust.json
+<data root>/registry/{skills,prompts,rules}/   (component library)
+```
+
+## Source map
+
+`src/variant/*.ts` (`migrate.ts` renames state written before PROP-0009 on `open`). Method origin: Harness² (`harness2/core/tree.py`, Apache-2.0).
+
+## Terminal inspection
+
+`/variant` lists the scope's versions with their tags, source, and which one this conversation runs
+and which is the head. On a version it offers: switch this conversation to it, restore it as the
+head, compare it with the head, tag it, and take some components from it; `/variant
+use|restore|tag|untag|diff|revert` are the typed forms. Restoring, reverting or adopting switches
+this conversation at the next turn boundary (ADR-0065).
+
+The resource browser retains the materialised preparation snapshot and labels it pinned. The
+current scope head is separately labelled latest saved; browsing and comparison never rematerialise
+the head as the running variant. Directory-backed variants remain browse-only. Library additions
+use the existing validated commit door and affect future terminals.