@xingular/harness 1.0.0 → 1.2.0

package/docs/architecture/proposals/PROP-0030-subagent-title.md

@@ -0,0 +1,86 @@
+---
+id: PROP-0030
+title: A parent-set title for each subagent, shown in the roster
+status: Accepted; implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [02-sessions-and-runs.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, terminal-tui.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0030: A parent-set title for each subagent, shown in the roster
+
+## Problem
+
+A live subagent row shows the child's `session_name` once the child calls it successfully, and
+otherwise the whole brief (`subagentsWidget.ts`, `safe(item.name) || safe(item.goal)`). The brief
+can run to 4000 characters, so the row shows a paragraph of instructions cut to the terminal width.
+In a live run of two explorers, neither had a name, and both rows showed their briefs.
+
+The child is the only one asked to name itself. The "six words at most" rule is in the
+`session_name` tool description and the prompt, and nothing checks it. A child may skip the call,
+or its call may fail, and the row then shows the brief for the whole run. The parent, which wrote
+the brief, knows the purpose in a few words and names nothing.
+
+## Affected rules
+
+No invariant changes. The contracts that change are:
+
+- `spawn_subagent` (page 07): a `title` parameter. The model must supply it.
+- `subagents.spawn` (page 10): an optional `title`.
+- The run record (page 02): an optional `title`, stored like `profile` (PROP-0029).
+- The live roster and `/subagents` (page 11, `terminal-tui.md`): the row title is the parent's title.
+- Parity (page 14, `parity.md`): the Subagents row names the title, not the child's session name.
+
+## Proposal
+
+- `spawn_subagent` takes `title`, a required string: one short imperative of at most six words,
+  such as "Map the auth flow". It is checked the way `session_name` is: whitespace collapses, and
+  control characters and empty values are refused with a message the model can act on.
+- `subagents.spawn` takes an optional `title` with the same check. A host or script that omits it
+  gets `briefTitle(brief)`: the first non-empty line of the brief, collapsed and capped at 60
+  characters. The model cannot omit it.
+- The child run record stores `title`, an optional text field (`RunRecord.title`). The spawn sets it
+  before the child launches, and a startup failure keeps it. A record written before this change
+  has no title and reads as `briefTitle(goal)`.
+- The terminal roster, the `/subagents` label and its search read the title. The row no longer
+  reads the child's `session_name`. The child still names its own Pi session with `session_name`,
+  and that name stays in the child's session history.
+- The transcript's `spawn_subagent` row shows the title, and the brief only when no title is given.
+
+## Alternatives
+
+- **Require the child to name itself.** This is the current design. The child must be prompted,
+  and the rule is not checked. The screenshot shows it was skipped.
+- **Make `title` optional in the tool.** A model skips an optional field the same way it skipped the
+  child's name. Rejected: the tool requires it, and only programmatic callers may omit it.
+- **Generate the title with an extra model call.** It costs a call and adds latency to every spawn.
+  Rejected.
+- **Keep the child's name first, then the parent's title.** A child that names itself would still
+  replace the title the parent chose. Rejected: one source keeps the roster stable.
+- **Do nothing.** Rows keep showing briefs whenever the child does not name itself.
+
+## Consequences
+
+- Applications built on the harness get a new required argument in `spawn_subagent`, and an
+  optional one in `subagents.spawn`. A model that omits `title` gets an error and retries.
+- The run record gains an optional field. Readers that ignore unknown fields are unaffected. The
+  App reads run records in Rust and does not render the roster.
+- The terminal monitor drops the child's `name` field. Its tests change with it.
+
+## Migration
+
+No data moves. Records without `title` read as `briefTitle(goal)`. The change can be undone by
+removing the parameter; records written with `title` stay readable, because the field is optional.
+
+## Checks
+
+- `src/sessions/subagentService.test.ts`: the title is stored on the child run, and defaults from the
+  brief's first line when omitted. An over-long title is refused.
+- `src/tools/spawnSubagent.test.ts` (new): the tool refuses a missing or over-long title before it
+  starts a child, and cleaning and the brief fallback behave as stated.
+- `src/terminal/subagentMonitor.test.ts`: the row takes the parent's title, and the child's
+  `session_name` does not change it.
+- `src/terminal/opentui/subagentsWidget.test.ts` and `model.test.ts`: the row and the transcript row
+  show the title.
+- `npm run typecheck`, `npm test`, and `npm run prove` (the spawn path is server code), then the App's
+  checks, because a harness change requires them.

package/docs/architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md

@@ -0,0 +1,54 @@
+---
+id: PROP-0031
+title: Namespace plugin commands by owner
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [INV-TUI-7, 06-plugins-and-capabilities.md, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, README.md, ADR-0021, ADR-0031]
+---
+
+# PROP-0031: Namespace plugin commands by owner
+
+## Problem
+
+The terminal currently uses `/plugin:<command>` for optional built-in and Pi extension commands, but bare names for commands owned by required built-ins. The generic `plugin` prefix does not identify the owner and still requires global command-name collision handling. Annotation commands are exposed as `/plugin:annotate` and `/plugin:notes`, while the plugin is named `Page notes` despite supporting interactive web annotation.
+
+Evidence: `src/plugins/builtinRegistry.ts` selects `unprefixed` or `plugin` from `descriptor.required`; `src/terminal/tui/commands.ts` routes the single `plugin:<name>` namespace; Pi commands are grouped only by command name and `sourceInfo.path`.
+
+## Affected rules
+
+- **INV-TUI-7** currently says required built-in commands use unprefixed names and optional built-in/Pi extension commands use `/plugin:<command>`.
+- **14 Surfaces and parity, Contracts** currently says optional built-in and Pi extension commands use `/plugin:<command>`.
+- **ADR-0021** records bare required built-ins and the generic `/plugin:<command>` form. This proposal supersedes its command-namespace decision.
+
+## Proposal
+
+Every plugin-owned terminal command uses `/<owner-prefix>:<command>`, whether the owner is a required built-in, optional built-in, or Pi extension. Core terminal commands remain bare. Help, completion, dispatch, and duplicate diagnostics all use the same owner-qualified route. A collision is determined by the complete owner-prefix/command pair; different plugins may use the same command name.
+
+Built-in modules declare a stable command prefix (defaulting to a validated slug derived from the plugin id, with explicit overrides where the public slug differs). Pi package extensions use `harness.commandPrefix` when declared and otherwise a normalized package name; loose extensions use a normalized extension name. Prefix collisions between owners and duplicate commands within an owner are reported with their source paths rather than silently routed. The `skill:` namespace remains reserved for skill invocation.
+
+A built-in plugin module may declare a default terminal command for the owner root. The annotations plugin uses prefix `annotate`: `/annotate:` opens the capture pane, `/annotate:annotate` is an equivalent discoverable alias, and `/annotate:notes` opens the saved-annotations page. Its public plugin title becomes **Web annotations**. The stable plugin id, stored note schema, `annotations.*` methods, and `page_notes_*` tools do not change.
+
+For one release, retain the existing `/plugin:<command>` forms and prior bare required-plugin forms as compatibility aliases when they still resolve unambiguously. These aliases are not shown in help or completion. Core commands keep precedence. Prompt templates and `/skill:<name>` keep their existing behavior.
+
+## Alternatives
+
+- Keep `/plugin:<command>` and only rename the annotations plugin. This leaves plugin ownership hidden and preserves a global collision surface.
+- Namespace only optional plugins. This retains two command rules and leaves required plugin commands able to collide with core or prompt names.
+- Use each plugin's display title as its prefix. Titles are presentation and can change; route identity must remain stable.
+- Do nothing. The generic prefix and current naming ambiguity remain.
+
+## Consequences
+
+The terminal command contract and `BuiltinPluginRegistry` metadata change. A plugin package may optionally declare `harness.commandPrefix`; packages without the field continue to work with a normalized source-derived prefix. No server method, capability set, data root, stored note, or run record changes. Host surfaces continue to use Harness methods; the Web annotations title is part of `plugins.list` metadata.
+
+## Migration
+
+New commands become owner-qualified. Existing generic and bare forms remain temporary aliases for one release, without appearing in completion or help. Scripts and keybindings should migrate to the owner-qualified forms. Removing the aliases later requires a release note; no stored-data migration is needed.
+
+## Checks
+
+- Registry and terminal tests cover prefix validation, owner-qualified routing, default plugin roots, aliases, extension identity, collisions, help, and completion.
+- Annotation tests cover `/annotate:`, `/annotate:annotate`, `/annotate:notes`, and the Web annotations title.
+- Run Harness typecheck, tests, and `npm run prove`.
+- Run Xingular Agent typecheck, tests, layer checks, and Rust tests; inspect terminal completion and the host's annotation/plugin presentation.

package/docs/architecture/proposals/PROP-0032-planning-quality.md

@@ -0,0 +1,196 @@
+---
+id: PROP-0032
+title: Evidence-grounded planning with read-only research delegation
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [02-sessions-and-runs.md, 06-plugins-and-capabilities.md, 07-tools-and-gate.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0032: Evidence-grounded planning with read-only research delegation
+
+## Problem
+
+Plan mode has a strong read-only gate and a usable terminal handoff, but its instructions describe
+only broad research, a UI-specific set of directions, and a loose output shape. They do not require
+plans to ground code claims in inspected sources, map the requested outcomes to actionable steps,
+resolve user-owned choices without asking about discoverable facts, or handle revisions as complete
+replacement plans. Plan mode also forbids delegation entirely, so substantial investigations cannot
+use the existing `explorer` profile to research in parallel; it has an explicit no-write tool list,
+but no plan-specific plugin restriction, and there is no built-in `researcher` profile. The
+instruction to explore “typically 3–5” UI directions also pushes ordinary UI implementation requests
+toward unnecessary design alternatives. Verification is requested but not defined as concrete checks
+with expected results.
+
+Evidence: `src/sessions/planMode.ts` defines `PLAN_INSTRUCTIONS`; `src/sessions/planMode.test.ts`
+checks prompt phrases and parser mechanics but does not measure plan quality. The binding summary in
+`docs/architecture/02-sessions-and-runs.md` currently says UI plans explore distinct design directions,
+compare trade-offs and recommend one. This differs from the stronger planning rubric in the checked-
+out oh-my-pi prompt (`external/omp/packages/coding-agent/src/prompts/system/plan-mode-active.md`):
+“Plan: execution spec, not design doc,” and “Every asserted path, symbol, signature, behavior:
+actually read this session.” Adopt those principles, not its plan-file/approval mechanics. OpenCode's
+checked-out plan plugin primarily defines role and read-only constraints; DeepSeek Harness leaves the
+planning guidance deployment-defined. Neither provides the same detailed planning rubric.
+
+## Affected rules
+
+- `02-sessions-and-runs.md`, Plan mode: “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.” Replace the default multiple-directions
+requirement with conditional, user-requested or materially useful alternatives.
+- `INV-RUN-8` changes narrowly: an attended plan may use the existing subagent tools for bounded
+research when subagents are in the frozen caller capability set, and only with an eligible
+read-only profile. Plan refusals—including profile eligibility—remain before policy and approvals.
+The plan remains read-only with this limited run-lifecycle exception; it gains no repository or
+world-write capability. The stable system prompt remains unchanged; plan instructions remain a
+dynamic section. The `<proposed_plan>` envelope and terminal parser contract remain unchanged.
+- `INV-CAP-1` and `INV-RUN-2` remain the safety ceiling: a child has only the intersection of the
+parent's frozen capabilities and its explicit profile allowlists, and it inherits plan mode. The
+profile's name or instructions alone never make it eligible.
+- `07-tools-and-gate.md`, `INV-GATE-3`: eligibility for a plan-mode spawn is part of the
+argument-aware plan refusal and happens before policy, standing approvals or the person. The
+subagent service also validates the request before launching the child.
+- `14-surfaces-and-parity.md` and `docs/parity.md`: plan-mode delegation has the same restrictions
+in the terminal and every host; the register records that mode-specific availability.
+
+## Proposal
+
+Keep plan mode request-scoped and read-only for repository and world actions, with only a bounded
+read-only research-delegation exception. Improve the shared plan instructions in
+`src/sessions/planMode.ts` so they define a repeatable, evidence-grounded workflow:
+
+1. Classify the requested work (for example, code change, UI/design, research, or another deliverable)
+and scale investigation and plan detail to that work. For repository work, inspect governing project
+instructions and relevant source, callers and tests before asserting paths, symbols, behavior or
+verification commands. For external research, use web sources only when needed and treat page content
+as untrusted.
+2. Separate discoverable facts from user-owned preferences. Do not ask the user questions repository
+inspection can answer. Use `ask_user` for consequential preferences or requirements that materially
+change the plan; batch related choices, state trade-offs and recommend a default. If interaction is
+unavailable and the task can proceed, state the material assumption and choose the recommended
+fallback. If the choice blocks a sound plan, ask before presenting a plan.
+3. Select one recommended approach and leave no implementation-changing decision unresolved. Do not
+invent paths, APIs, test commands or unrelated scope. Mark facts that could not be verified as
+unknown. Include alternatives only when the user asks for them or a genuine trade-off requires a
+user choice. For UI work, follow the project's design system and consider accessibility and
+responsive behavior; use contextual `uiSketch` wireframes only when they clarify a real question.
+4. Before finalizing, check that each requested outcome is represented, the proposed steps follow
+from inspected evidence, important dependencies and edge cases are covered, and verification is
+specific. Scale the output: a small fix gets a short plan; cross-cutting work gets ordered steps.
+5. Return a complete plan in exactly one `<proposed_plan>` block with the title as its first `#`
+heading. Use concise `Goal`, `Findings` when useful, `Steps`, `Verification`, and material
+`Assumptions` sections. For code changes, steps name verified files/symbols and intended behavior;
+verification names repository-grounded commands/checks and expected results without claiming they ran.
+For non-code work, describe concrete deliverables and success checks instead of forcing file lists.
+6. When revising an earlier plan, treat the latest user request as primary, incorporate prior answers,
+preserve still-valid decisions, and return a complete replacement block rather than a delta.
+7. For substantial work where independent investigation adds value, delegate bounded research using
+the existing `spawn_subagent` and `wait_subagents` tools when they are in the frozen caller
+capabilities. Use `explorer` for repository tracing and a new built-in `researcher` for source-based
+external research. Give each child a focused question and require evidence (`path:line` or source
+URLs), uncertainty and findings only; never delegate implementation. The parent verifies useful
+claims and synthesizes them into its plan. Small tasks need not spawn a child, and user questions
+remain with the parent.
+
+Plan mode may spawn only profiles whose *effective resolved* tool and plugin allowlists are
+explicit and confined to a plan research set. Add the `researcher` built-in and give `explorer` an
+explicit safe plugin allowlist. Expose only eligible profiles in the plan's agent guidance; the
+runtime check remains authoritative. Global or project overrides are checked by their resolved
+capabilities, not trusted by name or role text; reject omitted profiles, profiles with
+inherited unbounded allowlists, and profiles that include write/edit/Bash, connected-app actions or
+other non-research capabilities. The gate makes this an argument-aware plan refusal before approvals;
+the shared subagent service rechecks it before launch. A child keeps `plan: true`, remains within
+the parent's frozen capability ceiling, cannot ask the user or spawn nested agents, and receives
+only the intersection of parent tools/plugins, the profile allowlists and the plan research set.
+`wait_subagents` can collect only the resulting eligible child work. Existing automatic join and
+result-delivery behavior remains in force.
+
+Keep the existing PlanCard's implement/edit behavior and same-session handoff. Reuse the existing
+subagent methods, records and lifecycle; add no public server methods, writable plan files, new
+approval tool, persistent plan state, or application-specific behavior. The mode-specific tool-set
+exception is limited to eligible research delegation; it does not permit arbitrary profiles or
+writes. Keep the plan section dynamic; increase its character budget from 2,000 to 4,000 only to fit
+the richer instructions, and test that the compiled section is not cut.
+
+Evaluate plan quality in the separate Evaluation repository, not by treating prompt-string assertions
+as proof. Add a small representative planning task set and a rubric for source grounding, request
+coverage, decision quality, actionability, verification and calibrated use of alternatives/questions.
+Use deterministic checks where possible and blinded semantic review for qualities a keyword grader
+cannot establish. Evaluation task/grader paths and adapter support for `plan: true` must be inspected
+before selecting implementation points. Any changed task or grader must receive the required suite or
+grader version bump. Compare current and candidate prompts on the same tasks, model, effort and tools;
+run live trials only with explicit credential/model selection and authorization.
+
+## Alternatives
+
+- **Make only a short wording edit.** Rejected: it could remove the UI bias but would not define
+  evidence grounding, revision behavior, decision-completeness or how to measure improvement.
+- **Copy oh-my-pi's plan workflow wholesale.** Rejected: it depends on writable `local://` plan files,
+  plan-file editing and `xd://propose` approval. This Harness prohibits those actions in plan mode and
+  already carries the proposed plan in session history for its PlanCard handoff.
+- **Add a plan file, new approval tool or persisted plan lifecycle.** Deferred: these introduce new
+  behavior/state and are not needed to improve plan quality with the current handoff. Reconsider only
+  if controlled evaluations show the existing history-based handoff is insufficient.
+- **Keep 3–5 UI directions as the default.** Rejected: alternatives are useful for explicit design
+  exploration or genuine preference decisions, not as a routine precondition for implementing a
+  clear UI request.
+- **Allow every subagent profile in plan mode and rely on prompt wording.** Rejected: profiles can
+  be overridden and may inherit the parent's full tool/plugin set; a prompt is not an enforcement
+  boundary.
+- **Allow only profiles whose names are `explorer` or `researcher`.** Rejected: a global or project
+  profile can replace either name with broader capabilities. Eligibility must be checked against the
+  effective explicit allowlists, with the plan gate and child capability intersection as enforcement.
+- **Do not allow delegation in plan mode.** Rejected: independent read-only research can improve
+  coverage on substantial plans without granting implementation capability.
+- **Do nothing.** Rejected: the current tests cannot detect unsupported claims, missing requested
+  outcomes, vague verification or unnecessary alternatives.
+
+## Consequences
+
+The plan-mode prompt becomes more prescriptive only while planning; its dynamic-section delivery
+continues to leave the stable system prompt unchanged. Plan responses become more consistently
+structured, while retaining the existing title/tag parser and PlanCard. Both the SDK and terminal
+use the shared instructions and enforce the same profile eligibility before approvals. When the
+parent already has subagent capability, a plan may create ordinary child-run records for eligible
+read-only research; no child can gain tools beyond the parent's frozen set, and plan-mode refusals
+still prevent writes and commands. The terminal and App expose the same conditional behavior, with
+no host-only capability or presentation change. Existing saved histories, run records and old
+`<proposed_plan>` blocks remain readable; no storage or public protocol schema changes. Planning
+runs carry a larger dynamic section (up to 4,000 characters).
+
+The Evaluation repository will gain versioned planning tasks and grading, including a case where
+research delegation is useful and the parent must verify evidence. Its benchmark results are
+separately versioned and are not product behavior. The Xingular Agent application requires no
+presentation change unless evaluation identifies a genuine surface gap.
+
+## Migration
+
+No stored-data migration. Reuse the current subagent run records and methods; no server protocol or
+capability schema migration is required. Preserve the opening and closing `<proposed_plan>` tags and
+first-level title heading so old and new plans remain parseable. Existing plans are not rewritten;
+revisions produce a new complete block in the existing conversation. The plan-mode tool set and
+argument-aware refusal behavior change only as described above; all other approval behavior remains
+unchanged.
+
+## Checks
+
+- Harness tests cover the revised prompt contract, section budget/no-cut behavior, dynamic
+delivery/withdrawal, plan revisions and structured-plan parsing. Add profile and subagent cases for
+eligible built-ins, disabled parent capabilities, omitted/unsafe profiles, global/project overrides,
+child inheritance of `plan: true`, strict child tool/plugin intersection, blocked write/command
+attempts before approvals, non-nested delegation and result delivery. Exercise the same eligibility
+and refusal behavior through SDK and terminal plan runs. Run Harness typecheck and tests.
+- After acceptance, update `docs/architecture/02-sessions-and-runs.md`,
+`docs/architecture/06-plugins-and-capabilities.md`, `docs/architecture/07-tools-and-gate.md`,
+`docs/architecture/14-surfaces-and-parity.md` and `docs/parity.md` in the implementation change.
+Confirm both surfaces display and enforce the same mode-specific restriction.
+- In Evaluation, add representative planning scenarios, including a research task where delegation
+is useful and a case where it is not; grade evidence verification and verify that no child performs
+writes. Version the suite/grader as required. Verify the adapter launches a real plan-mode run and
+retains native tool/output evidence.
+- Run a controlled baseline/candidate pilot with the same explicitly selected model, provider,
+effort, tools and tasks; use repeated trials and blinded review. Do not call it a passing baseline
+until complete. Live requests require explicit authorization and credentials. No live model comparison
+was run for this implementation; it remains pending explicit model/credential selection and authorization.
+- After a Harness implementation, run its required checks and the Xingular Agent checks. For
+Evaluation runner/grader changes, run its offline dependency and unit-test commands.

package/docs/architecture/proposals/PROP-0033-compaction-plan-checkpoints.md

@@ -0,0 +1,75 @@
+---
+id: PROP-0033
+title: Rehydrate bounded run checkpoints after compaction
+status: Accepted
+created: 2026-10-25
+updated: 2026-10-25
+affects: [INV-PRM-1, INV-PRM-4, INV-RUN-8, 02-sessions-and-runs.md, 04-prompt.md, 11-terminal.md, 14-surfaces-and-parity.md, ADR-0032]
+---
+
+# PROP-0033: Rehydrate bounded run checkpoints after compaction
+
+## Problem
+
+Pi keeps the native transcript when it compacts context, but the model receives a summary and
+recent messages. A run's latest checklist is already persisted as `checklist.updated`, and
+continuations restore it, but the active run does not put that state back into model context after a
+successful compaction. Dynamic plan instructions can likewise be summarized away during an SDK
+run. This can leave an unfinished task without a reliable current step or planning contract.
+
+## Affected rules
+
+- **INV-PRM-1:** “The prompt is assembled only in `src/prompt/compile.ts`. Nothing else builds
+  model instructions.” The checkpoint must use that compiler.
+- **INV-PRM-4:** “An update carries only changed dynamic sections, so an unchanged turn appends
+  nothing. A compaction on the active branch forces the full snapshot again.” This proposal adds
+  rehydration inside an active run, before its next model request.
+- **INV-RUN-8:** Plan-mode tools and gate restrictions stay unchanged; checkpointing must not widen
+  the callable set or change the stable system prompt.
+
+## Proposal
+
+- Add a foundation-owned Pi extension, used by both `Sessions.run` and the Harness terminal. It
+  observes successful checklist tool results and the active request, and detects compaction through
+  the model-context projection.
+- After compaction, on each model request while that run remains active, append one ephemeral,
+  hidden context message compiled by `src/prompt/compile.ts`. It contains the bounded user request,
+  the latest validated checklist (including current and pending items), and current plan-mode
+  instructions when applicable. Continuations may seed it from their already persisted checklist.
+- Do not persist the checkpoint as another session entry or run event. Keep it scoped to the active
+  request, clear its in-memory state when that run settles or the branch changes, and never include
+  hidden reasoning. The existing native transcript, `checklist.updated` event and continuation
+  behavior remain the durable records.
+- Keep all authorization in the existing plan-mode gate. The checkpoint only restores context; it
+  grants no tools or permissions.
+
+## Alternatives
+
+- **Rely on the compaction summary to retain progress.** Rejected: the summarizer is probabilistic
+  and may omit exact checklist state or dynamic plan instructions.
+- **Add a checkpoint side file or run-event type.** Rejected: the run already records its checklist,
+  and an additional durable format would duplicate state and require protocol migration.
+- **Persist a custom context message after every compaction.** Rejected: it would remain in future
+  requests after the active run ended. An ephemeral context projection keeps the checkpoint
+  request-scoped.
+- **Do nothing.** Rejected: a bounded state checkpoint improves recovery without retaining the full
+  conversation in model context.
+
+## Consequences
+
+After compaction, each model request in the active run receives the checkpoint again; this adds a
+bounded amount of input until the run settles. There is no model call, run-event schema, public
+method, storage-layout, or stable-prefix change. Both the terminal and embedding sessions use the
+same compiler and checkpoint semantics. Existing application event validators require no update.
+
+## Migration
+
+None. Existing run events and native session histories remain readable. Runs without a checklist or
+active plan context receive no checkpoint. Interrupted-run continuation continues to use its
+existing dynamic continuation section.
+
+## Checks
+
+Test the compiler's bounds and content, active compaction detection, per-request reinjection,
+checklist updates, plan instruction restoration, and state clearing. Run Harness `npm run typecheck`,
+`npm test`, and `npm run prove`, then the Xingular Agent App checks required for a Harness change.

package/docs/architecture/proposals/PROP-0034-conversation-fast-mode.md

@@ -0,0 +1,120 @@
+---
+id: PROP-0034
+title: Conversation-scoped provider fast mode
+status: Proposed
+created: 2026-10-25
+updated: 2026-10-25
+affects: [INV-RUN-1, INV-RUN-3, INV-PAR-1, INV-PAR-2, 02-sessions-and-runs.md, 09-accounts-and-connectors.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity, App thread runtime settings]
+---
+
+# PROP-0034: Conversation-scoped provider fast mode
+
+## Problem
+
+People cannot request a provider's native priority/fast service for a conversation without changing
+models or reasoning effort. Adding a UI-only flag would not reach Pi's provider request, and
+forwarding an unchecked option would send unsupported fields to APIs that do not implement it.
+The terminal and App must agree on the setting, restore it with the conversation, and explain when
+the selected provider/API/model cannot honor it.
+
+Evidence: Pi 1.2.0 exposes `serviceTier` for OpenAI Responses and Codex Responses requests. The
+Anthropic SDK exposes `speed: 'fast'` for beta Messages; Anthropic documents the eligible Claude
+models and the preview beta requirement at
+https://platform.claude.com/docs/en/build-with-claude/fast-mode. The existing Harness terminal has
+a persistent Pi history branch, while the App stores `ThreadRuntimeSettings` with each conversation
+and passes `SessionRunInput` through its sidecar.
+
+## Affected rules
+
+- **INV-RUN-1** currently says: “A run pins one account, one variant version and one capability set
+  when it starts. None of them changes during the run.” The selected service tier must also be fixed
+  for the whole run; it must not alter the model or effort.
+- **INV-RUN-3** currently says: “Every run event is validated against its schema, redacted,
+  persisted, and only then relayed to listeners, in order.” A provider rejection that disables fast
+  mode needs a validated event so both surfaces can persist the conversation setting as off.
+- **INV-PAR-1** requires every host capability to be a Harness capability surfaced by the terminal.
+- **INV-PAR-2** requires both terminal and host surfaces to pass acceptance for a capability.
+
+## Proposal
+
+Add an optional `fastMode` boolean to `SessionRunInput`, defaulting to `false`. A run captures this
+value at start and uses the same value for all model requests in that run. The option changes only a
+provider-native request parameter; it never changes the selected model, reasoning effort, prompt, or
+tool set. Fast mode is an attended conversation setting; automated, refinement, reflection,
+subagent, and side-question runs do not inherit it implicitly.
+
+Use a conservative, explicit provider capability map based on the resolved model's provider, API,
+model id, and endpoint:
+
+- OpenAI Responses and Codex Responses use their native `service_tier: 'fast'` option.
+- Eligible Anthropic Messages models use `speed: 'fast'`; preview models also receive the required
+  fast-mode beta header, composed with any existing headers and Pi payload hooks.
+- Only documented model/API combinations on verified official endpoints are supported. Unknown
+  APIs, custom endpoints, proxies and other providers are unsupported until verified. The model
+  capability response reports both support and a short reason when unavailable.
+
+Unsupported combinations never receive a fast request. Attempting to enable the setting leaves it
+off and explains why. Selecting an unsupported model while fast mode is on turns the setting off
+with an explanation. If a provider explicitly rejects the fast/priority option after a supported
+request was sent, do not retry at standard priority: surface the provider error, emit a validated
+`fast_mode.disabled` run event, and disable fast mode for later requests in that conversation.
+
+Persist the conversation setting at the owning surface:
+
+- The terminal writes an invisible custom entry to Pi's native history branch. New sessions start
+  off; resumed sessions and branch navigation restore the last setting on that branch. A failed
+  fast request appends the off state to the branch.
+- The App adds `fastMode` to its existing per-thread `ThreadRuntimeSettings` and passes it with each
+  run. Missing values in older thread files mean off. The App handles `fast_mode.disabled` by
+  saving the setting as off.
+
+Expose `/fast`, `/fast on`, and `/fast off` in the terminal and App composer. The App also offers a
+Fast on/off row in the existing thread Account/Model/Effort settings popover. The terminal status
+line shows a shimmering `⚡ fast` immediately after effort when enabled. Both surfaces explain that
+fast mode may cost more and does not guarantee lower latency. New conversations default off; resume
+restores the existing conversation setting.
+
+The account model capability response gains `fastModeSupported` and an optional explanatory reason
+so the App can disable the setting before a request. No new Harness storage directory or run-record
+file is added; the terminal setting uses native Pi history, the App setting uses its existing thread
+record, and the rejection event uses the existing run event store.
+
+## Alternatives
+
+- **Do nothing.** This avoids a new provider option but leaves no supported way to request native
+  priority.
+- **Change model or effort to imply fast mode.** Rejected: those are independent user choices and
+  would not select the provider's priority service.
+- **Forward a generic priority field to every provider or proxy.** Rejected: support and semantics
+  are API-specific, and an unknown endpoint must not receive an unverified option.
+- **Retry at standard priority after rejection.** Rejected: this hides the provider's error and
+  changes the requested service without consent.
+- **Keep the setting only in the App.** Rejected by INV-PAR-1/2: the terminal must offer the same
+  conversation capability.
+
+## Consequences
+
+`SessionRunInput`, the model-capability response, and the run-event schema change. The terminal,
+App sidecar, App thread settings UI, and both surfaces' command handling change. No prompt compiler,
+model-selection, effort-selection, or tool-gate behavior changes. Because fast mode can cost more,
+the UI must disclose that; no latency improvement is promised. A provider error remains visible and
+is not hidden by a normal-priority retry.
+
+## Migration
+
+No native-history or App thread migration is required. A missing terminal custom entry and a missing
+App `fastMode` field both mean off. Existing provider and run-event readers remain compatible with
+old records; the App's run-event schema must be updated before it consumes the new event. Resuming a
+conversation restores its setting; starting a separate conversation defaults off.
+
+## Checks
+
+- Unit tests for provider/API/model/endpoint support and native request-option composition, including
+  preserving Anthropic reasoning-summary hooks and headers.
+- Harness tests for preflight rejection, per-run stability, provider rejection without standard-tier
+  retry, validated disable events, and terminal setting persistence across resume/fork/navigation.
+- App tests for legacy thread defaults, persistence, capability gating, `/fast`, the settings row,
+  and handling `fast_mode.disabled`.
+- Run Harness `npm run typecheck`, `npm test`, and `npm run prove`; App `npm run typecheck`,
+  `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`; exercise the terminal status
+  line in a local PTY. Do not make live-provider requests as part of these checks.

package/docs/architecture/proposals/PROP-0035-retain-subagent-status.md

@@ -0,0 +1,47 @@
+---
+id: PROP-0035
+title: Retain terminal subagent status until the next run
+status: Implemented
+created: 2026-10-25
+updated: 2026-11-19
+affects: [11-terminal.md, terminal-tui.md]
+---
+
+# PROP-0035: Retain terminal subagent status until the next run
+
+## Problem
+
+The terminal shows subagent descendants under the working status line and in `/subagents:subagents`, but removes them when the parent run settles. The terminal specification says finished rows remain only until the parent settles. This makes the final child statuses unavailable during the idle interval before the next run, even though the terminal itself remains open.
+
+Evidence: `src/terminal/controller.ts` clears the volatile `SubagentMonitor` in `finish()` and `subagentSnapshot()` returns an empty list without an active run. `src/terminal/opentui/app.ts` polls only during an active run and clears its local rows on `agent_settled`. The current retention boundary is documented in `docs/architecture/11-terminal.md` and `docs/terminal-tui.md`.
+
+## Affected rules
+
+- `docs/architecture/11-terminal.md` currently says: “Finished rows remain until the parent run settles. The projection is volatile and scoped to that parent run; it is not a persisted event or public server method.”
+- `docs/terminal-tui.md` currently says the projection “keeps finished child rows until that parent settles.”
+
+## Proposal
+
+Retain the latest parent run's subagent projection in the terminal after that parent settles. Keep showing the compact rows and the `/subagents:subagents` roster, with each child's final known status, until the next parent run starts. At the next run's start, clear the old projection before displaying that run's children. A final settlement read should capture child states that the periodic monitor poll has not yet reflected; overlapping or late reads must not replace data from a newer run.
+
+The projection remains volatile, read-only, and limited to the existing redacted fields. It is scoped to the latest parent run for the current terminal session, and is cleared when the session is replaced or the terminal is disposed. It remains neither a persisted event nor a public server method. No run-event schema, storage, or host API changes.
+
+## Alternatives
+
+- **Do nothing.** The last statuses remain unavailable once the parent settles.
+- **Retain only the frontend's last poll.** This can leave a child marked active after it has completed because monitor updates may fall between one-second polls.
+- **Persist a separate status snapshot.** Rejected: the requested lifetime is only until the next run, and retaining the existing volatile projection is sufficient.
+
+## Consequences
+
+The terminal monitor and presentation retain one run's already-redacted subagent rows while idle. The next run replaces them. Other Harness capabilities and the App surface are unchanged. There is no new persistent data, migration, public method, or event contract.
+
+## Migration
+
+None. Existing terminals clear their in-memory monitor on restart; the new behavior applies to runs observed by the updated terminal process.
+
+## Checks
+
+- Harness `npm run typecheck`, `npm test` (150 files; 1,141 passed, 3 skipped), focused terminal tests (61 passed), `npm run build`, and `npm run prove` passed.
+- App `npm run typecheck`, `npm test` (567 App and 67 sidecar tests passed), `npm run check:layers`, and `cd src-tauri && cargo test` (167 passed, 1 ignored) passed.
+- The initial full PTY run failed waiting for `1 of 1` in its plan-question flow, and `--questions-only` failed waiting for `UI layout`. After the question-dock/layout fixes, `python3 scripts/verify-terminal.py --cli dist/cli.js --sizes 40x20,80x24,100x30` passed 19 interaction groups at each size with the tty restored (2026-11-19). Focused unit and real-socket tests cover subagent retention. No real-model request was made.