@xingular/harness 1.0.0 → 1.2.0

package/docs/decisions/ADR-0018-builtin-feature-plugins.md

@@ -0,0 +1,35 @@
+# ADR-0018 — Built-in feature modules and namespaced commands
+
+Status: Accepted (owner requested implementation of the plan, 2026-10-24).
+Related: [PROP-0020](../architecture/proposals/PROP-0020-builtin-feature-plugins.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md),
+[11 Terminal](../architecture/11-terminal.md).
+
+## Context
+
+First-party plugin descriptors existed, but runtime assembly, server handlers and TUI command
+dispatch were centralized in separate files. Plugin commands shared the same unprefixed namespace
+as core commands. Duplicate Pi extension commands were silently assigned suffixes by the SDK.
+
+## Decision
+
+Use a typed internal registry for built-in plugin modules. Modules own their existing plugin
+descriptor and may supply world parts, public method handlers, terminal command metadata and
+lifecycle. Foundation keeps plugin loading and trust, capability attachment and gating, the TUI
+framework, and the generic isolated browser engine. Plugin commands use `/plugin:<command>`;
+duplicate names are rejected with owner diagnostics. The ownership taxonomy is documentation only.
+
+Retire old unprefixed forms for doctor, worktree, trajectory, subagents, notes and annotate at the
+cutover. Public server methods and stored data keep their current names and shapes.
+
+## Alternatives
+
+Keeping direct central dispatch preserves the current drift between plugin descriptions and
+runtime ownership. Exposing categories in public metadata adds a schema without a runtime need.
+Letting the SDK suffix duplicate commands makes their identity depend on extension load order.
+
+## Consequences
+
+New Harness-managed features register through the built-in plugin registry. The terminal owns the
+page adapter and UI; feature plugins contribute namespaced command metadata. Embedding hosts see
+the existing method table and capability contracts.

package/docs/decisions/ADR-0019-managed-git-worktrees.md

@@ -0,0 +1,31 @@
+# ADR-0019 — Managed Git worktrees are a Harness capability
+
+Status: Accepted (owner approved the parity plan, 2026-10-23).
+Related: [PROP-0016](../architecture/proposals/PROP-0016-managed-worktrees.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Worktrees isolate source changes, but an App-only implementation leaves terminal users without
+that capability and lets each host invent its own lifecycle and safety rules.
+
+## Decision
+
+The Harness owns the worktree registry, lifecycle, session leases, and server methods. Managed
+worktrees are disposable detached checkouts in device-local state; permanent worktrees are retained.
+Creating a worktree disables repository filters, carries source changes only under the defined
+copy/apply rules, and runs setup scripts only after exact-text trust. Leases prevent concurrent
+removal; removal snapshots recoverable work before deleting a checkout. Hosts call `worktrees.*`
+rather than managing these records independently, and the terminal provides the reference surface.
+
+## Alternatives
+
+Keeping the feature in the App breaks terminal/host parity. Putting large worktree checkouts inside
+source repositories pollutes them and makes the data visible to tools and editors. Platform-specific
+copy-on-write clones were deferred in favor of Git's portable linked-worktree behavior.
+
+## Consequences
+
+`worktreeId` identifies a Harness-managed worktree in a run. Worktree state is device-local under
+the Harness state directory. Hosts can present richer controls but do not own lifecycle or safety.

package/docs/decisions/ADR-0020-page-annotations.md

@@ -0,0 +1,37 @@
+# ADR-0020 — Page annotations and delivery are Harness-owned
+
+Status: Accepted (owner approved the parity plan and capture workflow, 2026-10-23).
+Related: [PROP-0017](../architecture/proposals/PROP-0017-page-annotations.md),
+[PROP-0018](../architecture/proposals/PROP-0018-annotation-queue-and-app-targets.md),
+[07 Tools and the gate](../architecture/07-tools-and-the-gate.md),
+[13 World tools](../architecture/13-world-tools.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Page annotations and the agent's ability to read or act on them must work in both the standalone
+terminal and embedding hosts. Keeping the note store and tools inside one host would split state and
+behavior; trusting arbitrary page-script output could let a page initiate unintended work.
+
+## Decision
+
+The Harness owns the canonical note store, sharing grants, page-note tools, queue and delivery
+lifecycle, and generic capture contract. The terminal captures in its visible isolated browser; a
+host supplies its own web-view or application-window adapter through the same contract. Capture
+results are trusted only when they come from an isolated script world or the host's own UI; otherwise
+sending requires person confirmation. Page-derived content remains untrusted in the delivered
+instruction. A person controls sharing, queueing, confirmation, and resolution; the agent may mark a
+shared note fixed but cannot resolve it or change grants.
+
+## Alternatives
+
+A terminal-only capture path would not support host web views. Host-owned stores and tools would
+create different behavior and duplicated data. Trusting page content or automatically sending
+unisolated results would grant a page authority it must not have.
+
+## Consequences
+
+Notes and grants have one Harness-owned representation and work through the terminal or a host.
+Hosts retain ownership of native windows and browser UI while using Harness methods for notes,
+sharing, and delivery. The server contract can represent capture targets without naming an
+application.

package/docs/decisions/ADR-0021-required-command-namespaces.md

@@ -0,0 +1,40 @@
+# ADR-0021 — Required built-in commands use the bare namespace
+
+Status: Superseded by [ADR-0031](ADR-0031-plugin-command-owner-namespaces.md).
+Supersedes: The command-namespace portion of [ADR-0018](ADR-0018-builtin-feature-plugins.md).
+Related: [PROP-0021](../architecture/proposals/PROP-0021-command-namespaces-and-duplicates.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+The terminal has a set of required built-in features whose pages are part of normal Harness use.
+Putting their commands behind `/plugin:` made them less direct to use. Separately, built-in and
+loaded extension commands could both appear when their names matched a core command, alias or
+prompt. Duplicate bridge registrations also exposed `/plugin:accounts`, `/plugin:hub`, and
+`/plugin:plugins` beside their existing core commands.
+
+## Decision
+
+Commands owned by a required built-in plugin use the bare terminal namespace: `/subagents`,
+`/trajectory`, `/doctor`, and `/worktree`. Optional built-in plugin commands, currently
+`/plugin:notes` and `/plugin:annotate`, and Pi extension commands remain under `/plugin:<command>`.
+Core commands `/accounts`, `/hub`, `/plugins`, and `/mcp` remain unprefixed.
+
+An existing bare core command, alias, required built-in command, or loaded prompt reserves its
+name. A colliding `/plugin:<name>` is absent from completion/help and direct invocation explains
+which bare command to use. Duplicate extension registrations retain owner-path diagnostics. Remove
+the bridge registrations that duplicate `/accounts`, `/hub`, and `/plugins`.
+
+## Alternatives
+
+Keeping all built-in commands namespaced preserves duplicate entries and makes required features
+less direct to invoke. Unprefixing every built-in plugin command would also change the optional,
+switchable Annotations commands. Suppressing only a fixed list of observed duplicate names would
+allow the same problem to recur as plugins or prompts are added.
+
+## Consequences
+
+Required built-in command metadata determines the namespace used by terminal completion, help and
+dispatch. A third-party extension whose command collides with a bare command or prompt must use a
+different command name to expose both. There is no protocol or storage change.

package/docs/decisions/ADR-0022-plan-only-question-tools.md

@@ -0,0 +1,34 @@
+# ADR-0022 — Question tools are available only in attended plan runs
+
+Status: Accepted (owner requested implementation of PROP-0022, 2026-10-24).
+Related: [PROP-0022](../architecture/proposals/PROP-0022-plan-only-questions.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Ordinary chat exposed the Harness-owned `ask_user` tool, while the terminal also activated its
+single-question `ask_user_question` tool in normal mode. Hiding the required `ask-user` plugin would
+also remove it from plan mode and contradict its required-plugin contract. The callable tool set
+must instead be resolved by run mode.
+
+## Decision
+
+Newly resolved normal runs omit `ask_user` before their capability set is frozen, regardless of a
+wider requested tool list. An attended plan run may receive it, subject to the caller's narrower
+capabilities. Automatic, probe, improver and reflection runs do not receive it. In the terminal,
+normal mode deactivates both question tools; a plan request temporarily enables the registered
+question tools and restores the previous active set on success, error or interruption.
+
+The required `ask-user` built-in remains attached and has no user-facing switch. Approval prompts
+and ordinary assistant text are unaffected. A continuation preserves the earlier frozen capability
+set; if that snapshot includes `ask_user`, an automatic or refinement-triggered continuation is
+rejected with `continuation_mismatch` rather than silently narrowing the snapshot or allowing an
+unattended question.
+
+## Consequences
+
+Normal and plan requests can have different provider tool schemas, so no cache-preservation claim is
+made; measure any provider-cache effect only under `INV-PRM-8`. Existing records and attachments need
+no migration. The App relies on the Harness-resolved tool set and adds no separate preference.

package/docs/decisions/ADR-0023-contextual-side-question-runs.md

@@ -0,0 +1,35 @@
+# ADR-0023: Contextual side questions are Harness runs
+
+**Status:** Accepted  
+**Date:** 2026-10-24  
+**Proposal:** [PROP-0019](../architecture/proposals/PROP-0019-contextual-side-questions.md)
+
+## Context
+
+The terminal and App had separate `/btw` implementations. The terminal used a short, in-memory
+Pi session; the App used a bounded, tracked run. Their answers could not consistently use the main
+run's instructions or public tool evidence, and they had different lifecycle and observability.
+
+## Decision
+
+The Harness owns one side-question service. It creates an independent run with no variant and an
+empty frozen capability set. The service uses a redacted projection of the main run's effective
+prompt, visible transcript, and persisted public events, including tool inputs and results. It
+excludes hidden reasoning and attachment bytes. Context is bounded, credential-like material is
+redacted, and transcript/tool content cannot add permissions. Terminal and host surfaces use the
+same service and ordinary run-event contract.
+
+## Consequences
+
+Side answers are separately recorded and can be inspected with ordinary run history and usage.
+They never enter or steer the parent conversation. No persistent side-thread store or migration is
+needed. The terminal presents a temporary scrollable dock; a host keeps its own presentation. The
+App's read-only native file tools use the operating system's read boundary across absolute and home
+paths; the App's host gate continues to protect edits, writes and shell commands.
+
+## Rejected options
+
+- Keeping a separate in-memory terminal session would preserve different answers and observability.
+- Sending hidden reasoning, images or the main run's tools would expose more than a side answer
+  needs and could let it act independently.
+- Persisting side threads would require retention, deletion and synchronization rules.

package/docs/decisions/ADR-0024-xagent-command.md

@@ -0,0 +1,40 @@
+---
+id: ADR-0024
+title: Publish the Harness CLI as xagent
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0023]
+supersedes: ADR-0009
+---
+
+# ADR-0024 — Publish the Harness CLI as xagent
+
+## Context and decision drivers
+
+The Harness CLI's no-subcommand path starts the standalone OpenTUI terminal. The current executable
+name, `xharness`, is being replaced by the requested shorter product command, `xagent`. The
+published command is part of the package's public interface.
+
+## Decision
+
+Publish `@xingular/harness` with one executable, `xagent`, mapped to `dist/cli.js`. Invoking
+`xagent` without arguments starts the existing OpenTUI terminal. Do not retain `xharness` as a
+compatibility alias. Keep the package name, `terminal` alias, host subcommands, data/state directory
+names, and `XINGULAR_HARNESS_*` environment variables unchanged.
+
+This supersedes ADR-0009's executable-name decision and the `xharness` command-name portion of
+ADR-0014. Other release-baseline decisions remain unchanged.
+
+## Consequences
+
+- Users and scripts that invoke `xharness` must migrate to `xagent`.
+- No account, data, or state migration is required.
+- If `xharness` has already been released, replacing it requires a new major version; this change is
+  intended for the unpublished 4.0.0 candidate.
+
+## Implementation and verification
+
+- The `bin` mapping and CLI help are tested by [`src/cli.test.ts`](../../src/cli.test.ts).
+- The implementation and migration notes are tracked in
+  [PROP-0023](../architecture/proposals/PROP-0023-xagent-cli-name.md).

package/docs/decisions/ADR-0025-question-choice-sketches.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0025
+title: Store bounded ASCII sketches with question requests
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0024, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0025 — Store bounded ASCII sketches with question requests
+
+**Accepted by the product owner on 2026-10-24.**
+
+## Context
+
+Choice labels and descriptions do not always communicate a layout or other compact visual
+comparison. Both question surfaces need the same safely bounded representation, and the validated
+`question.requested` event is the existing shared contract through which they receive choice data.
+
+## Decision
+
+- A question may set `uiSketch: true` to enable sketch previews. Each offered choice must then
+  provide its own `sketch`; without the flag, a choice must not provide a sketch.
+- Sketches are literal text of 1–8 LF-separated lines, at most 32 printable ASCII characters per
+  line, with at least one visible character. The complete value is at most 263 bytes. Tabs, CR,
+  control characters, escape sequences and non-ASCII text are invalid. Valid text, including
+  interior blank lines and trailing spaces, is preserved exactly.
+- Harness validates the flag/choice relationship and text bounds before emitting a request. The
+  persisted `question.requested` event may carry the metadata; `question.answered` and
+  `QuestionAnswer` remain unchanged. Older request events remain valid.
+- The terminal and hosts render one shared monospace preview below the choices, following the
+  hovered or focused choice. They render the sketch as text, not Markdown, ANSI or executable rich
+  output.
+
+## Consequences
+
+- The existing event schema and persistence path carry the preview; no event kind, image type,
+  storage file or protocol version is added. No data migration is needed.
+- Hosts mirror the optional schema fields. Surface parity requires the terminal and each host to
+  present the same choice sketches without changing answer semantics.
+- The strict ASCII and dimension limits keep the diagram readable in a 40-column terminal and
+  prevent markup, terminal controls and unbounded content from entering the question surface.
+
+## Implementation and verification
+
+Implemented under [PROP-0024](../architecture/proposals/PROP-0024-question-sketch-previews.md).
+Verification evidence is recorded with that proposal and in the App's implementation-stage log.

package/docs/decisions/ADR-0026-contextual-question-wireframes.md

@@ -0,0 +1,58 @@
+---
+id: ADR-0026
+title: Align question columns and preserve contextual ASCII wireframes
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0025, ADR-0025, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0026 — Align question columns and preserve contextual ASCII wireframes
+
+**Accepted by the product owner on 2026-10-24** through the plan “Fix TUI question columns and sketch previews”. This is foundation work.
+
+## Context
+
+Content-dependent choice rows do not align label and description boundaries. The original 32×8
+sketch limit cannot express contextual UI panels, and a caption plus left rule adds redundant
+preview chrome. ADR-0025 records the original sketch contract and its historical evidence; this
+decision amends its bounds and presentation without replacing the optional sketch/answer model.
+
+## Decision
+
+- Use one measured layout across every choice: marker gutter, one-third label cell, two-cell gap,
+  remaining description cell. Wrap within cells, retain empty description cells, and never stack
+  columns at compact widths. Use `(Rec.)` when the label column is fewer than 14 cells and a compact
+  dock hint below 60 terminal columns.
+- Accept 1–24 LF-separated lines of at most 80 printable ASCII characters each (1,943 bytes
+  maximum), with at least one visible character. Reject tabs, CR, controls, escapes and Unicode;
+  preserve whitespace literally. Both question tools and validated request events use these bounds.
+- Ask models for contextual UI wireframes containing actual panel/table structure and neighboring
+  elements, consistent across alternatives. This is generation guidance, not schema enforcement.
+- Render one shared border-only literal preview without a visible caption or extra left rule.
+  Preserve content without wrapping, reflow or truncation; bounded two-axis scrolling exposes
+  overflow. Hover/focus chooses the preview without changing the staged answer.
+- Bound and vertically scroll the dock body, keeping tabs and answer/action controls outside it.
+  PageUp/PageDown and Ctrl+Home/End scroll that body while the dock is active. Shift+arrows pan the
+  sketch; ordinary arrows keep question/choice navigation. Bring focused choices and notes into view.
+- Terminal and hosts accept the same metadata and preserve literal content. Host presentation may
+  differ, but the expanded contract requires acceptance on both surfaces under INV-PAR-1/2.
+
+## Consequences
+
+Existing sketches and events remain valid without a data rewrite. Readers enforcing the old limits
+must update before accepting larger events; rolling readers back requires avoiding sketches above
+those limits. `uiSketch` still requires a sketch on every choice and forbids sketches when disabled.
+`question.answered`, `QuestionAnswer`, the gate, prompt compilation and storage ownership do not
+change. No image format, event kind or executable rich-output contract is introduced.
+
+## Implementation and verification
+
+The accepted design is [PROP-0025](../architecture/proposals/PROP-0025-contextual-question-wireframes.md).
+Implementation and isolated terminal/host acceptance are recorded in the
+[retained verification](../evidence/terminal-question-wireframes/README.md), including four terminal
+sizes, live resizing, sketch panning, literal persistence and the host's expanded-boundary fixture.
+Earlier PROP-0024/ADR-0025 evidence remains historical; the new evidence does not claim live-model
+diagram quality, every emulator's behavior or native Tauri presentation.

package/docs/decisions/ADR-0027-connected-sketch-display.md

@@ -0,0 +1,60 @@
+---
+id: ADR-0027
+title: Project structural ASCII sketch lines into connected terminal borders
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0026, ADR-0026, ADR-0029, INV-RUN-3, INV-PAR-1, INV-PAR-2]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0027 — Project structural ASCII sketch lines into connected terminal borders
+
+**Design accepted by the product owner on 2026-10-24** with “yes, fix it” after screenshot review.
+This foundation presentation change is implemented and verified in isolated production fixtures;
+see [retained evidence](../evidence/terminal-connected-sketches/README.md).
+
+## Context
+
+ASCII `+|-` table frames appear disconnected in the terminal, and bare hyphen dividers do not
+reach the preview frame. ADR-0026's absolute literal-render promise prevents correcting those
+structural lines without a documented exception. Raw ASCII persistence and shared host metadata
+remain appropriate; the problem is terminal typography, not the question contract.
+
+## Decision
+
+Adopt [PROP-0026](../architecture/proposals/PROP-0026-connected-sketch-display.md). The terminal
+preview in `src/terminal/opentui/sketchPanel.ts` uses a bounded structural display projection:
+
+- Recognized ASCII table-border rows and enclosed vertical table edges become connected
+  box-drawing glyphs. Internal framed tables retain their original widths and positions.
+- Bare standalone hyphen divider rows expand to the larger of the panel viewport width and the
+  original sketch's widest line, joining the outer single-line preview frame with `├` and `┤`.
+- No global substitution: prose, content operators and ordinary pipes remain literal. Unrecognized
+  rows remain literal. Whitespace and geometry remain unchanged except for recognized structural
+  border glyphs and standalone-divider expansion, subject to the high-confidence boundary-cell
+  repair separately specified by [ADR-0029](ADR-0029-normalized-question-wireframe-borders.md).
+- Keep bounded two-axis panning, with no wrapping, reflow, truncation or markup interpretation.
+  Focus, selection, navigation and answers do not change.
+
+The validated source remains at most 80 printable ASCII columns by 24 lines. Persist that source
+literally, including whitespace; never save projected Unicode or divider expansion. No wire/schema
+or answer change is introduced. Hosts may retain literal previews of the same source. INV-PAR-1/2
+require equivalent capability and accepted metadata, not identical structural typography.
+
+## Consequences
+
+This amends only ADR-0026's terminal literal-render requirement and cross-surface typography
+promise; its bounds, raw persistence, layout and answer decisions remain in force. No migration or
+host code change is needed. Reverting the display projection does not affect saved events.
+Historical decisions and verification evidence remain unchanged.
+
+## Verification status
+
+The [PROP-0026 verification](../evidence/terminal-connected-sketches/README.md) covers structural
+recognition, content preservation, four terminal sizes, resizing/panning, original ASCII persistence
+and unchanged answers, alongside Harness and host checks. The later [ADR-0029 verification](../evidence/terminal-wireframe-normalization/README.md)
+covers title-bearing rules and bounded repair of missing or displaced frame edges. Prior PROP-0025
+evidence remains a record of the old presentation. Fixture verification is not owner visual
+acceptance, an every-font guarantee or evidence of live-model diagram quality.

package/docs/decisions/ADR-0028-xingular-agent-product-identity.md

@@ -0,0 +1,56 @@
+---
+id: ADR-0028
+title: Use Xingular Agent as the default Harness product identity
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0027, INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md]
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0028 — Use Xingular Agent as the default Harness product identity
+
+The product owner accepted [PROP-0027](../architecture/proposals/PROP-0027-xingular-agent-product-identity.md)
+on 2026-10-24.
+
+## Context
+
+The standalone terminal is Harness-owned, but its welcome and Harness-authored prompt identity used
+the default product name `Xingular Harness`. The requested product identity is `Xingular Agent`,
+with a terminal welcome that presents an orange `X` mark and blue `A G E N T` label. Changing the
+default affects product identity text beyond the welcome, including compiled prompts and Wiki text;
+embedding hosts may need their own name.
+
+## Decision
+
+Adopt PROP-0027:
+
+- Set `DEFAULT_PRODUCT_NAME` to `Xingular Agent`; continue honoring an explicit `productName` from
+  an embedding host.
+- Revise `INV-BND-2` to permit the exact canonical product identity `Xingular Agent` as the
+  default. Continue to prohibit application concepts, application-specific behavior and other
+  application names in Harness code and person/model-visible text.
+- Format a multiword product name in the empty welcome as the first letter of its first word in the
+  orange block mark and the remaining word(s), letter-spaced, in blue. Thus the default shows `X`
+  and `A G E N T`. A single-word name remains the mark without a subline.
+- Keep the centered greeting, tagline, `/help` hint, model/thinking status, composer and status bar;
+  use the existing orange and blue theme accents without adding tokens or changing other surfaces.
+
+## Consequences
+
+- Consumers that omit `productName` see `Xingular Agent` in Harness-authored product identity
+  text. Consumers that supply their own name are unchanged.
+- Existing prompt packs, runs and Wiki notes are not rewritten; newly compiled prompt identity and
+  new Wiki text use the default in effect at creation time.
+- No capability, API, storage layout or wire schema changes.
+
+## Verification status
+
+Implemented and verified on 2026-10-24.
+
+- Harness: `npm run typecheck`, `npm test` (143 files passed; 3 skipped), `npm run build`, and
+  `npm run prove` passed. Focused PTY verification passed at 40x20, 80x24 and 120x40, including
+  the `/help` transition.
+- Xingular Agent: `npm run typecheck`, `npm test` (566 renderer and 67 sidecar tests passed),
+  `npm run check:layers`, and `cd src-tauri && cargo test` passed.

package/docs/decisions/ADR-0029-normalized-question-wireframe-borders.md

@@ -0,0 +1,33 @@
+---
+id: ADR-0029
+title: Normalize high-confidence question wireframe borders in the terminal preview
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0028, ADR-0026, ADR-0027, INV-PAR-1, INV-PAR-2]
+---
+
+# ADR-0029 — Normalize high-confidence question wireframe borders in the terminal preview
+
+## Context
+
+The terminal displays bounded, model-authored ASCII sketches. The existing connected-glyph projection misses text-bearing top rules and rows with missing or misaligned side edges. The raw source remains the right shared contract, but its terminal display needs a narrowly constrained frame-repair rule.
+
+## Decision
+
+Adopt [PROP-0028](../architecture/proposals/PROP-0028-normalize-question-wireframes.md). The terminal may normalize only high-confidence, explicitly framed sketch boundaries:
+
+- Recognize title-bearing border rows and establish outer columns from matched frame rules.
+- Align a boundary character only across whitespace, or fill a missing boundary cell only where it is whitespace.
+- Preserve interior text, nested frame geometry, ambiguous rows, and ordinary content literally; no global symbol replacement.
+- Keep the source ASCII byte-for-byte in persistence and retain the existing question schema, answer payload, viewport and panning behavior.
+
+Hosts may continue rendering the same source literally. This decision changes terminal typography only; it adds no capability or host contract.
+
+## Consequences
+
+A valid framed sketch can display connected corners and continuous vertical edges even when its source omitted or misplaced a boundary glyph. Repairs are projection-only and deliberately conservative; ambiguous or content-conflicting rows remain untouched. No migration is required.
+
+## Verification
+
+Use structural unit fixtures and isolated production PTY runs at compact and wide terminal sizes. Verify the displayed topology, panning/resizing, and byte-for-byte source and answer preservation. This does not claim that every emulator/font renders box glyphs identically or that live-model sketches always describe the intended design.

package/docs/decisions/ADR-0030-agent-profiles.md

@@ -0,0 +1,43 @@
+---
+id: ADR-0030
+title: Agent profiles, one checklist per agent, and the subagent roster under the status line
+status: accepted
+created: 2026-10-24
+updated: 2026-10-24
+related: [PROP-0029, PROP-0006, ADR-0003, INV-RUN-2, INV-CAP-1, INV-PAR-1]
+---
+
+# ADR-0030 — Agent profiles, one checklist per agent, and the subagent roster under the status line
+
+## Context
+
+People want to start subagents of a known kind, such as a worker that edits and an explorer that
+only reads, and to follow their progress from the terminal. Subagents were copies of the parent
+or instruction-only c5 definitions, the terminal did not register the checklist tool, and the
+roster sat above the composer with a heading and no indication of each child's kind or progress.
+
+## Decision
+
+- Adopt [PROP-0029](../architecture/proposals/PROP-0029-agent-profiles.md): agent profiles are
+  Markdown files (built-in, `<data root>/agents/`, `<project>/.xingular/agents/`, then c5 names)
+  that a spawn resolves by name. A profile narrows tools and plugins and may choose a variant,
+  model and effort. It never widens the parent's capabilities.
+- Progress stays **one checklist per run** (PROP-0006). The parent's list is the plan the person
+  watches. Each child keeps its own list, and the roster shows its `n of m tasks`. There is no
+  shared, claimable task pool.
+- The terminal registers `checklist_write`, shows each write as a checklist block, and the prompt's
+  Progress group asks the model to keep it current because the person follows work from it.
+- The roster sits under the status line after one blank line, with no heading. Each row reads: status
+  mark, profile name in its colour, session name, tasks.
+
+## Consequences
+
+Profiles are a foundation feature, not variant data: refinement does not change them. A project
+can carry profiles in its repository. The App gets the same capability through `agents.*` and
+`RunRecord.profile`; it has no Agents screen yet (parity `planned`).
+
+## Verification
+
+Unit tests for profiles, narrowing, spawn, the monitor, the roster and the Agents page;
+`npm run prove`; and a loopback PTY run that checks the blank row under the status line, the row
+order, and the profile colours.

package/docs/decisions/ADR-0031-plugin-command-owner-namespaces.md

@@ -0,0 +1,37 @@
+# ADR-0031 — Plugin commands use owner-qualified namespaces
+
+Status: Accepted (PROP-0031, 2026-10-25).
+Supersedes: The command-namespace decision in [ADR-0021](ADR-0021-required-command-namespaces.md).
+Related: [PROP-0031](../architecture/proposals/PROP-0031-plugin-command-owner-namespaces.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md),
+[06 Plugins and capabilities](../architecture/06-plugins-and-capabilities.md).
+
+## Context
+
+The generic `/plugin:<command>` form hid command ownership for optional built-ins and Pi extensions,
+while required built-ins used a separate bare-command rule. Both forms left a global collision surface
+and made help, completion and invocation inconsistent across owners. Annotation routes also used the
+generic plugin prefix despite the plugin's annotation-focused purpose.
+
+## Decision
+
+Every plugin-owned terminal command is invoked as `/<owner-prefix>:<command>`, regardless of whether
+the owner is a required built-in, optional built-in or Pi extension. Core terminal commands remain
+unprefixed, and `/skill:<name>` remains reserved for skill invocation. Built-in plugins use stable
+prefixes; Pi packages may set `harness.commandPrefix` and otherwise derive the prefix from normalized
+package identity, while loose extensions use normalized extension names. Prefixes identify owners and
+must be unique; duplicate commands within an owner and owner-prefix collisions are rejected with
+source diagnostics.
+
+A built-in plugin module may choose a default command for its namespace root. Web annotations uses `/annotate:` for
+capture, `/annotate:annotate` as an equivalent alias, and `/annotate:notes` for saved annotations.
+For one release, the previous `/plugin:<command>` and bare required-plugin forms remain hidden
+compatibility aliases when unambiguous. They are omitted from help and completion.
+
+## Consequences
+
+The namespace rule applies uniformly to completion, help, highlighting and dispatch. Plugin packages
+may opt into a stable custom prefix with `harness.commandPrefix`. The compatibility aliases expire
+after one release and should not be used for new scripts or keybindings. This changes no server method,
+capability identifier, account data or annotation storage format.

package/docs/decisions/ADR-0032-compaction-run-checkpoints.md

@@ -0,0 +1,33 @@
+# ADR-0032 — Rehydrate bounded run checkpoints after compaction
+
+Status: Accepted (PROP-0033, 2026-10-25).
+Related: [PROP-0033](../architecture/proposals/PROP-0033-compaction-plan-checkpoints.md),
+[02 Sessions and runs](../architecture/02-sessions-and-runs.md),
+[04 Prompt](../architecture/04-prompt.md),
+[11 Terminal](../architecture/11-terminal.md),
+[14 Surfaces and parity](../architecture/14-surfaces-and-parity.md).
+
+## Context
+
+Pi preserves the native conversation transcript when compacting, but subsequent model requests use a
+summary and recent messages. The Harness already records the latest checklist as a run event and
+restores it when a stopped run is continued; an active run lacked equivalent rehydration after
+compaction. SDK plan instructions are dynamic context and may also be included in the summarized
+span.
+
+## Decision
+
+After compaction, each model request in the still-active run receives one bounded, ephemeral context
+message when a checklist or applicable plan instructions exist to restore. It contains the current
+request and available state. The prompt compiler assembles this content, and one Harness-owned
+extension provides the same behavior to embedded sessions and the terminal. The extension state is run-scoped and clears on
+settlement or branch navigation. The context message is not persisted to the native transcript or
+run-event stream; existing session history, checklist events and continuation records remain the
+sources of durable state. Hidden reasoning is never captured.
+
+## Consequences
+
+Post-compaction requests carry a small additional context block until the active run settles. The
+feature adds no storage, event, server method, tool, permission or stable-system-prompt change. Plan
+mode's existing gate remains authoritative. Runs without an explicit checklist or active plan state
+receive no checkpoint.