feat(tui): v3 foundation — low-risk consensus wins from 5-subagent audit

[kelsonpw]

Why this PR exists

Five expert TUI subagents independently audited the codebase. This PR ships the intersection of their consensus low-risk recommendations — boring, defensible wins that pave the way for the v3 redesign work tracked elsewhere without touching its surface area.

Every change is its own atomic commit so a reviewer can bisect, revert one without the others, or cherry-pick into a hotfix branch.

The 8 changes

#	Commit	What	Files
1	refactor(tui): remove unused Screen.Options enum	Dead enum entry + null registry slot, never reachable	src/ui/tui/flows.ts, src/ui/tui/screen-registry.tsx
2	feat(tui): register /help slash command	docs/flows.md and CLAUDE.md both promise /help; the COMMANDS registry never had it. Add registration + dispatcher with categorized cheatsheet	src/ui/tui/console-commands.ts, src/ui/tui/components/ConsoleView.tsx
3	feat(tui): /<Tab> autocompletes to longest common prefix	Tab inside the slash picker was silently dropped. Wire CLI-style LCP autocomplete (/d → no-op, /diag → /diagnostics)	src/ui/tui/primitives/SlashCommandInput.tsx
4	feat(tui): pin Events tab to RunScreen always	Conditional spread on eventPlan.length > 0 made the tab strip re-index mid-run when the agent's first plan landed. EventPlanViewer already has an empty-state placeholder	src/ui/tui/screens/RunScreen.tsx
5	refactor(tui): demote Snake to overlay-only	Snake was a tab next to Progress / Events / Logs. Easter eggs don't deserve workspace slots; /snake slash command + Overlay.Snake still work	src/ui/tui/screens/RunScreen.tsx
6	refactor(tui): remove redundant InlineEventPlan + ConditionalTips	InlineEventPlan duplicated the Events tab; ConditionalTips only existed to surface a Stripe doc link, which now rides as a 'stripe' DiscoveryFact pushed by agent-runner	src/ui/tui/screens/RunScreen.tsx, src/lib/agent-runner.ts
7	fix(tui): hoist OutroScreen useEffect above early return	A useEffect lived AFTER if (!outroData) return <FinishingUp /> — rules-of-hooks violation. The outroData: null → success transition would trip React's "Rendered more hooks than" error	src/ui/tui/screens/OutroScreen.tsx
8	fix(tui): McpScreen leads with value prop, names only detected clients	Pre-detection copy named Claude Code / Cursor / Claude Desktop BEFORE detection ran — promising tools we hadn't found. Lead with the value prop; detected list surfaces post-detection; Phase.None gains a amplitude-wizard mcp serve fallback hint	src/ui/tui/screens/McpScreen.tsx

Test coverage added

Each behavioral change has a pinning test next to its source:

• src/ui/tui/__tests__/console-commands.test.ts — /help + /snake registry + getHelpText categorized output
• src/ui/tui/primitives/__tests__/SlashCommandInput.test.ts — longestCommonPrefix unit tests
• src/ui/tui/primitives/__tests__/SlashCommandInput.tab.test.tsx — end-to-end Tab autocomplete via stdin
• src/ui/tui/screens/__tests__/RunScreen.spacing.test.tsx — Events tab always present, Snake absent from strip, ConditionalTips banner gone, EventPlanViewer renders on plan flip
• src/ui/tui/screens/__tests__/OutroScreen.hookOrder.test.tsx — outroData: null → success transition produces no console.error matching "Rendered .* hooks than"
• src/ui/tui/screens/__tests__/McpScreen.copy.test.tsx — Phase.Detecting names no client, Phase.Ask shows detected list, Phase.None hints at the fallback subcommand

Existing snapshot regenerated: src/ui/tui/screens/__tests__/__snapshots__/McpScreen.snap.test.tsx.snap.

Gates

• pnpm exec tsc --noEmit — clean
• pnpm exec eslint src/ --cache — 0 errors, 1 pre-existing warning in EventPlanFullScreen.test.tsx (unrelated defaultFlow import that's been on main since fix(p0): render event-plan as full-screen overlay #626; not touched here)
• pnpm build + smoke — clean
• pnpm exec vitest run --pool=forks --maxWorkers=1 — 3830 tests pass across 257 files

Out-of-scope (deferred to follow-up PRs)

The 5-subagent audit also flagged the following higher-blast-radius items. They will each be their own PR so the review surface stays small:

• CreateAccount flow consolidation (multi-step prompt fan-in)
• AccountConfirm screen extraction from AuthScreen
• Journey-stepper bucket fix (current bucket sometimes lags by one entry)
• Error-boundary recovery card (replace the bare ErrorFallback text with a recover/exit picker)

🤖 Generated with Claude Code

---

Note

Low Risk
Primarily TUI UX/flow cleanups and test additions, with minimal behavioral impact beyond command input handling and small UI routing changes.

Overview
Improves the TUI Run experience by keeping the Events tab always present (preventing tab index shifts mid-run) and moving Snake out of the tab strip to overlay-only access via /snake.

Adds Tab-based slash-command autocomplete in SlashCommandInput (longest common prefix, ignoring description-only matches) and pins related behavior with new tests.

Moves the Stripe “connect as data source” affordance from a RunScreen banner into agent-runner as a stripe discovery fact, fixes a rules-of-hooks early-return issue in OutroScreen, and refreshes McpScreen copy to avoid naming editors pre-detection (with a fallback hint to use amplitude-wizard mcp serve).

^{Reviewed by Cursor Bugbot for commit 49c6f17. 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: Tab autocomplete LCP includes description-matched commands
  • Filtered the LCP computation to only include commands whose cmd starts with the typed prefix (query), excluding description-only matches that were diluting the longest common prefix.

Or push these changes by commenting:

@cursor push a9b6914430

Preview (a9b6914430)

diff --git a/src/ui/tui/primitives/SlashCommandInput.tsx b/src/ui/tui/primitives/SlashCommandInput.tsx
--- a/src/ui/tui/primitives/SlashCommandInput.tsx
+++ b/src/ui/tui/primitives/SlashCommandInput.tsx
@@ -147,7 +147,11 @@
         // /debug + /diagnostics, but the picker stays open so they can
         // disambiguate with the next keystroke).
         if (isSlashMode && filtered.length > 0) {
-          const lcp = longestCommonPrefix(filtered.map((c) => c.cmd));
+          const prefixMatches = filtered.filter((c) =>
+            c.cmd.slice(1).toLowerCase().startsWith(query),
+          );
+          if (prefixMatches.length === 0) return;
+          const lcp = longestCommonPrefix(prefixMatches.map((c) => c.cmd));
           if (lcp.length > value.length) {
             setValue(lcp);
             setSelectedIndex(0);

_{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: Duplicated longestCommonPrefix utility function
  • Extracted the duplicated function to a shared module at src/ui/tui/utils/longest-common-prefix.ts and updated both PathInput.tsx and SlashCommandInput.tsx to import and re-export from it.

Or push these changes by commenting:

@cursor push 8925239752

Preview (8925239752)

diff --git a/src/ui/tui/components/PathInput.tsx b/src/ui/tui/components/PathInput.tsx
--- a/src/ui/tui/components/PathInput.tsx
+++ b/src/ui/tui/components/PathInput.tsx
@@ -31,7 +31,10 @@
 import { useState, useMemo, useRef, useEffect } from 'react';
 import { readdirSync, type Dirent } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute as pathIsAbsolute, resolve as pathResolve } from 'node:path';
+import {
+  isAbsolute as pathIsAbsolute,
+  resolve as pathResolve,
+} from 'node:path';
 
 import { useScreenInput } from '../hooks/useScreenInput.js';
 import { Colors, Icons } from '../styles.js';
@@ -142,9 +145,7 @@
   // Strip the trailing slash so `expandTilde` + `path.resolve` work
   // on the directory itself rather than on a path with a trailing
   // separator that happens to land on a file later.
-  const withoutTrailingSlash = stem.endsWith('/')
-    ? stem.slice(0, -1)
-    : stem;
+  const withoutTrailingSlash = stem.endsWith('/') ? stem.slice(0, -1) : stem;
   // A bare "~" expands to homedir. A bare "/" stays as the root.
   if (withoutTrailingSlash === '') return '/';
   if (withoutTrailingSlash === '~') return homedir();
@@ -205,24 +206,8 @@
   return { stem, partial, candidates };
 }
 
-/**
- * Compute the longest common prefix of an array of strings. Used when
- * Tab finds multiple matches: shells fill the prompt with the LCP and
- * leave the rest to the user.
- */
-export function longestCommonPrefix(items: string[]): string {
-  if (items.length === 0) return '';
-  if (items.length === 1) return items[0];
-  let prefix = items[0];
-  for (let i = 1; i < items.length; i++) {
-    const s = items[i];
-    let j = 0;
-    while (j < prefix.length && j < s.length && prefix[j] === s[j]) j++;
-    prefix = prefix.slice(0, j);
-    if (prefix === '') return '';
-  }
-  return prefix;
-}
+import { longestCommonPrefix } from '../utils/longest-common-prefix.js';
+export { longestCommonPrefix };
 
 /**
  * Replace the trailing segment of `input` with `candidateName`, optionally
@@ -251,7 +236,9 @@
   const [value, setValue] = useState(() => shortenHomePath(initialValue));
   // Caret position (number of chars from the start). We render a
   // block cursor at this index.
-  const [cursor, setCursor] = useState(() => shortenHomePath(initialValue).length);
+  const [cursor, setCursor] = useState(
+    () => shortenHomePath(initialValue).length,
+  );
 
   // Last validation error, cleared when the user types.
   const [error, setError] = useState<string | null>(null);
@@ -365,7 +352,11 @@
       setCandidates(result.candidates);
       baselineRef.current = value;
       const first = direction === 1 ? 0 : result.candidates.length - 1;
-      const previewed = applyCompletion(value, result.candidates[first].name, false);
+      const previewed = applyCompletion(
+        value,
+        result.candidates[first].name,
+        false,
+      );
       setValue(previewed);
       setCursor(previewed.length);
       setCycleIndex(first);

diff --git a/src/ui/tui/primitives/SlashCommandInput.tsx b/src/ui/tui/primitives/SlashCommandInput.tsx
--- a/src/ui/tui/primitives/SlashCommandInput.tsx
+++ b/src/ui/tui/primitives/SlashCommandInput.tsx
@@ -33,28 +33,8 @@
   );
 }
 
-/**
- * Returns the longest common prefix shared by every string in `values`.
- * Returns the input itself if `values` has a single entry, and `''` if
- * the input is empty. Used by Tab autocomplete: typing `/d` then Tab
- * extends the input to `/d` (no common prefix beyond the current input
- * across /debug, /diagnostics), while `/diag` + Tab extends to
- * `/diagnostics`.
- */
-export function longestCommonPrefix(values: string[]): string {
-  if (values.length === 0) return '';
-  if (values.length === 1) return values[0];
-  let prefix = values[0];
-  for (let i = 1; i < values.length; i++) {
-    const candidate = values[i];
-    let j = 0;
-    const maxLen = Math.min(prefix.length, candidate.length);
-    while (j < maxLen && prefix[j] === candidate[j]) j++;
-    prefix = prefix.slice(0, j);
-    if (prefix === '') return '';
-  }
-  return prefix;
-}
+import { longestCommonPrefix } from '../utils/longest-common-prefix.js';
+export { longestCommonPrefix };
 
 interface SlashCommandInputProps {
   commands?: SlashCommand[];
@@ -155,13 +135,9 @@
         // is `/d`, shorter than `/diag` itself — so Tab would be a
         // no-op when the user explicitly wants /diagnostics filled in.
         if (isSlashMode && filtered.length > 0) {
-          const lcpCandidates = filtered.filter((c) =>
-            c.cmd.startsWith(value),
-          );
+          const lcpCandidates = filtered.filter((c) => c.cmd.startsWith(value));
           if (lcpCandidates.length > 0) {
-            const lcp = longestCommonPrefix(
-              lcpCandidates.map((c) => c.cmd),
-            );
+            const lcp = longestCommonPrefix(lcpCandidates.map((c) => c.cmd));
             if (lcp.length > value.length) {
               setValue(lcp);
               setSelectedIndex(0);

diff --git a/src/ui/tui/utils/longest-common-prefix.ts b/src/ui/tui/utils/longest-common-prefix.ts
new file mode 100644
--- /dev/null
+++ b/src/ui/tui/utils/longest-common-prefix.ts
@@ -1,0 +1,20 @@
+/**
+ * Returns the longest common prefix shared by every string in `items`.
+ * Returns the input itself if `items` has a single entry, and `''` if
+ * the input is empty. Used by Tab autocomplete in both slash-command
+ * and path-completion contexts.
+ */
+export function longestCommonPrefix(items: string[]): string {
+  if (items.length === 0) return '';
+  if (items.length === 1) return items[0];
+  let prefix = items[0];
+  for (let i = 1; i < items.length; i++) {
+    const candidate = items[i];
+    let j = 0;
+    const maxLen = Math.min(prefix.length, candidate.length);
+    while (j < maxLen && prefix[j] === candidate[j]) j++;
+    prefix = prefix.slice(0, j);
+    if (prefix === '') return '';
+  }
+  return prefix;
+}

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

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

[kelsonpw]

Closing — V3 foundation work largely superseded by the merged salvage cluster (#763, #764, #770, #772, #773 + the in-flight #765-#771). Cherry-picked salvages preserved this PR's distinct content piecemeal; the original branch carries v2 orchestration history that won't merge to main.