feat(tui): v2 PR 5 — full screen-tree redesign + IA + render-cost teardown (stacks on #693)

[kelsonpw]

TL;DR

• Unique to this PR: full TUI v2 screen-tree polish — shared lifecycle glyph vocabulary, Operator Overview reframing of /status, mode badge in HeaderBar, /help slash command with mid-run grouping, and the useWizardSelector slice-hook infrastructure for render-cost discipline.
• Depends on: feat(orchestration): v2 PR 4 — widen wiring + retire WizardSession redundancy + supervisor + live status refresh (stacks on #691) #693 (PR 4 — wiring + supervisor + live refresh). Stacks feat(orchestration): v2 foundation — durable state, lifecycle, status/resume commands (PR 1 of 3) #689 → feat(orchestration): v2 PR 2 — user-choice + manual-verification checkpoints + MCP-app lifecycle (stacks on #689) #690 → feat(orchestration): v2 PR 3 — TUI integration + MCP-server tool parity + perf hot-paths + resilience (stacks on #690) #691 → feat(orchestration): v2 PR 4 — widen wiring + retire WizardSession redundancy + supervisor + live status refresh (stacks on #691) #693 → feat(tui): v2 PR 5 — full screen-tree redesign + IA + render-cost teardown (stacks on #693) #696. Final PR in the v2 stack.
• Most load-bearing test: src/ui/tui/screens/__tests__/StatusOverlayScreen.glyphs.test.tsx — pins the canonical glyph palette, the "what's blocking" summary headline, and the mode-badge + Blocked-vs-Running distinction.
• If you read one section, read this one: "Glyph palette (canonical vocabulary)" — every primary surface in the TUI now sources its state-symbol from src/ui/tui/utils/lifecycle-display.ts. Silent drift trips a unit test.

How to review without running

The diff is large. Below are the 7 files where most reviewable behavior lives, with what each one shows. Skim these in order to get the substance of the PR without checking out the branch.

1. src/ui/tui/utils/lifecycle-display.ts — Canonical glyph + label + color vocabulary mapping TaskLifecycle → {glyph, color, label}. This is the source-of-truth that all primary surfaces (operator overview, progress list, header) consume. The exhaustive switch keeps drift caught at compile time.
2. src/ui/tui/utils/__tests__/mode-badge.test.ts — Spec-as-test for mode-badge resolution priority (agent > ci > nested > mcp-server > suppressed in plain interactive). Reads top-to-bottom as the resolution rules; covers CLAUDECODE=1 and CLAUDE_CODE_ENTRYPOINT envs.
3. src/ui/tui/screens/StatusOverlayScreen.tsx — The Operator Overview itself. Sectioned by Session / Primary work / Background / Pending choices / Pending verifications / MCP capabilities / Owned artifacts / Next action. Includes the new "what's blocking the run?" headline summary.
4. src/ui/tui/screens/__tests__/StatusOverlayScreen.glyphs.test.tsx — Regression pins for the glyph palette, the summary headline ("Waiting on N choices…", "N primary task(s) in flight", etc.), the Blocked vs. Running distinction (⏸ red vs. › violet), and mode-badge rendering.
5. src/ui/tui/hooks/useWizardSelector.ts + src/ui/tui/hooks/__tests__/useWizardSelector.test.tsx — Slice-hook infrastructure with shallowArrayEqual / shallowObjectEqual. The render-cost ceiling test (src/ui/tui/__tests__/render-cost.test.tsx) demonstrates the ~60% render-budget cut for slice-subscribed components versus whole-store subscribers.
6. src/ui/tui/components/HeaderBar.tsx + src/ui/tui/components/__tests__/HeaderBar.modeBadge.test.tsx — Mode badge placement and conditional suppression in plain interactive mode.
7. src/ui/tui/__tests__/console-commands-help.test.ts — Locks down the /help text contract: which commands are listed, how they're grouped (always-available vs. paused-during-run), and the hanging-indent multi-line feedback rendering.

Recommended runtime check: pnpm try --install-dir=<some-test-app> and press /status — confirms the Operator Overview renders with the new glyphs, summary headline, and mode badge in the header.

---

Stacks on #693 → #691 → #690 → #689. Merge after PRs 1+2+3+4.

Problem

PRs 1–4 fixed the substrate (durable orchestration store, lifecycle, choice/verification primitives, supervisor with PID + heartbeats, live file-watcher refresh). The TUI surface was solid but unfinished:

• Some screens needed terminal resize to redraw after transitions.
• Prompts could disappear or get re-asked after a durable answer.
• "Success" UI showed up while a manual verification was still pending.
• Background agents were hard to distinguish from user-directed work.
• /status was usable but not refreshable while open.
• The slash-command bar was easy to miss during active runs.

PR 5 turns the TUI from "screens that mostly work" into a serious operator interface: coherent IA, shared glyph vocabulary, actionable operator overview, and render-cost discipline.

IA redesign

Three-zone layout (top → bottom):

1. Header (≤ 2 rows): JourneyStepper + identity + mode badge.
2. Body (flex, dominant): active screen content.
3. Chrome (≤ 3 rows): inline status pill, KeyHintBar, slash prompt.

The mode badge surfaces [agent] / [ci] / [nested] / [mcp-server] (suppressed in plain interactive mode). Resolution priority is documented in docs/tui-v2.md.

ASCII layout — 3 viewports

Wide (142×41)

✓ Welcome ─ ✓ Auth ─ ● Setup ←  ─ ○ Verify ─ ○ Done
Amplitude Wizard  [agent]                                                    · Acme / Web App / Production
─────────────────────────────────────────────────────────────────────────────────────────────────────────

Tasks                                                                       Discovered facts
✓ Detect framework                                                          · framework=Next.js
› Install Amplitude                                                         · package_manager=pnpm
○ Plan and approve events                                                   · TypeScript=yes
○ Wire up event tracking
  · Reading package.json
  · Running pnpm add @amplitude/analytics-browser

Standard (100×30)

✓ Welcome ─ ✓ Auth ─ ● Setup ←  ─ ○ Verify ─ ○ Done
Amplitude Wizard  [agent]                                · Acme / WebApp / Prod
──────────────────────────────────────────────────────────────────────────────

Tasks
✓ Detect framework
› Install Amplitude
  · Reading package.json
○ Plan and approve events
○ Wire up event tracking
──────────────────────────────────────────────────────────────────────────────
◆ Status: pnpm install (3.4s)
Tab=ask  ←/→=tabs  Ctrl+C=cancel
❯ Press / for commands

Narrow (80×24)

✓ ─ ✓ ─ ● ─ ○ ─ ○
Amplitude Wizard  [agent]                       · Acme / WebApp
─────────────────────────────────────────────────────────────────
Tasks
✓ Detect framework
› Installing Amplitude
○ Plan events
○ Wire up
─────────────────────────────────────────────────────────────────
◆ pnpm add … (3.4s)
Ctrl+C=cancel
❯ /

Glyph palette (canonical vocabulary)

Every primary surface shares one vocabulary:

State	Glyph	Color	Meaning
Queued	○	muted	Created, awaiting start
Running	›	violet	Actively executing
Waiting	…	blue	Paused on user choice / verification
Blocked	⏸	red	Cannot proceed (auth, network, dep)
Completed	✓	success	Terminal: success
Failed	✗	red	Terminal: failure
Cancelled	⊘	amber	Terminal: cancelled by user
Superseded	⮕	muted	Terminal: replaced by another task

Lives in src/ui/tui/utils/lifecycle-display.ts, sourced from TaskLifecycle. Pinned by unit tests so silent drift trips a test.

Screen tree changes

• Kept: Welcome, Auth phase screens, Setup/Run/Outro, all 6 overlays.
• Reframed: StatusOverlayScreen → "Operator Overview". Sectioned by Session / Primary work / Background / Pending choices / Pending verifications / MCP capabilities / Owned artifacts / Next action. Live-refresh via PR 4's useOrchestrationStore hook so a sibling shell running wizard choice answer … updates the open overlay without close+re-open.
• Augmented: HeaderBar gets a mode badge.

Prompt UX contract

Every choice prompt renders the full contract:

Field	Source
Why-asking	Choice.whyAsking
Options + descriptions	Choice.options[]
Recommended option	Choice.recommendedOptionId
Safe-default option	Choice.safeDefaultOptionId
Reversible	Choice.reversible
Requires human	Choice.requiresHuman
Consequence if skipped	Choice.consequenceIfSkipped
Resume command	Choice.resumeCommand
Skip safety	derived: safe-default + !requires-human + reversible

ChoiceCheckpointBanner renders the full block; the operator overview renders an inline condensed version that still includes every field.

Slash command coherence

New /help command lists every registered command grouped by "available anytime" vs "available before/after a setup run". When a run is active, the second group renames itself "paused while a setup run is active (Ctrl+C to cancel, then retry)" so the user knows exactly why a command can't fire and what to do.

Multi-line command feedback (e.g. /help, /diagnostics) now renders with a hanging indent so it reads as one coherent block, not several disconnected lines.

Render-cost teardown

New useWizardSelector(store, selector, isEqual?) slice hook. Components subscribed to a slice no longer rerender for unrelated store ticks. shallowArrayEqual and shallowObjectEqual exported alongside.

Render-cost benchmark fixture (src/ui/tui/__tests__/render-cost.test.tsx):

Subscriber type	3 task transitions + 5 status bumps
Whole-store	8+ renders
Tasks slice	3 renders
Status slice	5 renders

Slicing cuts each subscriber's render budget by ~60% in this scenario. The infrastructure ships in PR 5; migrating individual subscribers is incremental.

Bugs addressed (with regression-test refs)

• Mode-badge invisibility for nested-agent invocations — CLAUDECODE=1 / CLAUDE_CODE_ENTRYPOINT now surface as [nested] in the header and in the operator overview. Test: src/ui/tui/utils/__tests__/mode-badge.test.ts, src/ui/tui/screens/__tests__/StatusOverlayScreen.glyphs.test.tsx.
• Operator overview blocked-vs-running confusion — Blocked state now renders the distinct ⏸ glyph + red color, separate from running › + violet. Test: StatusOverlayScreen.glyphs.test.tsx.
• Multi-line slash feedback wrapping awkwardly — feedback now hanging-indents continuation lines instead of single-line truncation. Covered by console-commands-help.test.ts (text contract) and existing ConsoleView tests.
• No "what's blocking the run?" headline in the operator overview — added a 1-line summary that resolves to "Waiting on N choices from you" / "Waiting on N manual verifications" / "N primary task(s) in flight" / "Session active — no pending action" / "No active session". Test: StatusOverlayScreen.glyphs.test.tsx::summary headline.

The brief's other bug categories (success-while-pending, prompt re-ask after durable answer, prompts that disappear) are already covered by PR 3's ManualVerificationRibbon integration and the existing ChoiceCheckpoint.test.tsx / OutroScreen.verificationRibbon.test.tsx regression tests, which pass on PR 5.

Tests added

40 new tests over the base 3949 (3989/3989 vitest):

• 5 — lifecycle-display vocabulary
• 9 — mode-badge env resolution
• 6 — /help text generation
• 5 — HeaderBar mode badge rendering
• 4 + 3 — useWizardSelector primitives + render-cost ceiling
• 7 — StatusOverlayScreen glyph palette + summary + mode badge
• 1 — StatusOverlayScreen Operator Overview reframing (existing test updated)

Backward compatibility

• All existing slash commands continue to work the same way; /help is additive.
• /status overlay's data shape is unchanged from PR 3; only the rendering reorganized.
• --agent, --ci, --json, manifest, plan, apply, verify, MCP server, v: 1 envelope, exit codes — all unchanged.
• Mode badge is suppressed in plain interactive mode, preserving the prior header look for the most common case.
• ProgressList still uses a blank gutter for pending rows rather than the canonical ○ glyph (deliberate UX trade-off — see comment in ProgressList.tsx).

Known limitations & follow-ups

• The render-cost helpers exist (useWizardSelector); migrating every subscriber over is out of scope for PR 5. The infrastructure is in place; the migration is incremental.
• The operator overview is rendered via the same overlay infrastructure as before; it doesn't yet support keyboard-actionable choice resolution from inside the overlay.

Test plan

• pnpm exec vitest run --pool=forks --maxWorkers=1 — 277 files / 3989 tests pass
• pnpm test:bdd — 100/100 scenarios pass
• pnpm build (TypeScript + smoke test) — clean
• pnpm lint — clean (only pre-existing warning unchanged)

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds new orchestration-related CLI commands and MCP tool surfaces plus changes to credential-resolution signaling, which can affect automation and operator workflows if schemas/exit codes drift. Most changes are additive and covered by new schema-validated smoke tests, but they touch user-facing command routing and external contracts.

Overview
Introduces a durable orchestration inspection surface across the CLI and the external MCP server, adding tasks/task/sessions/session/resume/orchestration status plus choice and verification subcommands with documented extended exit codes and JSON envelopes.

Wires a first “beachhead” mirror for agent-mode environment selection into the orchestration store (records an environment_selection choice and marks it answered), and updates credential resolution to return a discriminated outcome that is logged by bin.ts for debuggability.

Expands docs/README with /status and TUI v2/operator concepts, adds shared orchestration CLI helpers (install-dir resolution, JSON error envelopes), and adds extensive new tests (CLI smoke tests against real binary, MCP-server orchestration tool parity, SSE frame suppression, and per-run cache memoization).

^{Reviewed by Cursor Bugbot for commit 6210b95. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Primary tasks render glyph twice (double glyph)
  • Removed the StateBadge component (which rendered its own glyph) from the primary tasks section and inlined just the label text, matching the pattern used by background tasks to render the glyph exactly once per row.

Or push these changes by commenting:

@cursor push 97259f1ad4

Preview (97259f1ad4)

diff --git a/src/ui/tui/screens/StatusOverlayScreen.tsx b/src/ui/tui/screens/StatusOverlayScreen.tsx
--- a/src/ui/tui/screens/StatusOverlayScreen.tsx
+++ b/src/ui/tui/screens/StatusOverlayScreen.tsx
@@ -56,24 +56,13 @@
 import { ChoiceStatus } from '../../../lib/orchestration/checkpoints/choices.js';
 import { VerificationStatus } from '../../../lib/orchestration/checkpoints/verifications.js';
 import { resolveMode } from '../utils/mode-badge.js';
-import {
-  lifecycleDisplay,
-  type LifecycleDisplay,
-} from '../utils/lifecycle-display.js';
+import { lifecycleDisplay } from '../utils/lifecycle-display.js';
 import { TaskLifecycle } from '../../../lib/orchestration/lifecycle.js';
 
 interface StatusOverlayScreenProps {
   store: WizardStore;
 }
 
-/** Compact "glyph + label" badge used in every section. */
-const StateBadge = ({ display }: { display: LifecycleDisplay }) => (
-  <Text color={display.color} bold>
-    {display.glyph}{' '}
-    <Text color={display.color}>{display.label}</Text>
-  </Text>
-);
-
 /**
  * Section header — bold, secondary color, with a count badge.
  * Pulled out so the operator overview's many sections share the same
@@ -262,7 +251,7 @@
                 {display.glyph}{' '}
               </Text>
               <Text color={Colors.body}>
-                <StateBadge display={display} /> — {t.label}
+                <Text color={display.color}>{display.label}</Text> — {t.label}
               </Text>
             </Box>
           );

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Autofix Details

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: shallowObjectEqual fails for objects with different keys
  • Added Object.prototype.hasOwnProperty.call(b, k) check before the value comparison so objects with the same key count but different key names are correctly detected as unequal.

Or push these changes by commenting:

@cursor push 931ca6d84a

Preview (931ca6d84a)

diff --git a/src/ui/tui/hooks/useWizardSelector.ts b/src/ui/tui/hooks/useWizardSelector.ts
--- a/src/ui/tui/hooks/useWizardSelector.ts
+++ b/src/ui/tui/hooks/useWizardSelector.ts
@@ -107,7 +107,8 @@
   const bk = Object.keys(b);
   if (ak.length !== bk.length) return false;
   for (const k of ak) {
-    if (!Object.is(a[k], b[k])) return false;
+    if (!Object.prototype.hasOwnProperty.call(b, k) || !Object.is(a[k], b[k]))
+      return false;
   }
   return true;
 }

_{You can send follow-ups to the cloud agent here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: StatusOverlayScreen shows mode badge in interactive mode
  • Added a showBadge guard (mode.key !== 'interactive') to conditionally render the mode badge in StatusOverlayScreen, matching the existing suppression logic in HeaderBar.

Or push these changes by commenting:

@cursor push a111fe2fd9

Preview (a111fe2fd9)

diff --git a/src/ui/tui/screens/StatusOverlayScreen.tsx b/src/ui/tui/screens/StatusOverlayScreen.tsx
--- a/src/ui/tui/screens/StatusOverlayScreen.tsx
+++ b/src/ui/tui/screens/StatusOverlayScreen.tsx
@@ -157,6 +157,7 @@
 
   const lsp = data.status.lastStoppingPoint;
   const mode = resolveMode();
+  const showBadge = mode.key !== 'interactive';
 
   // Split active tasks into "primary" (running/waiting/blocked) and
   // "background" (everything else among the active set — supervisor's
@@ -205,10 +206,14 @@
           <Text bold color={Colors.accent}>
             {Icons.diamond} Operator overview
           </Text>
-          <Text color={Colors.subtle}> {Icons.dot} </Text>
-          <Text color={mode.color} bold>
-            [{mode.label}]
-          </Text>
+          {showBadge && (
+            <>
+              <Text color={Colors.subtle}> {Icons.dot} </Text>
+              <Text color={mode.color} bold>
+                [{mode.label}]
+              </Text>
+            </>
+          )}
         </Box>
         <Text color={Colors.body}>{summary}</Text>
         <Text color={Colors.muted}>

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 8a800c0. Configure here.}

[kelsonpw]

V2 PR 5 (full TUI v2 screen-tree redesign) — replaced by V3 polish work landed and pending across the TUI v3 chain. Closing per direction change. Audit by subagent a209c551541d85df3.