@xingular/harness 1.0.0 → 1.1.1

package/docs/architecture/proposals/PROP-0023-xagent-cli-name.md

@@ -0,0 +1,61 @@
+---
+id: PROP-0023
+title: Rename the published CLI command to xagent
+status: Implemented
+created: 2026-10-24
+updated: 2026-10-24
+affects: [11-terminal.md, package.json#bin, CLI documentation, ADR-0009]
+---
+
+# PROP-0023: Rename the published CLI command to xagent
+
+## Problem
+
+The package currently publishes `xharness` as its only executable, and invoking it without a
+subcommand starts the Harness-owned OpenTUI terminal. The requested launch command is `xagent`.
+The command name is a public CLI contract, so replacing it must update the package bin mapping,
+help text, command examples, smoke checks, and the terminal specification.
+
+## Affected rules
+
+- Page 11 names `xharness` as the published executable and standalone terminal command.
+- `package.json#bin`, the package lock, CLI usage, and command-specific help publish and document
+  `xharness`.
+- ADR-0009 records `xharness` as the sole published executable.
+
+## Proposal
+
+Publish `xagent` as the sole executable mapped to `dist/cli.js`. Invoking `xagent` without a
+subcommand starts the existing OpenTUI terminal; `terminal` remains an explicit alias and the
+existing subcommands remain available. Do not keep `xharness` as a compatibility alias. Keep the
+npm package name, terminal runtime, data/state directory names, and environment-variable names
+unchanged. Update command examples and regression/smoke checks to use `xagent`.
+
+## Alternatives
+
+- Keep `xharness` as an alias. This avoids disruption but does not replace the requested launch
+  command.
+- Rename the npm package. This is unrelated to the executable name.
+- Do nothing. This leaves the requested command unavailable.
+
+## Consequences
+
+- Scripts and shell aliases using `xharness` must change to `xagent`.
+- The rename is a breaking CLI change. It is included before publication of the 4.0.0 candidate;
+  if `xharness` has already been released, the rename requires a new major release.
+- No account, data, state, or server-protocol migration is required.
+
+## Migration
+
+Install `@xingular/harness` and launch the terminal with `xagent`. Update invocations of the former
+`xharness` command. Existing `~/.xingular-harness/{data,state}` contents are reused unchanged.
+
+## Checks
+
+- `npm run typecheck` passed.
+- `npm test` passed: 137 test files, 1,036 tests passed, 3 skipped; the focused CLI test also passed (2 tests).
+- `npm run prove` passed, including the standalone server lifecycle.
+- `node dist/cli.js --help` printed usage beginning with `xagent`.
+- `npm pack --dry-run` passed and included the CLI, TUI bundle, and updated decision records.
+
+The lasting decision is recorded in [ADR-0024](../../decisions/ADR-0024-xagent-command.md).

package/docs/architecture/proposals/PROP-0024-question-sketch-previews.md

@@ -0,0 +1,130 @@
+---
+id: PROP-0024
+title: Add bounded ASCII sketch previews to question choices
+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, 10-server-protocol.md, 11-terminal.md, 14-surfaces-and-parity.md, docs/parity.md, App/shared/contracts.ts, App/src/modes/chat/QuestionBatchForm.tsx, App/docs/features/FEAT-0013-plan-mode.md, App/docs/architecture/implementation-stage.md, ADR-0025]
+---
+
+# PROP-0024: Add bounded ASCII sketch previews to question choices
+
+**Accepted by the product owner on 2026-10-24; implementation and verification completed in the working tree.**
+
+## Problem
+
+Question choices currently carry labels, descriptions and recommendation state. The validated
+`question.requested` run event persists those fields, but neither the Harness question contract nor
+the App's mirrored contract can carry a choice-specific visual sketch. As a result, an agent cannot
+show a small text diagram to clarify a choice, and neither question surface can preview one while a
+person compares choices.
+
+This changes the persisted run-event payload contract. It must be accepted before changing code or
+the architecture specification.
+
+## Affected rules
+
+- **INV-RUN-3:** “Every run event is validated against its schema, redacted, persisted, and only then
+  relayed to listeners, in order. An event that arrives after the run settled is kept as evidence and
+  never applied or relayed.” This proposal adds validated optional metadata to
+  `question.requested`; it does not change event ordering or persistence.
+- **INV-PAR-1:** “Every capability a person can use in a host is a Harness capability: a foundation
+  service, a world part or a first-party plugin, reachable through server methods. The standalone
+  terminal surfaces it. A host is a presentation of it.” Sketch metadata and the terminal preview
+  are Harness-owned; the App presents the same question data.
+- **INV-PAR-2:** “A capability is complete only when its terminal surface and its host surface both
+  pass acceptance. It lands in the Harness first, together with its terminal surface; the host
+  surface follows.” Both question surfaces must render and test the same metadata.
+
+## Proposal
+
+1. Extend each question input with optional `uiSketch?: true`. This question-level flag enables
+   sketch mode; it applies to that question only, including questions in an `ask_user` batch.
+2. Extend each choice with optional `sketch?: string`. When `uiSketch: true`, every choice must
+   contain a valid sketch. When the flag is absent, choices must not contain sketches. Reject an
+   invalid combination before emitting a question event; do not silently omit or truncate data.
+3. Bound each sketch to 1–8 lines and at most 32 printable ASCII characters per line. Lines are
+   separated by LF. Only bytes `0x20`–`0x7e` and LF are allowed; tabs, CR, terminal controls,
+   escape sequences and Unicode are rejected. The sketch must contain at least one non-space
+   printable character. Interior blank lines and trailing spaces are allowed and preserved exactly.
+   The maximum encoded length is 263 bytes (eight 32-character lines plus seven LF separators).
+4. Add the fields to both Harness question-tool schemas (`ask_user` and terminal
+   `ask_user_question`) and their runtime validation. Add them to the `question.requested` payload
+   schema and preserve them through `RunRegistry` into the persisted event. `question.answered` and
+   `QuestionAnswer` stay unchanged: sketch metadata is never part of an answer.
+5. The terminal question dock renders choice labels and descriptions in wrapping columns. It places
+   one shared, monospace sketch canvas below the choice list, displaying the hovered choice's sketch
+   or, with no hovered choice, the keyboard-focused choice's sketch. It does not create one canvas
+   per choice. Sketch content is rendered as literal text, without Markdown or ANSI interpretation.
+6. The App mirrors the payload schema and preview behavior in `QuestionBatchForm`. Its choice
+   label/description columns wrap at narrow widths, and its shared preview is literal monospace
+   text. Update plan-mode acceptance to cover sketch-enabled questions and record the implementation
+   in the App's implementation-stage log. Update Harness architecture/terminal docs and
+   `docs/parity.md` when implementing.
+7. On acceptance, add ADR-0025 to record the stable question-event and sketch-bounds contract.
+
+The optional flag is intentionally a positive literal, not a free-form renderer configuration.
+Sketches do not introduce an image/attachment type, a host-only surface or a new answer format.
+
+## Alternatives
+
+- **Accept optional sketches without a mode flag.** This leaves it unclear whether sketches are
+  expected, permits partially illustrated questions, and makes the preview's presence ambiguous.
+- **Allow Markdown, Unicode diagrams, ANSI or unbounded text.** Rendering differs across terminal
+  and host, escape/control content creates risk, and unbounded content can overwhelm a question
+  surface.
+- **Use image attachments or a rich-output event.** This adds a separate content/storage/rendering
+  contract for a small, readable diagram and cannot provide the same text fallback in the terminal.
+- **Do nothing.** Keeps the existing event stable but does not let questions explain choices with
+  compact diagrams.
+
+## Consequences
+
+- New `question.requested` events may carry `uiSketch: true` and per-choice `sketch` strings. The
+  event remains backward-compatible: both fields are optional, and old events continue to parse.
+- The App's shared contract must accept the same bounded fields as Harness. A stale host that does
+  not understand the optional metadata can still read the other question fields, but cannot show
+  the preview; parity requires updating the App before marking the feature complete.
+- The question surface gains a bounded preview with no answer semantics. Recommendation ordering,
+  selection, free text, notes, submission and cancellation remain unchanged.
+- There is no run-record layout change or migration. Sketches are stored only in the existing
+  `question.requested` event payload, subject to the existing event redaction and persistence path.
+- Existing question-tool and event callers that omit `uiSketch` behave as before. Calls that enable
+  it must provide a valid sketch for every choice.
+
+## Migration
+
+No migration is needed. New readers accept old question events because the new payload fields are
+optional; new writers validate the flag/choice relationship and bounds. Answer payloads are
+unchanged. The Harness implementation and terminal surface must land first; then the App schema and
+form are updated in a separate App repository change. No live-model request is required for
+verification.
+
+## Checks
+
+After acceptance, verify schema bounds and flag/choice consistency, preservation of literal sketch
+text through both tool paths and persisted events, compatibility with old events, unchanged answer
+payloads, and terminal/App hover/focus preview behavior. Run the focused Harness and App question
+tests, including the isolated question-form browser fixture. Also run:
+
+- Harness: `npm run typecheck`, `npm test`, `npm run build`, `npm run prove`,
+  `python3 scripts/verify-terminal.py --questions-only` at 40×20, 80×24 and 120×40, and a terminal
+  input-latency profile.
+- App: `npm run typecheck`, `npm test`, `npm run check:layers`, `npm run check:ui`,
+  `cd src-tauri && cargo test`, and the isolated question-form browser fixture.
+
+## Implementation evidence
+
+- Harness: `npm run typecheck`, all 1,041 tests (3 skipped), `npm run build` and `npm run prove`
+  passed. The isolated `--questions-only` PTY check passed at 40×20, 80×24 and 120×40 with
+  `pyte`; the 40-column run checks compact sketch navigation and answers, while wider runs also
+  check wrapped notes and free-text.
+- Input latency profile (160×45, four rounds, loopback provider, no live requests): idle p50/p95/p99/max
+  4.83/9.69/10.02/10.14 ms; history 4.72/9.79/10.41/10.60 ms; streaming 8.36/19.53/21.67/26.00 ms.
+  No keystrokes were missed.
+- App: `npm run typecheck`, `npm test` (566 renderer, 49 sidecar and 7 development-signing passed;
+  one signing test skipped), `npm run check:layers`, `npm run check:ui` and Rust tests (168 passed,
+  1 ignored) passed. The isolated question-form browser fixture passed all 5 tests using the installed
+  system Chrome executable.
+- The first App test run, executed concurrently with other checks, exceeded an existing run-event
+  performance threshold; the full suite passed when rerun alone. No live-model request was made.

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.