feat(tui): track transcript reading and session navigation improvements

[me2seeks]

Problem

Long-session reading is split between Ctrl+O (tool expansion), Ctrl+T (thinking expansion), and /transcript. Finding an earlier exchange requires scrolling, and Session selection needs better search and orientation. Some failed text tool results show only a colored status disc plus line/byte counts, so failure is not explicit in monochrome output.

Current baseline, verified in packages/cli/src/pi-tui-runner.ts:

• /resume continues the current Session from its latest safe boundary; it is not the Session picker.
• /session opens the picker; Enter switches to the selected Session. Tab already switches Current / All. Improve this existing capability rather than introducing it again.
• /rename <new name> directly renames the current Session and updates the terminal title; it is refused during a running Turn.
• Tool cards already provide compact summaries, protected status/exit annotations, bounded output, and expanded details. Consecutive tool rows intentionally have no blank gaps.

This tracker is owned by @me2seeks. The scope below reflects the agreed UX direction; exact keybindings and layouts still need implementation-level validation.

Desired outcome

Work	Before	Target behavior
Unified detailed reading	Separate thinking/tool toggles and reader	One detailed transcript entry point shared with /transcript, preserving event order. Evaluate Ctrl+O to enter/leave and Ctrl+E to expand/collapse; resolve existing key conflicts.
Reading continuity	The reader tracks rendered rows; cross-mode/expansion anchoring needs improvement	Preserve the viewed message/tool and local position during toggles and new output. Collapse to its heading if necessary. Follow the tail only when already following or explicitly requested. Preserve the draft.
Search as a reading aid	Scrolling and paging are the main way to locate old content	Keep normal scrolling/paging. Add search that locates original text, then lets the user continue scrolling; cancelling returns to the prior reading position. A separate tree/index is not required for this first slice.
/session discovery	Existing selectable list with Tab Current / All	Improve search, recent sorting and useful filtering over the existing scopes; make scope, project/path and selected identity clear. Retain search text across scope changes. Show only metadata actually available from the owner.
Picker orientation	Existing list needs a preview/focus usability evaluation	Evaluate a bounded read-only excerpt/path preview before switching. Enter still opens directly, without a mandatory action menu. Maintain a visible selection across valid refreshes; ignore stale results.
Local tool-summary improvements	Some failed text results collapse to line/byte counts	Add explicit failure wording, and a bounded safe reason when available. Preserve successful one-line summaries, protected exit/status annotations, and compact tool stacks.
Targeted expanded-result layout	Some structured results combine status, identifiers and content into long lines	Compare representative outputs and improve summary/item/metadata separation only where the comparison demonstrates a readability gain. No blanket tree-line or multi-line card redesign.
Contextual hints and narrow terminals	Existing views need consistent usability validation	Show actions relevant to the focused view. Prioritize readable titles, status and essential controls over secondary columns; keep full paths inspectable and search matches visible.

• Implement unified detailed reading with normal scrolling and stable reading anchors.
• Add auxiliary transcript search; distinguish collapsed content from unloaded/unsearched history. Browsing must not rewind, branch, or change execution context.
• Improve the existing /session picker: search, scope/path clarity, ordering/filtering, and stable selection. Evaluate preview layout with real terminal examples before choosing it.
• Fix failed text summaries that rely on color alone. Use existing redacted/presentable result facts; full output remains available in details.
• Compare structured expanded results before/after and make only demonstrated layout improvements. Preserve the compact success path and existing stream truncation/metadata behavior.
• Validate contextual hints, Chinese wrapping, monochrome output, narrow terminals and resizing with screenshots or recordings.
• Verify streaming during historical reading, repeated expansion, pending interactions, duplicate names, empty results, cross-directory switching, stale list/preview responses, Host changes, and vanished selections. Cancel/failure must preserve the current Session and draft; clipboard failure must not replace editor text.

Keep /resume safe-boundary continuation and /rename <name> direct current-session renaming. A selected-row action menu, left/right action carousel, rename-other-session shortcut, and deletion UI are not committed scope. Switching sessions must not gain an extra confirmation/menu step.

Session selection restoration is scoped to the current Host and valid query/projection context, not an old row number. Previews use the existing read-only data path. Runtime Host retains execution, Session/Turn lifecycle, permissions, metadata writes and recovery authority; the TUI owns presentation and navigation. Do not introduce another transcript/task store.

Deliver focused PRs with same-scenario before/after evidence and limitations. A slice does not automatically close this tracker. Material product decisions follow the public dev@maka.apache.org discussion process in CONTRIBUTING.md; implementation details can be reviewed in PRs.

Alternatives or workarounds

Existing shortcuts, terminal scrollback, /transcript, /session and /rename remain the baseline. Keep pi-tui and Maka's visual language. A mandatory navigation tree or a blanket tool-card redesign is not necessary to meet the goals.

Reference study (source/document inspection; full terminal acceptance remains outstanding):

• Command Code 1.50.1: unified detailed reading and compact task output. Do not copy its reported toggle-to-bottom behavior, estimated thinking durations, billing or hosted services. Its installed rendering implementation uses React/Ink.
• pi-tool-display: summary/preview density; Maka already has truncation and summaries, so compare readability rather than add another pipeline.
• Crush Session dialog: contextual hints and narrow-screen secondary-column handling, not mandatory Session management menus.
• fzf preview and lazygit scroll margin: inspect before selecting and retain nearby list context. Maka supplies its own bounded read-only preview, not shell preview commands.
• pi session-search and pi-input-history: visible search matches and explicit action semantics. Do not copy local JSONL scans, draft-replacing clipboard fallbacks, or new persistent input stores.

Settings commands remain undecided; inline diff emphasis is deferred. Branch execution, worktree management, cloud sharing, new notification systems and persistent prompt history are outside this scope. Direct code reuse requires provenance/license review.

Related work:

• feat(cli): add an in-app transcript viewer for long TUI sessions #2997: existing transcript reader foundation.
• feat(cli): TUI resume has no discovery surface — no interrupted-session hint, and /resume errors when no session is attached #3508 / fix(cli): discover resumable sessions from /resume #3582: related recovery/discovery work; refresh before implementation without conflating current /resume and /session semantics.
• feat(tui): trial an anchored composer in fullscreen mode on nightly #4136 / feat(tui): trial an anchored composer in fullscreen mode on nightly #4221: anchored-composer experiment originating in @me2seeks's Discussion Should the TUI composer stay visible while reading scrollback? #3879, delegated to another contributor. Coordinate scrolling/selection/copy; do not reclaim the work or decide fullscreen defaults here.

Inspected baseline: 5a1514c1d43894691186174cc0683e0b6fd88f53. Key evidence: pi-tui-runner.ts (resumeSession, showSessionList, rename), pi-tui-transcript-viewer.ts, pi-transcript-tools.ts (textResultSummary, compactToolSummary), and the failed-Read compact-output case in packages/cli/src/__tests__/pi-transcript.test.ts.

AI assistance disclosure: Drafted and updated with Codex at the author's direction, with GPT-5.6-luna subagents assisting research and review.

Implementation progress

Implementation progress (the tracker remains open):

• feat(cli): unify detailed transcript navigation #5029 — unified detailed reader, per-entry reading anchors, auxiliary search, and draft/pending-interaction preservation. Final CLI suite: 866 passed, 0 failed, 3 existing skips. First opening still starts at the tail; search covers currently rendered loaded text only.
• feat(cli): add searchable session picker #5027 — searchable /session picker over the existing Current/All scopes, query and valid selection retention, and foreign-session path search. Enter still opens directly. Ordering/filtering beyond text search, bounded previews, and long-path layout remain to be evaluated.
• fix(cli): label failed text tool summaries #5028 — merged: explicit failure labels for generic text results. fix(cli): separate failure outcomes from output sizes #5037 follows up on UX feedback by removing error-text line/byte counts from failed summaries; existing terminal/shell exit-code summaries and successful rows remain unchanged.

All three slices use isolated worktrees and passed repository lint, formatting, build, typecheck, and the required workspace dependency checks. PR bodies use the project template, English main text, and collapsed Chinese explanations. Human review and hosted CI remain separate from local validation. #5028 was merged by a separate operation while follow-up work was in progress; this implementation/review-handling run has not approved or merged PRs.

Remaining: representative structured-result comparisons, broader narrow-terminal/resize recordings, picker preview/layout evaluation, and the full cross-Host/stale-result acceptance matrix. The original checklist remains open until the corresponding work is integrated and verified.

Current Todo view — agreed implementation slice

• feat(cli): add current Todo indicator and read-only view #5046 adds a single-line current Todo indicator above the composer and a read-only, scrollable /todo overlay. Ctrl+O remains the detailed transcript entry point.
• The current snapshot comes from existing session.todo.query; existing Todo domain notifications and subscription recovery invalidate it. No text parsing, polling, new Host wire schema, Todo tool changes, or storage changes.
• Historical tool rows remain unchanged. This is not a Todo history feature: later writes replace the current snapshot, and completed means model-reported completion.
• Empty lists hide the indicator; query failure/unsupported capability shows unavailable rather than empty. Session changes and teardown discard late responses. Long items wrap; small terminals preserve composer space. Pending permission/question/form interactions take priority over the Todo overlay.
• Local verification: CLI 906 passed / 0 failed / 3 existing skips; Runtime Host client subscription 28 passed; build, typecheck, lint, formatting, TUI copy checks and required dependency checks passed. Independent review completed. The PR includes rendered before/after evidence; live-provider/manual terminal recordings remain outstanding.

This slice is proposed in a PR, not merged. The broader tracker remains open.

[me2seeks]

take