@xingular/harness 0.1.7 → 1.1.1

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,94 @@
+---
+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).
+
+## 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/README.md

@@ -0,0 +1,101 @@
+# Architecture proposals
+
+A proposal is required before any change that alters a contract, an invariant, a layer
+boundary, an extension point, or the storage layout described in [the specification](../README.md).
+The author writes it and stops; the user reviews it. Code and spec pages change only after the
+proposal is `Accepted`.
+
+## Status
+
+| Status | Meaning |
+|---|---|
+| `Proposed` | Written, waiting for the user. Nothing has changed. |
+| `Accepted` | The user approved it. Implement it and update the spec pages in the same change. |
+| `Implemented` | Code and spec pages match the proposal. Link the commit or ADR. |
+| `Rejected` | The user declined it. The file stays as a record. |
+| `Withdrawn` | The author dropped it before review. |
+
+## Index
+
+| ID | Title | Status | Affects | Date |
+|---|---|---|---|---|
+| [PROP-0001](PROP-0001-reporting-section.md) | A built-in Reporting section that shapes the final reply | Implemented | INV-PRM-2, 04-prompt.md | 2026-10-21 |
+| [PROP-0002](PROP-0002-retain-rollout-workspaces.md) | Opt-in retention of each refinement execution's workspace | Implemented | INV-REF-1, 05-refinement.md, 10-server-protocol.md, 12-storage.md | 2026-10-21 |
+| [PROP-0003](PROP-0003-executor-settings.md) | Name the model and account of refinement's executions on refine.start | Implemented | 05-refinement.md, 10-server-protocol.md | 2026-10-21 |
+| [PROP-0004](PROP-0004-flexible-reporting-guidance.md) | Flexible final-reply guidance with an optional human-inspection heading | Implemented | INV-PRM-2, 04-prompt.md, ADR-0007, ADR-0008 | 2026-10-21 |
+| [PROP-0005](PROP-0005-xharness-cli-name.md) | Rename the published CLI command to xharness | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0009 | 2026-10-22 |
+| [PROP-0006](PROP-0006-run-checklist.md) | A run checklist the model writes, recorded as a run event | Implemented | 02-sessions-and-runs.md, 06, 07, 10-server-protocol.md | 2026-10-22 |
+| [PROP-0007](PROP-0007-run-continuation.md) | Continue a stopped run as a new run with the same pins | Implemented | INV-RUN-4, INV-RUN-10, 00-overview.md, 02-sessions-and-runs.md, 10-server-protocol.md | 2026-10-22 |
+| [PROP-0008](PROP-0008-lessons-from-runs.md) | Opt-in lessons from finished runs, kept in the Wiki | Implemented | INV-MEM-2, 02, 06, 08-memory-and-history.md, 12-storage.md, ADR-0010 | 2026-10-22 |
+| [PROP-0009](PROP-0009-foundation-and-variants.md) | Name the fixed half the foundation and the mutating half the variant | Accepted | INV-TREE→INV-VAR, new INV-FND-1/2, 00, 03, 05, 10, 12, ADR-0011 | 2026-10-22 |
+
+| [PROP-0010](PROP-0010-session-names.md) | Agent-managed native session names | Implemented | 02, 04, 07, 11 | 2026-10-22 |
+
+| [PROP-0011](PROP-0011-doctor.md) | Readiness diagnostics and explicit live probes | Accepted; implementation in working tree | INV-EXT-1/4, INV-GATE-1, INV-TUI-4, 01, 07, 09, 10, 11 | 2026-10-22 |
+
+| [PROP-0012](PROP-0012-release-baseline.md) | Public 1.0.0 distribution and generic browser ownership | Accepted; candidate implementation | INV-BND-2, 00, 07, 11, 13 | 2026-10-22 |
+
+| [PROP-0013](PROP-0013-resource-browser.md) | Unified terminal resource browser | Implemented; working tree verified | 03, 06, 09, 11 | 2026-10-22 |
+
+| [PROP-0014](PROP-0014-fullscreen-browser-tabs.md) | Full-screen browser with persistent section tabs | Implemented; working tree verified | 11, terminal-tui.md | 2026-10-23 |
+
+| [PROP-0015](PROP-0015-one-capability-surface.md) | One capability surface: the terminal and every host offer the same capabilities | Accepted | INV-BND-2, new INV-PAR, 00, 11, 14, AGENTS.md | 2026-10-23 |
+
+| [PROP-0016](PROP-0016-managed-worktrees.md) | Managed git worktrees in the terminal and every host | Harness/terminal in 4.0.0 candidate; App create integration, remaining actions PAR-012 | INV-BND-2, D-5, INV-STO-3, INV-SRV-1, 00, 02, 10, 11, 12, 14 | 2026-10-23 |
+
+| [PROP-0017](PROP-0017-page-annotations.md) | Page annotations captured in the headed browser or a host's web view | Harness/terminal in 4.0.0 candidate; App source pending native-gesture acceptance | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+
+| [PROP-0018](PROP-0018-annotation-queue-and-app-targets.md) | Inspector-style page notes, a fix queue to the agent, and app windows as capture targets | Harness/terminal in 4.0.0 candidate; App source present, native WKWebView acceptance pending | INV-STO-3, INV-SRV-1, 07, 10, 11, 12, 13, 14 | 2026-10-23 |
+| [PROP-0019](PROP-0019-contextual-side-questions.md) | Harness-owned contextual side questions across surfaces | Implemented; working tree verified | INV-RUN-1/3/5, INV-GATE-1, INV-PLG-1/5, INV-CAP-1, INV-SRV-1/2, INV-PAR-1/2, 02, 04, 06, 07, 10, 11, 12, 14, ADR-0023 | 2026-10-24 |
+| [PROP-0020](PROP-0020-builtin-feature-plugins.md) | Built-in feature modules and namespaced plugin commands | Implemented; included in 4.0.0 candidate | INV-PLG-5/6, INV-TUI-2/7, INV-SRV-1, 06, 11, 13, 14 | 2026-10-24 |
+| [PROP-0021](PROP-0021-command-namespaces-and-duplicates.md) | Required built-in commands and duplicate command suppression | Implemented | INV-TUI-7, INV-PAR-1, 11, 14, ADR-0021 | 2026-10-24 |
+| [PROP-0022](PROP-0022-plan-only-questions.md) | Keep question tools available only in interactive plan mode | Implemented | INV-RUN-8, 02, 04, 06, 07, 11, 14, parity, ADR-0022 | 2026-10-24 |
+| [PROP-0023](PROP-0023-xagent-cli-name.md) | Rename the published CLI command to xagent | Implemented | 11-terminal.md, package.json#bin, CLI documentation, ADR-0024 | 2026-10-24 |
+| [PROP-0024](PROP-0024-question-sketch-previews.md) | Add bounded ASCII sketch previews to question choices | Implemented; working tree verified | INV-RUN-3, INV-PAR-1/2, 02, 10, 11, 14, parity, App question contract and plan-mode docs, ADR-0025 | 2026-10-24 |
+| [PROP-0025](PROP-0025-contextual-question-wireframes.md) | Strict question columns and contextual ASCII wireframes | Implemented; working tree and isolated fixtures verified | INV-RUN-3, INV-PAR-1/2, 02, 11, 14, terminal-tui.md, parity, ADR-0026 | 2026-10-24 |
+
+| [PROP-0026](PROP-0026-connected-sketch-display.md) | Connect structural sketch lines in the terminal display | Implemented; working tree and isolated fixtures verified | 11, 14, terminal-tui.md, parity, ADR-0027 | 2026-10-24 |
+| [PROP-0027](PROP-0027-xingular-agent-product-identity.md) | Use Xingular Agent as the default Harness product identity | Accepted; implemented and verified | INV-BND-2, 00-overview.md, 04-prompt.md, 11-terminal.md, terminal-tui.md, ADR-0028 | 2026-10-24 |
+| [PROP-0028](PROP-0028-normalize-question-wireframes.md) | Normalize high-confidence question wireframe borders in the terminal preview | Implemented; production PTY verification passed | INV-PAR-1/2, 11-terminal.md, 14-surfaces-and-parity.md, terminal-tui.md, parity, ADR-0029 | 2026-10-24 |
+| [PROP-0029](PROP-0029-agent-profiles.md) | Agent profiles that subagents start from | Accepted; implemented | INV-RUN-2, INV-VAR-4, INV-STO-3, INV-SRV-1, 02, 03, 04, 06, 10, 11, 12, 14, parity, ADR-0030 | 2026-10-24 |
+| [PROP-0030](PROP-0030-subagent-title.md) | A parent-set title for each subagent, shown in the roster | Accepted; implemented | 02, 07, 10, 11, terminal-tui.md, 14, parity | 2026-10-24 |
+
+Numbers are four digits, start at `0001`, and are never reused.
+
+## Template
+
+Save as `PROP-NNNN-<short-slug>.md`.
+
+```markdown
+---
+id: PROP-NNNN
+title: <one line>
+status: Proposed
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+affects: [INV-..., 02-sessions-and-runs.md, ...]
+---
+
+# PROP-NNNN: <title>
+
+## Problem
+What is wrong or missing today, with evidence (code paths, failures, requests).
+
+## Affected rules
+Each invariant, contract or boundary this changes, by ID, quoted as it stands.
+
+## Proposal
+The new rule and design, stated as the spec page would state it after the change.
+
+## Alternatives
+Other options considered, and why they were not chosen. Include "do nothing".
+
+## Consequences
+What changes for applications built on the harness, for stored data, and for the server protocol.
+
+## Migration
+How existing data, runs and hosts move over. Whether it can be undone.
+
+## Checks
+How the change will be verified: tests, `npm run prove`, the App's checks.
+```

package/docs/decisions/ADR-0002-native-subagent-lifecycle.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0002
+title: Native subagent lifecycle in Harness sessions
+status: superseded
+superseded_by: ADR-0003
+created: 2026-10-18
+updated: 2026-10-18
+---
+# ADR-0002 — Native subagent lifecycle in Harness sessions
+
+Superseded by [ADR-0003](ADR-0003-shared-asynchronous-subagents.md), which expands the native
+service to asynchronous execution, reliable delivery, and terminal parity. The earlier decision
+and its rationale are retained below.
+
+## Context
+
+Subagents already used Harness sessions, capability snapshots and run lineage, but their tool
+owned launching and polled run files for completion. A host inferred ownership from session
+names, coupling it to an internal identifier format.
+
+## Decision
+
+`Sessions.spawnSubagent` owns child creation. A live parent's captured launch supplies caller,
+account, model selection, folder, policy context, prompt and capability ceiling. The host or
+model supplies only a complete brief and an optional tool subset. Current capability availability
+and the captured nesting limit further restrict each child. Empty tool subsets stay empty;
+spawning permission is never added back after narrowing. Children start with fresh history,
+without inherited image attachments or request preamble. Existing tool gating applies.
+
+The model tool is an adapter to the same native API exposed over RPC. `RunRegistry.wait` resolves
+on settlement, including failed startup and interruption, without polling or per-call listeners.
+The Harness Subagents plugin attributes the model-visible tool. Opt-in remains a session option;
+`{}` selects the Harness default depth of one. Application organization delegation remains a host
+concern. Consumers resolve ownership from run lineage rather than parsing session IDs.
+
+## Alternatives and consequences
+
+Keeping orchestration in the tool would leave hosts without the same lifecycle contract.
+Moving application organizations into Harness would violate the embedding boundary. A new
+background job manager would duplicate existing run tracking, approvals and interruption.
+The selected change reuses these layers and preserves the synchronous model tool behavior.
+The native API starts children only for live parents in the same Harness instance; it does not
+resume a stopped parent's launch or implement cross-process child management.
+
+## Evidence
+
+Regression coverage is in `src/sessions/sessions.test.ts` and `src/server/server.test.ts`.
+Application host and run-family tests cover nested lineage with opaque session IDs. Verification
+results belong to the implementation handoff; no release or live-provider behavior is claimed.