@xingular/harness 2.0.0 → 2.0.1-unstable

package/docs/architecture/proposals/PROP-0025-contextual-question-wireframes.md

@@ -0,0 +1,49 @@
+---
+id: PROP-0025
+title: Strict question columns and contextual ASCII wireframes
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-RUN-3, INV-PAR-1, INV-PAR-2, 02-sessions-and-runs.md, 11-terminal.md, 14-surfaces-and-parity.md]
+---
+
+# PROP-0025: Strict question columns and contextual ASCII wireframes
+
+The owner accepted the design with “Implement the plan: Fix TUI question columns and sketch previews”. This is foundation work. Implemented and verified in the working tree; see [ADR-0026](../../decisions/ADR-0026-contextual-question-wireframes.md) and [retained evidence](../../evidence/terminal-question-wireframes/README.md).
+
+## Problem
+
+Choice rows independently distribute width based on their content, so label and description boundaries differ. Sketches are limited to 32 columns by eight lines and presented beneath a redundant caption and left rule. These limits cannot represent a contextual UI panel like the owner's reference.
+
+## Affected rules
+
+- INV-RUN-3 validates every persisted question event. Its sketch bounds change from 32×8 to 80×24.
+- INV-PAR-1/2 require the same capability and accepted metadata on terminal and host surfaces.
+- Page 11's wrapping columns become strictly aligned columns at compact widths too.
+
+## Proposal
+
+Use one measured layout for every choice: marker gutter, one-third label cell, two-cell gap, remaining description cell. Preserve cells even without a description; never stack them on compact terminals. Text wraps within its cell.
+
+Support up to 24 LF-separated lines of 80 printable ASCII characters each (1,943 bytes maximum), preserving whitespace and rejecting controls, Unicode and empty diagrams. Tool guidance requests contextual UI wireframes with actual panel/table structure and neighboring elements, consistent across alternatives.
+
+Render one border-only ASCII preview without a visible caption. Preserve literal content with bounded two-axis scrolling. Keep tabs and answer/action controls outside the dock body's vertical scrolling region. PageUp/PageDown and Ctrl+Home/End scroll that body; Shift+arrows pan the sketch, leaving ordinary arrows for question/choice navigation. Focused choices and notes are brought into view. No answer semantics change.
+
+## Alternatives
+
+- Keep the old bounds: cannot show the reference's contextual layout.
+- Only change flex ratios: leaves per-row content-dependent boundaries.
+- Reflow or truncate diagrams: destroys structure or hides content permanently.
+- Rich images or structured scene graphs: unnecessary new storage/rendering contracts.
+
+## Consequences
+
+Both question tools, event validation and host contracts use the larger bounds. Existing clients with old limits must update before accepting larger new events. Existing event and answer formats, gate, prompt compilation and storage ownership remain unchanged. Generation quality is guidance, not a schema guarantee.
+
+## Migration
+
+No data rewrite. Old diagrams and events remain valid. Keep host contract compatibility in a separate repository change. Rollback of readers requires avoiding newly generated diagrams above the old bounds.
+
+## Checks
+
+Geometry and schema boundary tests, literal persistence and unchanged answers; isolated production PTY checks at 40×20, 60×24, 80×24 and 120×40 including resizing, scrolling and keyboard focus; Harness typecheck/test/build/prove and latency profile; App typecheck/test/layer/UI/Rust checks and isolated question-form fixture. No live requests or personal profiles.

package/docs/architecture/proposals/PROP-0026-connected-sketch-display.md

@@ -0,0 +1,96 @@
+---
+id: PROP-0026
+title: Connect structural sketch lines in the terminal display
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-PAR-1, INV-PAR-2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md]
+---
+
+# PROP-0026: Connect structural sketch lines in the terminal display
+
+The owner approved this foundation presentation change with “yes, fix it” after inspecting a
+screenshot of disconnected sketch lines. Implementation and rendered-topology verification passed
+in isolated production fixtures; see [retained evidence](../../evidence/terminal-connected-sketches/README.md) and
+[ADR-0027](../../decisions/ADR-0027-connected-sketch-display.md). The viewport-relative canvas and
+divider sizing below were later amended by [ADR-0080](../../decisions/ADR-0080-fixed-width-question-sketch-canvas.md);
+the connected-border projection remains in force.
+
+## Problem
+
+The terminal preview's ASCII `+|-` table frame appears gapped, and bare horizontal divider rows
+stop short of the surrounding preview frame. The absolute literal-render promise in PROP-0025
+prevents a display-only correction even though the stored sketch and answer semantics need not
+change. Historical PROP-0025 evidence establishes only the earlier presentation.
+
+## Affected rules
+
+- Page 11: “Sketches support up to 80 columns by 24 lines (page 02) and remain literal: no wrapping,
+  reflow, truncation or markup interpretation.” Its absolute literal display requirement is amended
+  by the bounded structural projection below; raw persistence remains literal.
+- Page 14: “The terminal and each host render the same literal text as one shared preview,
+  preserving whitespace and providing access to overflow; neither surface changes the answer
+  payload.” The same validated source and content remain required; identical structural glyphs
+  are not required across surfaces.
+- INV-PAR-1/2 still require the same capability and acceptance on both surfaces. Terminal-only
+  typography introduces no new capability or host contract. Page 02's validated ASCII bounds and
+  literal persisted request event, and INV-RUN-3's validation requirement, are unchanged.
+
+## Proposal
+
+In `src/terminal/opentui/sketchPanel.ts`, project validated ASCII into display text only:
+
+- Recognize ASCII table-border rows and enclosed vertical table edges, rendering their structural
+  `+`, `-` and `|` cells as connected box-drawing glyphs. Keep internal framed tables at their
+  original widths and positions; do not stretch them to the viewport.
+- Expand bare standalone hyphen divider rows to `max(panel viewport width, original sketch widest
+  line)`. Join these dividers to the outer single-line preview frame with `├` and `┤`; use the
+  existing bounded two-axis viewport when the projected canvas overflows.
+- Recognition is structural, not a global substitution. Preserve prose, content, arithmetic
+  operators and ordinary pipes literally. Unrecognized rows remain literal. Apart from recognized
+  border cells and standalone-divider expansion, preserve whitespace, blank lines and geometry.
+- Do not wrap, reflow, truncate or interpret Markdown/ANSI. All content remains reachable through
+  panning. Hover/focus preview behavior, navigation and staged answers remain unchanged.
+
+Raw sketches remain exactly the validated 80-column × 24-line maximum ASCII source (1,943 bytes
+maximum), including trailing spaces and blank lines, in request events and history. Display glyphs
+and expanded dividers never enter persistence or answer payloads. A host may retain a literal ASCII
+preview of that same source; terminal-only typography is permitted, not a host-only capability.
+
+## Alternatives
+
+- Do nothing: retains the screenshot's disconnected frame and short dividers.
+- Globally replace `+|-`: corrupts content, operators and pipes without structural context.
+- Stretch every table: destroys internal layout and relative geometry.
+- Rewrite stored sketches as Unicode or introduce structured graphics: unnecessary schema,
+  generation and migration changes for a display problem.
+
+## Consequences
+
+The terminal's absolute literal-render promise becomes a bounded structural display projection.
+There is no wire/schema, tool, validation-bound, server, storage or answer change. Hosts need no
+implementation change and may keep literal previews. This is foundation rendering work, not variant
+data. Historical proposals, decisions and evidence remain records of the behavior they verified.
+
+## Migration
+
+No data migration. Existing ASCII sketches use the same display projection when shown; rollback
+only restores literal terminal rendering. Implementation is terminal-only; host schemas and presentation
+need no change.
+
+## Checks
+
+The checks below passed in the implementing working tree; see the linked evidence for commands,
+counts, screen captures, bundle digests and limits. This is fixture verification, not a claim of
+owner visual acceptance or live-model diagram quality:
+
+- Connected table corners/tees/edges, with internal framed tables retaining original widths.
+- Standalone dividers fill the larger of viewport width and original widest line and join the
+  outer frame; test narrow/wide viewports, resizing and two-axis panning.
+- Prose, arithmetic operators, ordinary pipes, unrecognized structures, whitespace and blank lines
+  remain unchanged outside the explicit projection; persisted ASCII and answers are byte-for-byte
+  unchanged, including 80×24 boundary fixtures.
+- Isolated production PTY screenshots and interaction checks for the new rendering, independent of
+  the retained PROP-0025 evidence. Confirm the host's literal preview remains contract-compatible.
+- The implementing change runs Harness typecheck/tests and the applicable terminal checks, plus
+  embedding App checks required by AGENTS.md. No live-provider request is authorized here.

package/docs/architecture/proposals/PROP-0027-xingular-agent-product-identity.md

@@ -0,0 +1,60 @@
+---
+id: PROP-0027
+title: Use Xingular Agent as the default Harness product identity
+status: Accepted
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md, terminal-tui.md, ADR-0028]
+---
+
+# PROP-0027: Use Xingular Agent as the default Harness product identity
+
+The product owner accepted this proposal on 2026-10-24. The decision is recorded in
+[ADR-0028](../../decisions/ADR-0028-xingular-agent-product-identity.md).
+
+## Problem
+
+The empty welcome in `src/terminal/opentui/root.tsx` derives its block mark and spaced subline from `XINGULAR_HARNESS_NAME`, which `Terminals.prepare()` sets from `env.productName`. When no product name is supplied, `src/core/env.ts` defaults to `Xingular Harness`, so the current welcome shows a large `XINGULAR` mark and `H A R N E S S` subline. The requested identity is an orange `X` mark followed by a blue `A G E N T` label, with a welcoming message and restrained `/help` hint.
+
+`Xingular Agent` is the product name; the requested screen remains the Harness-owned terminal. However, changing the default name changes person- and model-visible Harness text beyond this screen, and the specification forbids naming an application. This required an explicit architecture decision, which the product owner accepted as PROP-0027.
+
+## Affected rules
+
+`INV-BND-2` currently says: “The harness names no application and no application concept (agent role, group, task, pane, handoff, App browser workspace, computer use) in code paths it reads or text a model or person sees. Text names the product through `env.productName` (default `Xingular Harness`; `{product}` in a tool description).”
+
+The rule's default product identity and its prohibition on application naming are affected. The terminal's existing ownership and composition contracts in `11-terminal.md` are not otherwise changed.
+
+## Proposal
+
+Make `Xingular Agent` the default `env.productName`, while retaining explicit `productName` values supplied by embedding hosts. Amend `INV-BND-2` to allow this exact canonical product identity as the default; continue to forbid application concepts, app-specific branching and other application names in Harness behavior.
+
+For the welcome, format a multiword product name as a block mark made from the first letter of its first word, followed by the remaining word or words letter-spaced. Thus the default `Xingular Agent` appears as an orange `X` and blue `A G E N T`. A single-word product name keeps its full word as the mark and has no subline. Keep the greeting and tagline neutral, color the `/help` hint blue, and preserve the existing model/thinking information and composer. Use the existing `theme.primary` orange and `theme.accent` blue; do not add tokens or change other terminal surfaces.
+
+The default product name is used by Harness outside the TUI, including compiled prompt and Wiki text. This proposal intentionally changes those defaults too; embedding hosts that need another identity continue to pass their own `productName`.
+
+## Alternatives
+
+- **Keep `Xingular Harness` as the default and rely on `productName` overrides.** This preserves `INV-BND-2` and avoids changing prompt/Wiki text, but does not make the requested product identity the built-in default.
+- **Change only the TUI welcome label.** This would show `Xingular Agent` while other Harness text still calls the product `Xingular Harness`, and would bypass the existing `env.productName` boundary.
+- **Do nothing.** Retains the current `XINGULAR` / `H A R N E S S` welcome.
+
+## Consequences
+
+- Hosts that omit `productName` will use `Xingular Agent` in Harness-authored product text, not only in the terminal welcome. Hosts with an explicit name are unaffected.
+- The terminal remains Harness-owned and generic in behavior. No application-specific branches, capabilities, storage or protocol fields are added.
+- Existing session/run records and Wiki data are not rewritten. New compiled contexts and new Wiki text use the new default; prior records retain the name with which they were created.
+- No server or terminal wire schema changes.
+
+## Migration
+
+No data migration is required. Embedding hosts that need to retain the former default can pass `productName: 'Xingular Harness'`; hosts with another product identity continue to pass that name explicitly. Reverting the default affects only newly created contexts and text, not persisted records.
+
+## Checks
+
+Verification:
+
+- Test `createEnv()`'s new default and that an explicit `productName` still wins.
+- Add a focused PTY welcome check for the `A G E N T` label and orange/blue ANSI colors at 40x20, 80x24 and 120x40; verify `/help` replaces the welcome.
+- Run Harness `npm run typecheck`, `npm test`, `npm run prove`, `npm run build`, and the focused terminal verification.
+- Run Xingular Agent's `npm run typecheck`, `npm test`, `npm run check:layers`, and `cd src-tauri && cargo test`.
+- Update the affected architecture and terminal-detail pages, and record the accepted lasting choice in an ADR.

package/docs/architecture/proposals/PROP-0028-normalize-question-wireframes.md

@@ -0,0 +1,55 @@
+---
+id: PROP-0028
+title: Normalize high-confidence question wireframe borders in the terminal preview
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-PAR-1, INV-PAR-2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity.md, ADR-0027]
+---
+
+# PROP-0028: Normalize high-confidence question wireframe borders in the terminal preview
+
+**Accepted and implemented on 2026-10-24** through “Implement the plan: Repair question wireframe borders.” The terminal-only display projection is amended; the persisted question contract and answers do not change. Verification is retained in [evidence](../../evidence/terminal-wireframe-normalization/README.md).
+
+## Problem
+
+The terminal currently projects horizontal rules only when a row contains decoration characters alone, so a title embedded between a frame's `+` corners remains ASCII. It recognizes vertical edges only when a row already contains both `|` delimiters. A missing or shifted side edge can therefore leave a visibly open or misaligned frame. Existing fixtures cover regular tables and dividers, not these screenshot-shaped cases.
+
+## Affected rules
+
+- Page 11 currently limits projection to recognized border characters and says whitespace and geometry are preserved except for structural glyph conversion and standalone-divider expansion. A high-confidence frame may now need a boundary glyph inserted or moved within whitespace to restore its declared rectangle.
+- Page 14 currently promises preservation of whitespace and geometry in the shared sketch source. The validated source remains unchanged and hosts may remain literal; the terminal preview gains this narrowly bounded projection exception.
+- The existing 80×24 ASCII source bounds, literal request-event persistence, answer payload, schema, server protocol and host contract are unchanged.
+
+## Proposal
+
+Keep the ASCII sketch as the wire and persistence format. In `src/terminal/opentui/sketchPanel.ts`, use a bounded cell-grid/topology pass to:
+
+- Recognize explicit ASCII frame rows with `+` corners and horizontal `-` runs, including a frame title surrounded by horizontal runs.
+- Establish a panel's left and right boundary columns from matched frame rules. Project only high-confidence panels; nested frames retain their own extents.
+- Within a matched frame, normalize a displaced `|` only when the path to its established boundary is whitespace, and synthesize a missing boundary glyph only into a whitespace cell. Preserve all interior text. If a row conflicts with content or the frame is ambiguous, leave it literal rather than guessing.
+- Resolve corners, tees, crossings and edges from neighboring structural cells. This is not a global `+|-` conversion: prose, arithmetic, ordinary content pipes, Markdown-like text and unmatched rows remain literal.
+- Keep the existing bounded two-axis viewport, panning, standalone-divider behavior and source bounds. Projected or inferred glyphs never enter events, history or answers.
+
+Strengthen both `ask_user` and terminal `ask_user_question` generation guidance to require stable left/right columns and matching border positions across rows and alternatives. Guidance is not validation; existing and externally supplied bounded ASCII sketches still receive the same safe display treatment.
+
+## Alternatives
+
+- **Prompt guidance only:** lowers the chance of new malformed sketches but cannot repair existing or externally supplied sketches.
+- **Global symbol substitution:** can corrupt prose, pipes and operators.
+- **Structured wireframe schema:** could make all geometry deterministic, but requires a wider protocol, persistence and host migration for a display-only correction.
+- **Do nothing:** retains disconnected title rules and incomplete edges.
+
+## Consequences
+
+Only the terminal's display projection changes. A recognized frame may occupy previously blank boundary cells or move a boundary character across whitespace, while its interior text stays fixed. Stored sketches remain byte-for-byte ASCII, answer semantics remain unchanged, and hosts may continue to show the literal source. Unrecognized or ambiguous diagrams are not repaired automatically.
+
+## Migration
+
+No data, schema, protocol or host migration. Existing question records use the new projection when displayed. Rolling back the terminal restores the prior literal behavior without affecting stored data.
+
+## Checks
+
+- Unit fixtures for title-bearing top rules, missing and whitespace-shifted edges, nested frames, ordinary pipes/prose, blank lines and unchanged source text.
+- Production PTY question fixtures at 40×20, 60×24, 80×24 and 120×40: connected cell topology, resize/pan behavior, and unchanged answers and persisted sketches.
+- Harness typecheck, full tests and build; App typecheck, tests, layer/UI checks and Rust tests. No live-provider requests are needed.

package/docs/architecture/proposals/PROP-0029-agent-profiles.md

@@ -0,0 +1,124 @@
+---
+id: PROP-0029
+title: Agent profiles that subagents start from
+status: Accepted; implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [INV-RUN-2, INV-VAR-4, INV-CAP-1, INV-STO-3, INV-SRV-1, 02-sessions-and-runs.md, 03-variants.md, 04-prompt.md, 06-plugins-and-capabilities.md, 10-server-protocol.md, 11-terminal.md, 12-storage.md, 14-surfaces-and-parity.md, parity, ADR-0030]
+---
+
+# PROP-0029: Agent profiles that subagents start from
+
+## Problem
+
+A subagent is either a copy of its parent or one of the parent variant's c5 definitions
+(`sub_agents/<name>/AGENT.md`). A c5 definition carries instructions only: the child cannot have
+its own tools, plugins, variant, model or effort (`subagentService.ts`, `spawn`). Nothing exists
+outside a variant, so a person cannot keep a "worker" or an "explorer" of their own, and a
+terminal session without a variant cannot name any subagent at all: the terminal never passed its
+variant to `Subagents.register`, so `agent:` always failed with "There is no subagent named …".
+The subagent roster could not say which kind of agent a child is.
+
+## Affected rules
+
+- INV-RUN-2: "A child run's set is the intersection of its parent's and what it asked for; it
+  never widens."
+- INV-VAR-4: "A run resolves its variant once and pins it; a child run or later turn uses the same
+  files even if the head moves."
+- INV-CAP-1: "A capability set only narrows."
+- INV-STO-3: "A new top-level folder or a new file in `runs/<id>/` is an architecture change."
+- INV-SRV-1: the method table (a new `agents` group).
+- 02 Subagents contract: "`agent` names one of the parent harness's subagents (c5)".
+
+## Proposal
+
+**A profile** is a Markdown file with frontmatter. The body is the role instructions.
+
+| Field | Meaning | Omitted |
+|---|---|---|
+| `name` | `^[a-z0-9][a-z0-9_-]*$`, equal to the file name | the file name |
+| `description` | one line, shown to the model and in `/agents` | required |
+| `color` | `blue green yellow red magenta cyan orange purple` | `blue` |
+| `tools` | tool allowlist | every tool the parent has |
+| `plugins` | plugin ids whose contributions the child keeps; required plugins always stay | all |
+| `variant` | `<scope>`, `<scope>@<version>` or `none` | the parent's pinned variant |
+| `model`, `effort` | the child's model and effort, on the parent's account | the parent's |
+
+**Sources**, later ones winning by name:
+1. Built-ins in code (`agents/builtin.ts`): `worker` and `explorer`.
+2. `<data root>/agents/<name>.md` (global).
+3. `<project root>/.xingular/agents/<name>.md`, where the project root is the nearest folder above
+   the session's working folder that holds `.git`, or the working folder itself.
+
+The parent variant's c5 definitions fill names nobody else took, as instruction-only profiles
+(source `variant`), so existing variants keep working. An unreadable file is reported in
+`problems` and hides nothing.
+
+**Spawning.** `spawn_subagent { agent }` and `subagents.spawn { agent }` resolve a profile
+(`agents/profiles.ts::resolveProfile`).
+- Tools: the child's tools are the parent ceiling ∩ the profile's `tools` ∩ the call's `tools`.
+  Profile tools the parent lacks are dropped and returned as `unavailableTools`.
+- Plugins: the child's contributions are the parent's whose plugin is in `plugins` or required,
+  and a tool whose owning plugin was dropped goes with it (`agents/narrow.ts`).
+- Gated tools stay the parent's gated tools ∩ the child's, so a worker's edits still ask.
+- Variant: a profile with `variant: <scope>[@version]` makes the child resolve and pin that variant
+  when it starts. `none` and c5 definitions start the child with no variant; otherwise the child
+  keeps the parent's pinned folder.
+- The profile body becomes the child's `subagent` section, "Your role: <name>" (order 22).
+- `RunRecord.profile` records the profile name on the child; it is absent for a copy.
+- The spawn result adds `agent` and, when non-empty, `unavailableTools`.
+
+**Prompt.** When a run may spawn, the compiler receives one `subagents` section (order 64) that
+lists every profile with its description (`profileSection`). It replaces the variant's own c5
+list, which it includes.
+
+**Methods.** A new `agents` group: `agents.list { cwd? }` → `{ profiles, problems }`,
+`agents.get { cwd?, name }`, `agents.create { cwd?, name, scope: global | project, from? }`
+(the template, or a copy of `from`; never overwrites), `agents.remove { cwd?, name, scope }` (own
+files only). The harness is the only writer of profile files. The terminal reaches the same
+functions through `terminal.agents.list|create|remove`.
+
+**Terminal.** `/agents` opens the Agents page: built-in, global, project and variant profiles,
+unreadable files, and details. Enter on a row offers edit (opens `$VISUAL`/`$EDITOR`), copy and
+delete for a person's own profile, and copy for a built-in. The subagent roster sits under the
+status line after one blank line, without a heading; each row is the status mark, the profile
+name in its colour (`subagent` for a copy), the child's session name (or its brief), and
+`n of m tasks` from the child's own checklist. The terminal passes its pinned variant to
+`Subagents.register`, so c5 names work there too.
+
+## Alternatives
+
+- **Profiles as variant data (c5 only).** Refinement could change them, but a person would need a
+  variant to have a worker at all, and a variant cannot carry a model or plugin choice per child.
+- **Store in `config/`.** One JSON file per data root is harder to edit by hand, cannot live in a
+  repository, and would make `config/` a second enablement store (INV-PLG-6).
+- **A shared task pool that subagents claim.** Considered with this change and rejected: it needs
+  item ids, owners, locking and a new store, and is the delegated work queue the product keeps out
+  of scope. Each run keeps its own checklist (PROP-0006); the roster shows each child's progress.
+- **Do nothing.** Subagents stay copies, and the terminal cannot name any.
+
+## Consequences
+
+- Hosts see one optional `profile` field on run records, two optional fields on the spawn result,
+  and a new `agents` method group.
+- A profile can only narrow: a child never gains a tool, connector or contribution its parent
+  lacks (INV-RUN-2 and INV-CAP-1 hold unchanged). Choosing another variant or model is not a
+  capability and stays within the parent's account.
+- A project profile comes from the repository, like `AGENTS.md`: its instructions are as trusted
+  as the repository, and it cannot widen access.
+- The prompt's subagent list now changes when a profile file changes, at the next run; a run that
+  already started keeps its prompt.
+- INV-VAR-4 reads: a child run uses the parent's pinned files unless its profile names another
+  variant, which the child then resolves and pins itself.
+
+## Migration
+
+None. Existing c5 definitions appear as profiles of source `variant`. Removing the feature means
+deleting `src/agents/` and the `agents/` folders; run records keep an unused field.
+
+## Checks
+
+`src/agents/profiles.test.ts`, `src/sessions/subagentService.test.ts` (profiles narrow, pin a
+variant, record the name), `src/server/server.test.ts` (`agents.*`), the terminal roster, monitor
+and Agents page tests, `npm run prove`, the App's checks, and a loopback PTY run that spawns an
+explorer, a worker and a copy and reads the roster under the status line.

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.