@xingular/harness 2.0.0 → 2.0.1-unstable

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.

package/docs/architecture/proposals/PROP-0036-first-class-harness-commands.md

@@ -0,0 +1,59 @@
+---
+id: PROP-0036
+title: First-class Harness terminal commands
+status: Implemented
+created: 2026-10-25
+updated: 2026-10-25
+affects: [INV-PLG-10, INV-TUI-7, 06-plugins-and-capabilities.md, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0031]
+---
+
+# PROP-0036: First-class Harness terminal commands
+
+## Problem
+
+Harness-owned pages for subagents, agent profiles, recorded-run inspection, diagnostics and worktrees are currently exposed through `BuiltinPluginRegistry` command metadata. This couples their terminal command namespace and discoverability to a feature-plugin registry even though these required features are not optional plugin toggles. It also makes ordinary Harness commands appear as plugin commands in help and completion.
+
+Evidence: `src/plugins/builtin.ts` registers these commands on the `subagents`, `history`, `doctor` and `worktrees` modules; `src/terminal/tui/pluginCommands.ts` maps them to pages; `src/terminal/tui/commands.ts` builds canonical namespaced completion and dispatch from `BuiltinPluginRegistry`.
+
+## Affected rules
+
+- **INV-PLG-10** currently couples a built-in feature's descriptor, tools, server methods and terminal command metadata to one registry owner. Plugin-owned commands should remain with their feature modules, but Harness core commands should be owned by the terminal's core command registry.
+- **INV-TUI-7** requires every plugin-owned command to use an owner prefix. The commands in this proposal become Harness core commands, not plugin-owned commands; all other plugin and extension commands retain owner-qualified routes.
+- **14 Surfaces and parity, Contracts** describes the current terminal command namespace. The command changes are presentation only and add no capability or server method.
+
+## Proposal
+
+Register these routes directly in the core terminal command table and dispatch them to the existing Harness pages:
+
+- `/doctor` opens readiness diagnostics.
+- `/worktree` opens managed worktrees.
+- `/trajectory [run-id]` opens recorded runs and events.
+- `/subagents` opens the subagent roster; `/agents` opens agent profiles.
+
+Keep `/history` (and its `/tree` alias) for session branch navigation. Keep `/mcp` and `/connections` as first-class entries into the Connections browser. All other core commands stay unprefixed. Plugin-owned built-in and extension commands continue to use `/<owner-prefix>:<command>`; annotations retain their `annotate` namespace and default route.
+
+The `doctor`, `worktrees`, `history` and `subagents` feature descriptors remain registered and required. Their services, server methods, tools and capability behavior do not move. Only their terminal command metadata and dispatch move to the core command registry. Core commands reserve their names under the existing terminal command collision policy.
+
+For one release, accept the prior owner-qualified and `/plugin:<command>` forms for the routes being promoted as hidden compatibility aliases. Do not show aliases in help or completion. Remove them after the compatibility release.
+
+## Alternatives
+
+- Keep these routes under owner prefixes. Rejected: it keeps core terminal actions classified as plugin commands and exposes redundant namespaces for required Harness features.
+- Remove the feature descriptors from `BuiltinPluginRegistry`. Rejected: those descriptors still own Harness tools, server methods and capability contributions; only terminal command ownership needs to change.
+- Replace `/history` with the trajectory page. Rejected: `/history` already navigates the current session's branches. Keep it and expose the run trajectory as `/trajectory`.
+- Do nothing. Rejected: help, completion and dispatch continue to treat these core pages as plugin-owned commands.
+
+## Consequences
+
+Help, completion, slash recognition and dispatch use the core command table for the promoted commands. The `/mcp` command remains in that table and keeps its Connections behavior. Plugin command-prefix collision checks remain in force for plugin-owned commands. No capability set, server protocol, account data, run record or stored resource changes.
+
+## Migration
+
+No stored-data migration. Accept the previous qualified forms as hidden aliases for one release; scripts and keybindings should use the bare canonical names. `/history` remains the branch picker and `/trajectory` is the recorded-run page.
+
+## Checks
+
+- Registry and terminal tests cover bare routes, help, completion, slash recognition, compatibility aliases, prompt-name collisions, `/history`, `/mcp` and unchanged plugin namespace routing.
+- Harness `npm run typecheck`, `npm test` (150 files; 1,143 passed, 3 skipped) and `npm run prove` passed.
+- Xingular Agent `npm run typecheck`, `npm test` (App and sidecar suites: 634 passed; signing tests: 7 passed, 1 skipped), `npm run check:layers` and `cargo test` (167 passed, 1 ignored) passed.
+- Isolated terminal PTY checks passed for `/help`, composer modes, and the `/trajectory` Runs/Events page. `/help` screen-layout assertions were skipped because optional `pyte` is unavailable.

package/docs/architecture/proposals/PROP-0037-workspace-write-boundary.md

@@ -0,0 +1,63 @@
+---
+id: PROP-0037
+title: Default filesystem writes to the active project workspace
+status: Implemented
+created: 2026-11-19
+updated: 2026-11-19
+affects: [INV-GATE-1, INV-GATE-3, INV-GATE-8, INV-RUN-1, INV-TUI-8, 02-sessions-and-runs.md, 04-prompt.md, 07-tools-and-gate.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity]
+---
+
+# PROP-0037: Default filesystem writes to the active project workspace
+
+> **Implementation update:** This proposal records the original pathname-check and
+> denial-triggered-retry design. Security review found those details bypassable; accepted
+> [PROP-0039](PROP-0039-workspace-boundary-hardening.md) replaces them with operation-time atomic
+> writes and explicit pre-execution outside-scope approval. Follow the current contracts in
+> [07 Tools and the gate](../07-tools-and-gate.md) and [11 Terminal](../11-terminal.md).
+
+## Problem
+
+Harness tells the model that read-only file tools can use any path the process can read, and that the working folder is not a repository boundary (`src/prompt/compile.ts`; `docs/architecture/07-tools-and-gate.md`, Native file paths). The same page says `edit`, `write` and `bash` pass through the existing gate and policy, but that gate has no built-in workspace-root rule. The SDK's `ToolPolicy` is optional, and the terminal's default approval flow is not a filesystem sandbox (`src/sessions/policy.ts`, `src/sessions/sessions.ts`, `src/terminal/terminals.ts`). Thus a session has no Harness-wide default that keeps model-initiated file mutations in its project.
+
+## Affected rules
+
+- **INV-GATE-8**, as it stands: “Native read-only file access is bounded by process and operating-system permissions, not by the repository root. Absolute and `~` paths are valid inputs. This does not change the gate or permissions for writes and commands.” The first two sentences remain; the final sentence changes because the Harness will scope writes and shell file effects.
+- **INV-GATE-3**, as it stands: “Order is fixed: capability and plan-mode refusals, then the policy's scope and authorize, then standing approvals, then the person, then authorize again.” The mandatory workspace check must join this ordering without allowing a host policy to silently broaden it; an approved one-call escape must be authorized before the operation runs.
+- **INV-RUN-1**, as it stands: “A run pins one account, one variant version and one capability set when it starts. None of them changes during the run.” A run will also pin its resolved workspace-write root so a continuation or later filesystem change cannot silently widen its scope.
+- **INV-TUI-8**, added by implementation: the terminal uses the same Harness-pinned root and workspace-write policy as SDK sessions; it cannot widen the boundary through its private socket or native extension.
+
+## Proposal
+
+1. **Preserve broad reads.** Read-only filesystem tools retain their existing process/OS-permission behavior. The write boundary applies to model-controlled filesystem mutations, not to reads.
+2. **Resolve one trusted workspace root per run.** After Harness has selected the effective `cwd` (including a managed worktree), resolve the nearest ancestor containing `.git`, canonicalize it, and store it as `RunRecord.workspaceRoot`. If there is no Git repository, use the canonical `cwd`. A worktree is its own active workspace. Do not infer the root from model-supplied tool arguments or an unvalidated `projectId`.
+3. **Default file writes to that root.** Native `edit` and `write` calls may mutate paths inside the root. Resolve paths canonically and reject symlink/path escapes. Paths outside it require approval for that operation. A per-tool remembered grant does not authorize an outside write.
+4. **Enforce shell writes, not just shell-call names.** Run model Bash—including the initial `!` command—under an OS-enforced workspace-write sandbox. Shell commands may read as before but may write only under `workspaceRoot`; `/tmp` and other external paths are outside the default write scope. A denied outside write produces a clear denial and a one-shot escalation path for that command. Approval reruns only that command with the wider access needed. Fail closed when workspace-mode enforcement is unavailable; never silently run it unconfined.
+5. **Use existing approval controls.** Outside writes require a person’s one-call approval. Mark the request human-only so remembered grants cannot answer it. The existing Full Permission switch may automatically grant this explicitly eligible escape; it is off by default. Preserve hard policy denials and the existing read-only, plan, unattended, probe, improver and reflection restrictions. Full Permission does not add tools or bypass those restrictions.
+6. **Keep artifacts in the project by default.** Files created for the task, including deliverables, belong inside the active workspace. Prefer an existing project convention such as `artifacts/` or `outputs/` when present; do not require or create a universal output folder. An explicitly approved outside write remains possible.
+7. **Make the policy Harness-owned and shared.** Apply the same root and decision in SDK sessions and the standalone terminal. Host `ToolPolicy` may impose stricter limits, but cannot waive the Harness boundary except through the same explicit approval path. Connected-app and other non-filesystem side effects remain governed by their existing tool policies.
+
+## Alternatives
+
+- **Prompt-only “write in the repo” guidance.** Rejected: it expresses a preference but does not prevent absolute paths, symlink escapes or shell commands from writing elsewhere.
+- **Rely only on the host `ToolPolicy`.** Rejected: it is optional and host-specific, so terminal and embedded sessions could differ.
+- **Check only `edit`/`write` paths or parse Bash strings.** Rejected: shell commands can write through arbitrary programs, redirection, subprocesses and indirect paths; string inspection is not a reliable boundary.
+- **Allow all OS temp directories by default.** Rejected for this proposal: the requested default is project-only. A temp location outside the workspace needs the same approval as any other outside write.
+- **Do nothing.** Keeps the existing broad behavior and leaves repository scope to prompt guidance or host configuration.
+
+## Consequences
+
+- Add an optional, backward-compatible `workspaceRoot` field to `RunRecord`; new runs set it, old records remain readable, and continuations of older runs derive it from their recorded working directory. No separate workspace registry or output directory is introduced.
+- The native file tools and shell need different enforcement mechanisms: canonical target checks for file mutations and an OS sandbox for shell subprocesses. The same workspace policy and approval semantics must be used by SDK and terminal paths.
+- The `RunRecord` schema is returned over the server protocol, so embedding hosts and sidecar schemas must tolerate the additive field. The Harness remains responsible for computing it; a host cannot nominate an arbitrary wider root.
+- Workspace mode fails closed on unsupported or unavailable sandbox backends. A person can still explicitly authorize one outside operation, or use the existing Full Permission switch where permitted.
+- Standard commands that need to write outside the project (including to `/tmp`) may need an approved one-shot retry. Project-local artifact/output conventions continue to work without extra approval.
+
+## Migration
+
+No stored files are rewritten. Parsers accept older run records without `workspaceRoot`; a continuation derives the root from the earlier record's `workingDirectory` and stores it on the new run. New runs pin the effective root after worktree selection. Existing remembered tool grants remain stored but do not satisfy outside-write approvals. The current Full Permission switch remains off/on as configured; it is the only standing choice that may approve a boundary escape, and read-only or unattended facts continue to disable it.
+
+## Checks
+
+- Workspace resolution, canonical file-write inspection, session/terminal approvals and sandbox tests cover Git roots, worktrees, non-Git folders, symlink escapes, broad reads, remembered-grant rejection, eligible Full Permission, hard restrictions, fail-closed behavior and one-shot retries. Passed.
+- Harness `npm run typecheck`, full `npm test` (153 files; 1,167 passed, 3 skipped), and `npm run prove` passed on 2026-11-19.
+- The App sidecar contract verifies `runs.find` returns the pinned root. App `npm run typecheck`, `npm test` (571 renderer and 67 sidecar tests passed; 7 development-signing tests passed, 1 skipped), `npm run check:layers`, and `cd src-tauri && cargo test` (169 passed, 1 ignored) passed. Rust compilation emitted warnings.