feat(mecatui): add comfort transcript presentation

[jbeda]

Summary

• Add actor-accent speaker headings in comfort and detailed views, with dark/light transcript recipes and compatible custom-theme fallbacks.
• Collapse adjacent settled tool calls into comfort summaries with failure counts; keep active cards visible and F9 per-call summaries in source order. Full arguments/results remain in Ctrl+T.
• Preserve group spacing, selection/copy provenance, reading anchors, and incremental rendering caches without parsing large cached tool arguments.
• Keep proven internal background-work and no-progress continuations out of reloaded human transcripts without changing stored model history, genuine user input, scheduled results, or event replay.
• Update owning documentation, generated contract comments, goldens, and real restart/client/Model regression coverage.

Groups reflect visible transcript adjacency, not dispatcher batches or concurrency. This does not add connected outline rails, measured timing, new identity, public theme settings, or durable-history machinery.

Verification

Passed locally on the committed candidate:

• task generate
• task test
• task test:race
• task lint
• task docs
• task site:build
• task build
• go run ./cmd/mecademo (tool result, permission ask/approval, final result)

Four-axis review plus scoped incremental rechecks found no remaining findings. Focused coverage includes mixed active/settled/failing/delegated calls, rebinding and modal routing, selection/anchors, light-mode cache replacement, persisted embedded/connect restart, and legacy/provenance preservation guards. A 4 MiB Write regression proves warm lifecycle render passes allocate zero; restoring the old full projection fails the test.

An isolated natural Shell → saved session → server/client/startup UI comparison reproduced the harness-note attribution on the pristine branch baseline and styling-only candidate; the new projection omits it. This does not establish why it was first noticed in a particular prior installation.

Limitations

• Legacy records without attributable harness origin remain visible rather than guessing from their text.
• The reload projection runs on the server; connected deployments need the updated server, not only the client.
• Automated tests do not certify every native terminal font or cell-width combination.

Plan

Full approved implementation plan, including the reload-note follow-up. The private design-study source location is omitted; all behavioral requirements and verification intentions are retained.

[jbeda]

Implementation plan archive: transcript visual language

• Slug: transcript-visual-language
• Source plan: .scratch/transcript-visual-language-plan.md (provenance, not a remote link)
• Repository/PR: stacklok/mecatl#2375
• Implementation branch: impl/transcript-visual-language; base: main
• Recorded start/review baseline: ac67d62123383afbede513b0c6cf2aa448f4f1b2
• Published PR head: 793e967c69060f4bef6da07f3308f177aff27fc7
• Archived: 2026-10-15T23:05:11Z

This is the approved design and verification plan, including the later reload-note fix. Historical planning-state statements below describe the drafting checkpoint; implementation and delivery were separately authorized. Actual completed checks are recorded in the PR body, not inferred from this plan's intended verification.

Publication note: the private interactive-study source location is omitted. All behavior, interfaces, tasks, acceptance checks, deferrals, and the reload-note amendment are retained.

---

Transcript visual language and outline rollout

• Slug: transcript-visual-language
• Implementation branch: impl/transcript-visual-language (already active in this checkout root)
• Base branch: main
• Recorded implementation start/current HEAD: ac67d62; initial code-review baseline, not moving origin/main.
• Status: revised plan after Joe's confirmed October 12 decisions; independent static critique found no blockers. The Mono wording advisory was corrected to preserve its actual existing palette. Planning does not authorize implementation, commit, push, PR creation or publication.
• Supersedes original PR 1 exclusions of comfort headings, aggregation and changed spacing. Preserve/extend existing uncommitted implementation; do not reset, recreate or rebase the branch.

Goal and scope

Ship accent speaker headings in comfort (non-F9) and detailed (F9), settled-tool aggregation in comfort, individual per-call summary lines in detailed, one blank row between response blocks/tool groups, and dark/light support. Make useful progress before canonical tool identity, execution telemetry and durable history work.

PR 1 now changes presentation grouping as well as styling. A group is consecutive visible top-level tool-family cards, NOT an authoritative dispatcher batch or claim of concurrency. PR 2 still owns connected outline rails/enclosures. No new durable state, execution identifiers, hook store, events, wire/schema changes, measured timing or generalized tree renderer.

Preserve existing work

• Preserve frozen local/remote impl/conversation-outline at af7d4d2, ignored scratch evidence and handoffs. No wholesale merge/cherry-pick, reset, cleanup, deletion, force push or rebase.
• Preserve current uncommitted PR 1 vocabulary/rendering/tests/docs. Prior verification covers the old candidate, not this amended scope.
• Design reference: the approved interactive transcript study (private source location omitted). Illustrative material, not a telemetry contract or supported settings schema.
• No edits to another checkout's handoff, HANDOFF update, branch switch, code implementation or publication during planning.

Grounded current behavior and approach

Paths abbreviated ui/ below are under cmd/mecatui/ui.

• cmd/mecatui/theme/{theme.go,builtins.go,registry.go} already own glyph constants and separate transcript marker/rail/text, reasoning/statistics/run-rail roles. Aztec/Solar have independent recipes; New/custom themes and Mono have palette-derived fallbacks. Extend these seams without public palette keys.
• ui/render.go:renderAssistantSnapshotFresh currently labels only F9; labels use neutral bold text beside accented glyphs. ui/internal/blocks/plain_cards.go:PrepareUser has a neutral bold label and existing border; PrepareNotice has a harness glyph but no system heading. Update heading styling/visibility without recoloring bodies.
• ui/toolcall_projection.go:projectToolCall/settled() define lifecycle truth. Settled includes success and recorded terminal failure; terminal without result is otherwise awaiting-result; provisional results are finalizing. Reuse this, not glyphs, row counts or ResultReceived alone.
• ui/tool_block.go:renderToolSnapshot/renderSettledToolLine already render settled calls as individual summary lines in both modes. Delegation uses the same projection. render.go:renderPasses deliberately fixes tool-family effectiveExpand=false. Keep this per-card invariant; F9 changes group assembly, not payload expansion. Ctrl+T remains full details.
• ui/internal/scrollback/scrollback.go:ToolCallMetadataAt provides local BlockID/revision, call name/arguments and lifecycle facts without detaching results/artifacts. Local IDs are existing presentation coordinates, not new canonical execution identities.
• ui/rendered_frame.go:renderConversationFrame/appendFrameSegment and ui/block_cache.go own assembly, provenance and incremental prefixes; render.go has a string-render equivalence path. Group at renderer/frame assembly; retain reusable per-card rendering and equivalent frame/string output. Do not reorder logical scrollback.
• ui/rendered_frame.go:renderedRow and ui/selection.go:selectionPointFor/resolveLogical associate source text with a single block. Aggregates require truthful derived-display provenance/member anchor relationships, not fabricated member source offsets. ui/conversation_view.go remains the sole viewport capture/restore owner.
• cmd/mecatui/main.go:resolveThemeAutoDetect -> ui/update.go:onBackgroundColor/switchTheme already select Solar for a light reply on a real TTY without explicit theme selection, rebuilding renderer/caches. Reuse that one-shot path.

Confirmed PR 1 contract

Accent headings and themes

• Both views: visible user, assistant and ordinary harness messages have ▶ you, ◀ mecatl, ◆ system headings. Glyphs and bold heading labels use actor accents; bodies stay neutral. No colored first physical answer line or actor-color wash over Markdown/code.
• Add comfort assistant headings; empty/whitespace-only assistants remain invisible. Add system headings only to already-visible ordinary notices. Preserve existing notice filtering; no newly exposed benign notices or invented empty-call notices.
• Preserve user border, Markdown/syntax styling, reasoning treatment, recovery/hook/delivery/permission/delegation status and provenance indicators. These are not ordinary system headings. No separate tools-batch heading besides the aggregate.
• Retain full internal transcript{LLM,Tool,User,Harness}{Marker,Rail,Text} vocabulary and immutable glyph data; add internal heading roles only if needed to keep bodies independent. Marker/rail defaults match but remain independently defined. Dormant rail roles do not render outlines.
• Aztec dark accents unchanged: LLM #c98f9d, Tool #57b8bf, User #e9b949, Harness #aaa0d4; normal body #e7e2d3, harness #bac8bf, run #6b857a, reasoning/statistics #9aaba0.
• Solar adopts saturated light accents: LLM #a13d62, Tool #006f7a, User #955b00, Harness #713bb0. Retain light body #202d28, harness #40554a, run #687b70, reasoning/statistics #52665b. Validate against actual built-in surfaces; adjust only if necessary for contrast, not by adding background fill.
• Targets: text/headings/markers 4.5:1, structural rails 3:1 on supported built-in surfaces; include reasoning/statistics/harness bodies. Custom/partial/built-in-name overrides remain palette-derived; Mono retains its existing grayscale-with-blue-accent palette and status colors, rather than acquiring Aztec/Solar recipes. Verify color-independent readability separately in reduced/no-color output. No public settings/JSON keys.
• Existing startup detection/explicit --theme/MECATUI_THEME/custom precedence remain. Absent/dark reply retains fallback; non-TTY does not probe. No new appearance switch, continuous monitoring, font or line-height controls.

Tool presentation groups

• A group is a maximal visible sequence of ordinary Tool/Subagent/Team cards after hidden/empty cards are skipped for that view. Any visible user, assistant, ordinary notice, hook, error, delivery or statistics card ends it. Same rule in both modes; visibility differences can change group membership.
• No inferred dispatcher boundaries from timing, provider IDs or empty model calls. Separate batches without a visible intervening message form one presentation group.
• Comfort replaces all settled members, including failures, with ● N tools run (singular for one), optional · F failed when nonzero, and discoverable resolved-keybinding hints for detailed view and Toolcalls. Even a singleton uses an aggregate. Failure count has error styling; tool marker/normal heading use tool accent. No duration estimate or token totals.
• Comfort places the settled aggregate first, immediately followed by all nonsettled cards in original relative order, even if an active call originally preceded completed ones. Underlying scrollback and Ctrl+T inventory order stay unchanged.
• Pending, awaiting-result, finalizing and finalizing-failed remain individually visible with existing bounded cards/delegation activity. No empty aggregate if none settled. Canonical settlement updates counts/removes the active card; recorded terminal failures use existing projection semantics.
• Detailed/F9 retains every call in source order: settled calls remain single per-call summary lines; active calls retain their cards. F9 does not expose arguments/results/child traces. Ctrl+T exposes full details in either view, including aggregated failures and delegations.
• Keep modal/key ownership and rebinding support. Hints use resolved bindings. No new collapse checkbox/preference/shortcut or mouse drill-down.

Spacing, copy, anchors and cache lifetime

• Both views have exactly one blank terminal row between visible response blocks/tool groups. No added blank rows between calls inside a group, including between aggregate and active cards. Detailed does NOT space each call separately.
• Retain internal card/body spacing and attached-statistics placement: attached annotations are not independent response blocks. No phantom/leading/trailing group gaps or connected run rails in blank rows. Detailed appendices keep separate ownership.
• Copy visible text only; never expand hidden tool payloads. Collapse/expand, disappearance or changed count may clear selections whose exact visible text cannot be proven. Preserve unchanged provable selections on resize/theme/update. General decorative-copy limitations and known Markdown soft-wrap provenance drift remain separate work.
• Summary text is derived display text, never a constituent body/arguments/result. Keep usable reading anchors through group growth, active settlement, F9 and resize using existing member identities and a small renderer-local member-to-row relation if needed. Preserve exact content anchors where possible; collapsed-member anchors land at the containing group, not tail/unrelated content. conversationView retains tail-follow ownership. No persisted summary IDs/second correlation store.
• Reuse per-card caches; derive counts/status from cheap metadata, without cloning settled results/artifacts on warm renders. Assembly/prefix validity accounts for membership/revisions/visibility/mode/width; theme switches rebuild the renderer. Appended calls can change an earlier aggregate even without earlier card re-render: rebuild from the affected group start, not just appended suffix. Cover hidden insertion, message visibility changes, non-tail result/failure changes and conversation rebuild/session switch. Do not retain old groups after rebuild.

Bite-sized implementation tasks

1. Baseline inventory and amendment fixtures. Preserve active branch/start OID and existing edits; read nested guidance. Inventory heading/projection/frame/string/cache/selection/binding owners. Add focused fixtures pinning confirmed changes, initially red where behavior is absent. Completion: old work intact; no assumed dependency on deferred identity series.
2. Accent headings and light recipe. Depends on 1. Theme seams, renderAssistantSnapshotFresh, structured_blocks.go, internal/blocks/plain_cards.go. Add comfort assistant and visible system headings; accent labels with neutral bodies/statuses. Update assistant provenance offsets in both modes, including collapsed reasoning/empty content. Test dark/light/custom/Mono, contrast, border, narrow/Unicode/sanitization and real light response/cache replacement. Completion: specified headings reach both actual views without changing filtering or outcome semantics.
3. Renderer-local group assembly. Depends on 1; integrate after 2's heading/visibility rules. Group visible tool-family passes using existing projection metadata; keep card renderers and scrollback unchanged. Retain only assembly data for order/counts and anchor membership. Implement group-aware prefix invalidation in frame/string paths together. Test hidden/empty bridging, visible boundaries, singleton/multiple groups, append/non-tail settlement/failure/delegation updates and warm-cache payload reuse. Completion: one transient grouping rule supplies both modes, no engine/client/storage/schema changes.
4. Comfort aggregates, detailed per-call lines and spacing. Depends on 2–3. Render truthful counts/failures and resolved binding hints; active cards follow immediately. F9 restores original-order per-call summary lines, not full payloads. Apply one inter-block/group row and zero intra-group rows; retain attached/internal spacing. Test active-only/settled-only/mixed/all-failed/finalizing-failed/terminal failure cases, boundaries, narrow wrapping/truncation, rebound keys/modals and absence of timing. Completion: scenario/golden output matches selected study behavior except omitted timing/outline grammar.
5. Anchors, selection and integration. Depends on 3–4; grouping isn't complete without this. Truthful derived summary provenance and existing-member anchors, no fake source offsets. Test visible summary copy, untouched prose/active selections, honest clear when changed/hidden, anchored reading within groups through count growth/settlement/F9/resize/theme, tail-follow, Ctrl+T open/close and conversation replacement/replay. Verify frame/string and cached/fresh equivalence and no warm settled-payload cloning. Completion: no hidden-content copy, stale prefixes or jumps to unrelated content.
6. Documentation, code review and gates. Depends on 2–5. Use tech-writer/owning guidance for docs/tui.md, user-docs/mecatui/themes.md and owning transcript/keybinding page if needed. Document comfort/F9 summary distinction, spacing and inspector, not unsupported schema/timing. Regenerate goldens via official update flags. Panel-review entire candidate against ac67d62; incremental fixes get targeted rechecks. Run gates below. Completion: independently useful amended PR candidate, no automatic commit/push/PR.

Tasks 3–5 are one integration group: don't ship aggregates without cache/provenance/anchor behavior. Task 2 can be developed separately after inventory; do not lose uncommitted edits in isolated delegation.

Acceptance and verification

• Both views/Aztec/Solar/Mono/custom show accent speaker headings, neutral Markdown bodies, invisible empty calls, unchanged filtering/safety/provenance meaning.
• Four settled calls with one failure yield ● 4 tools run · 1 failed plus resolved hints, no duration. F9 yields four source-order per-call lines without intra-group gaps; Ctrl+T contains all exact details.
• Active Subagent preceding completed Read/failing Shell and finalizing Grep yields a two-settled/one-failed summary, then Subagent/Grep in comfort; F9 retains Subagent/Read/Shell/Grep order. Finalizing failure never prematurely counts as settled.
• Hidden/empty cards bridge groups; visible user/assistant/notice/hook/delivery/error/stat boundaries split them. One row between response blocks/groups; zero between calls; no new gap for attached statistics.
• Group append across cached prefix, non-tail updates, changed visibility/boundaries/mode/width/theme and session rebuild match fresh output in frame/string paths; unrelated cached cards don't reload payloads.
• Copy never expands hidden calls or treats summary as member-source text. Preserve provable selections and reading positions; changed/disappeared selections clear; hidden-member anchors resolve to containing group. Exercise real Model/viewport integration, not just helper output.
• Startup tests cover actual light render/cache changes and TTY/explicit/custom/absent/dark/non-TTY gating. Rebinding tests assert hints and real dispatch/modal routing for detailed view and Toolcalls.
• Focused packages: go test ./cmd/mecatui/theme/... ./cmd/mecatui/ui/internal/blocks/... ./cmd/mecatui/ui/... ./cmd/mecatui/internal/renderfmt/... with task-specific -run filters; command-package startup/rebinding tests too. Offline/test-owned fixtures, including composition UserModelDir.
• Once integrated: task test. PR-ready gates: task lint, task test:race, task docs, task build, go run ./cmd/mecademo proving tool call/permission ask/approval/result. Full gates serial, 600-second limits. Existing Unix-socket path-length evidence favors Shell temp_scope:system for these gates; fixtures remain test-owned. No generated schema changes expected.
• Native terminal/font/cell-width appearance remains manual. No revision implementation tests ran during planning; static critique cannot prove runtime behavior.
• Plan stays ignored/uncommitted. If an implementation PR is separately authorized, archive one complete publishable plan in a verified PR comment per plan-implement; redact private paths/notes without dropping material contracts. No PR/comment creation during planning.

Larger rollout and ownership

1. This PR: accent headings, existing dark/light selection, comfort aggregation/F9 per-call projection, response/group spacing. No connected outlines/new telemetry.
2. Truthful live outline presentation: separately researched/reviewed successor; run rails, LLM enclosures, tool branches, expanded prompts and correct final detail closure. No synthetic timing/guessed totals/concurrency claims. PR 1 groups are not execution batches. History structure stays flat absent authoritative coverage; reconcile actual upstream identity/hook contracts first.
3. Measured timing: existing engine execution/wait measurements through canonical events/wire/results after canonical identity. Distinguish unknown/not-executed/measured zero, execution/wait/result release; test live/stored round trips; no audit joins/new IDs.
4. Remaining execution facts: audit landed contracts; only required model/run continuation, dispatcher-owned membership/order, terminal outcomes/measured phase intervals. Don't sum guessed parallel durations as elapsed time.
5. Durable history foundation: coordinate docs(drafts): committed session history and shared interaction design #2179 design (not shipped contract); ordered content/activity, checkpoint/cursor linkage, coverage/gaps, unfinished recovery, compaction. No outline-only ledger.
6. Historical semantic projection: canonical relationships/real timing; replay has no live approval/accounting/hooks/steer/continuation effects. Insufficient legacy history stays flat/explicitly partial.
7. Cursor reconnect: coherent load/follow, deduplication, gaps/session switches/continuations. Connection loss is observer state, not proof of server completion.

Other effort owns compatibility preflight -> canonical ToolCallID/provider replay separation/migration -> typed hook/review lifecycle -> TUI canonical correlation. Reconfirm landing before dependent work without touching that checkout. Nested Subagent/Team historical fidelity and grouped stylesheet inheritance/public customization are separate follow-ons. Preserve experiment detail-closure/Markdown provenance evidence; no opportunistic reducer/history redesign.

Decisions and review record

• Joe confirmed accent speaker headings in both modes, neutral bodies and no wrap-dependent colored first answer line.
• Joe confirmed comfort aggregation/failure counts without guessed timing; F9 one per-call summary line, full details Ctrl+T.
• Joe corrected detailed spacing: no rows between calls inside a group, one between response blocks/groups.
• Joe confirmed saturated light accents/existing startup detection and overrides.
• Joe confirmed visible-adjacency tool-family grouping including delegation; hidden/empty bridging, visible-message boundaries, settled-first comfort/active relative order and original-order F9.
• Joe confirmed visible-only copy, honest selection clearing when selected text changes/disappears, preserved unchanged provable selections/stable reading anchors. Design frontier settled; planning, not implementation authority.
• Fresh-context revision critique: no blockers found; one advisory noted that existing Mono is grayscale-with-blue-accent, not strictly monochrome (theme/builtins.go:72,96–100). Corrected the wording to preserve existing palette fallbacks/status colors, not redesign Mono. Reviewer inspected current lifecycle, metadata, rendering, startup and selection seams; the ignored plan was supplied inline. Static review only, no runtime tests or native appearance proof. Prior code review/gates cover older styling scope; amended implementation still requires integrated code review/gates.

Authorized reload-note follow-up

After manual inspection, Joe explicitly requested fixing internal harness control notes showing as you on session reload. The server's human-display transcript projection omits known background completion/pending and no-progress continuations only with positive stored harness provenance and no media; it preserves compaction summaries, scheduled results, other harness content and principal/unknown user lookalikes. No stored/model history or event replay is changed. Legacy records without attributable origin remain untouched; do not guess authorship from user text.

Implement at the existing common server snapshot projection, with a fresh outer message slice and existing immutable-message semantics; no new wire fields or engine APIs. Verify filtering/preservation/order/empty completion/storage invariants and real persisted embedded/connect restart -> client -> Model rendering. Update transcript contract comments through generators and owning resume docs. This is a narrow display bug fix, not the deferred durable-history/identity roadmap. Delivery authority remains local-only; evidence and final gates are in the run note.