Make the gx launcher explain pane control (#495)

The zero-argument launcher is now the first pane users see, so it needs to teach the same dmux/cockpit actions instead of spending the main area on decoration.

Constraint: Existing agent-selection and dry-run launch behavior must stay stable.

Rejected: Implement terminal-pane creation inside agents start | terminal pane runtime already belongs to gx cockpit and would widen this UI pass into session orchestration.

Confidence: high

Scope-risk: narrow

Directive: Keep cockpit-only actions as guidance here until terminal/project pane creation is wired through the cockpit runtime.

Tested: node --test test/agents-selection-panel.test.js test/agents-start-dry-run.test.js

Tested: node --check src/agents/selection-panel.js

Tested: openspec validate agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02 --type change --strict

Tested: openspec validate --specs

Tested: git diff --check

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

openspec/changes/agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-30

openspec/changes/agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02/proposal.md

@@ -0,0 +1,15 @@
+## Why
+
+- The `gx` zero-argument launcher opens a terminal panel, but the right side was decorative and the visible `[t]erminal` / pane-management cues did not explain how they map to the existing dmux cockpit controls.
+- Users need the launcher home to behave like a compact pane-management command surface: clear task entry, clear selected agent state, and visible dmux pane shortcuts without moving focus to a separate sidebar first.
+
+## What Changes
+
+- Replace the decorative launcher body with a bounded Pane Management shortcut map modeled on the existing `gx cockpit`/dmux commands.
+- Clarify task-input mode versus launch/action mode so typing a task is not confused with terminal pane shortcuts.
+- Add reducer coverage for `?`, terminal guidance, and `Alt+Shift+M` pane-menu guidance.
+
+## Impact
+
+- Affects only the terminal launcher render/reducer and focused tests.
+- Does not create new terminal-pane runtime behavior; terminal and pane-management actions point users to the existing `gx cockpit` surface.

openspec/changes/agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02/specs/agents-interactive-launcher/spec.md

@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: Launcher Home Pane Management Guidance
+The interactive `gx` launcher home SHALL present a bounded pane-management shortcut map that mirrors the existing `gx cockpit`/dmux actions while preserving the agent selection workflow.
+
+#### Scenario: Empty launcher home
+- **WHEN** `gx agents start --panel --dry-run` is rendered without a task
+- **THEN** the panel shows task-entry guidance
+- **AND** the panel shows pane-management shortcuts including terminal, files, and `Alt+Shift+M` pane menu guidance
+- **AND** no branch or worktree plan is emitted before a task exists.
+
+#### Scenario: Shortcut help while entering a task
+- **WHEN** the launcher is in task-entry mode
+- **AND** the user presses `?`
+- **THEN** the task text remains unchanged
+- **AND** the launcher reports that the shortcut map is visible on the right.
+
+#### Scenario: Cockpit-only pane actions
+- **WHEN** the launcher is in agent-selection mode
+- **AND** the user presses a cockpit-only pane action such as `t` or `Alt+Shift+M`
+- **THEN** the launcher keeps the current selection state
+- **AND** reports guidance that the action is available from `gx cockpit`.

openspec/changes/agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02/tasks.md

@@ -0,0 +1,38 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02`; branch=`agent/codex/improve-gx-launcher-pane-management-ux-2026-04-30-12-02`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02` on branch `agent/codex/improve-gx-launcher-pane-management-ux-2026-04-30-12-02`. Work inside the existing sandbox, review `openspec/changes/agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/improve-gx-launcher-pane-management-ux-2026-04-30-12-02 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02`.
+- [x] 1.2 Define normative requirements in `specs/agents-interactive-launcher/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Implement scoped behavior changes.
+- [x] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+  - Evidence: `node --test test/agents-selection-panel.test.js test/agents-start-dry-run.test.js` passed (`12/12`).
+  - Evidence: `git diff --check` passed.
+- [x] 3.2 Run `openspec validate agent-codex-improve-gx-launcher-pane-management-ux-2026-04-30-12-02 --type change --strict`.
+  - Evidence: change is valid.
+- [x] 3.3 Run `openspec validate --specs`.
+  - Evidence: command completed with `No items found to validate.`
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/improve-gx-launcher-pane-management-ux-2026-04-30-12-02 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).

src/agents/selection-panel.js

@@ -9,6 +9,41 @@ const DEFAULT_MAX_SELECTED_AGENTS = 10;
 const DEFAULT_PANEL_WIDTH = 118;
 const DEFAULT_PANEL_HEIGHT = 30;
 const SIDEBAR_WIDTH = 36;
+const PANEL_ACTIONS = [
+  ['n', 'New agent', 'create an agent pane in this repo'],
+  ['t', 'Terminal', 'open a shell pane from gx cockpit'],
+  ['p', 'Project', 'create pane in another project'],
+  ['Alt+Shift+M', 'Pane menu', 'act on the focused tmux pane'],
+  ['j/k', 'Jump', 'move between panes in the list'],
+  ['m', 'Menu', 'open pane context actions'],
+  ['x', 'Close', 'close selected pane'],
+  ['b', 'Child worktree', 'branch from selected pane'],
+  ['f', 'Files', 'browse selected worktree read-only'],
+  ['h/H', 'Hide panes', 'hide one or isolate selected pane'],
+  ['P', 'Project focus', 'show only one project'],
+  ['a/A', 'Add to pane', 'agent or terminal in worktree'],
+  ['r', 'Reopen', 'restore a closed worktree'],
+];
+
+const PANEL_SHORTCUT_MESSAGES = {
+  '?': 'Shortcut map is shown on the right.',
+  t: 'Terminal panes are managed in gx cockpit; open cockpit, then press t.',
+  p: 'Project panes are managed in gx cockpit; open cockpit, then press p.',
+  m: 'Pane menu is available in gx cockpit with m or Alt+Shift+M.',
+  'alt-shift-m': 'Pane menu is available in gx cockpit for the focused tmux pane.',
+  x: 'Close is available from gx cockpit pane menu.',
+  b: 'Child worktrees are available from gx cockpit pane menu.',
+  f: 'File browser is available from gx cockpit pane menu.',
+  h: 'Hide/show panes from gx cockpit pane menu.',
+  H: 'Hide/show panes from gx cockpit pane menu.',
+  P: 'Project focus is available from gx cockpit pane menu.',
+  a: 'Add agent to worktree from gx cockpit pane menu.',
+  A: 'Add terminal to worktree from gx cockpit pane menu.',
+  r: 'Reopen closed worktrees from gx cockpit pane menu.',
+  s: 'Settings are available from gx cockpit.',
+  l: 'Logs are available from gx cockpit.',
+  L: 'Layout reset is available from gx cockpit.',
+};
 
 const ANSI = {
   reset: '\x1b[0m',
@@ -157,12 +192,14 @@ function normalizePanelKey(value) {
   const raw = rawPanelKey(value);
   if (raw === '\u0003') return 'ctrl-c';
   if (raw === '\u0015') return 'ctrl-u';
+  if (raw === '\u001bM') return 'alt-shift-m';
   if (raw === '\u001b') return 'escape';
   if (raw === '\r' || raw === '\n') return 'enter';
   if (raw === '\u007f' || raw === '\b') return 'backspace';
   if (raw === '\u001b[A') return 'up';
   if (raw === '\u001b[B') return 'down';
-  return raw.toLowerCase();
+  if (raw.length === 1 && raw !== raw.toUpperCase()) return raw.toLowerCase();
+  return raw;
 }
 
 function printableTaskInput(value) {
@@ -214,6 +251,15 @@ function applyAgentSelectionKey(state = {}, rawKey) {
   }
 
   if (current.taskInputActive) {
+    if (key === '?') {
+      return {
+        state: {
+          ...current,
+          message: PANEL_SHORTCUT_MESSAGES['?'],
+        },
+        action: 'render',
+      };
+    }
     if (key === 'enter') {
       return taskLaunchState(current);
     }
@@ -249,6 +295,9 @@ function applyAgentSelectionKey(state = {}, rawKey) {
   if (key === 'enter' || key === 'n') {
     return taskLaunchState(current);
   }
+  if (PANEL_SHORTCUT_MESSAGES[key]) {
+    return { state: { ...current, message: PANEL_SHORTCUT_MESSAGES[key] }, action: 'render' };
+  }
   if (key === 'up' || key === 'k') {
     return {
       state: {
@@ -297,13 +346,6 @@ function padLine(value, width) {
   return `${text}${' '.repeat(width - text.length)}`;
 }
 
-function centerLine(value, width) {
-  const text = String(value || '');
-  if (text.length >= width) return text.slice(0, width);
-  const left = Math.floor((width - text.length) / 2);
-  return `${' '.repeat(left)}${text}${' '.repeat(width - text.length - left)}`;
-}
-
 function colorize(value, color, options = {}) {
   if (!options.color) return value;
   const code = ANSI[color];
@@ -335,27 +377,6 @@ function framePanel(title, rows, width = 92) {
   ].join('\n');
 }
 
-function matrixChar(row, column, seed) {
-  const value = (row * 17 + column * 31 + seed * 13 + row * column) % 41;
-  if (value === 0 || value === 7) return '1';
-  if (value === 3 || value === 11) return '0';
-  return '.';
-}
-
-function renderMatrixLine(width, row, seed) {
-  let line = '';
-  for (let column = 0; column < width; column += 1) {
-    line += matrixChar(row, column, seed);
-  }
-  return line;
-}
-
-function overlay(line, segment, column) {
-  const start = Math.max(0, Math.min(column, line.length));
-  const text = String(segment || '').slice(0, Math.max(0, line.length - start));
-  return `${line.slice(0, start)}${text}${line.slice(start + text.length)}`;
-}
-
 function renderSidebarRows(options, selections, definitions, width, height) {
   const total = selectedAgentCount(selections);
   const maxSelected = options.maxSelected || DEFAULT_MAX_SELECTED_AGENTS;
@@ -368,7 +389,9 @@ function renderSidebarRows(options, selections, definitions, width, height) {
   const rows = [
     `─ gx ${'─'.repeat(Math.max(0, width - 5))}`,
     `▦ gitguardex ${topBars}`.slice(0, width),
-    '  [n]ew agent  [t]erminal',
+    options.taskInputActive
+      ? '  Type task  [?]help  Esc cancel'
+      : '  [n] launch  [t] terminal  [?] help',
     '',
     '  Select Agent(s)',
     `  Selected: ${total}/${maxSelected}`,
@@ -388,7 +411,7 @@ function renderSidebarRows(options, selections, definitions, width, height) {
     `  claims: ${claims}`,
     options.message
       ? `  status: ${options.message}`
-      : (options.taskInputActive ? '  status: Type task, then Enter.' : ''),
+      : (options.taskInputActive ? '  status: Type task, then Enter.' : '  status: Enter launches selected agent.'),
   ];
 
   while (rows.length < height - 5) {
@@ -397,70 +420,55 @@ function renderSidebarRows(options, selections, definitions, width, height) {
 
   rows.push(
     '─'.repeat(width),
-    '  [l]ogs  •  [p]rojects',
+    '  [l]ogs [p]rojects [s]ettings',
     '  Press [?] for keyboard shortcuts',
-    '  Tip: Hidden panes keep running.',
+    '  Tip: live panes: gx cockpit',
     '',
   );
 
   return rows.slice(0, height).map((row) => padLine(row, width));
 }
 
-function renderLogoCardRows(options, selections, width) {
+function boundedText(value, width) {
+  const text = String(value || '');
+  if (text.length <= width) return text;
+  if (width <= 3) return text.slice(0, width);
+  return `${text.slice(0, width - 3)}...`;
+}
+
+function renderPaneManagementRows(options, selections, width, height) {
   const total = selectedAgentCount(selections);
   const maxSelected = options.maxSelected || DEFAULT_MAX_SELECTED_AGENTS;
-  const innerWidth = Math.max(46, width - 2);
-  const logoRows = [
-    ' ██████╗ ██╗  ██╗',
-    '██╔════╝ ╚██╗██╔╝',
-    '██║  ███╗ ╚███╔╝ ',
-    '██║   ██║ ██╔██╗ ',
-    '╚██████╔╝██╔╝ ██╗',
-    ' ╚═════╝ ╚═╝  ╚═╝',
-  ];
-  const body = [
-    ...logoRows.map((line) => centerLine(line, innerWidth)),
-    centerLine('gitguardex', innerWidth),
-    centerLine('AI developer agent guardrail multiplexer', innerWidth),
-    centerLine(`Select Agent(s) · Selected: ${total}/${maxSelected}`, innerWidth),
-    centerLine(options.taskInputActive
-      ? 'Type task, then press Enter'
-      : 'Press [n] or Enter to create a new agent', innerWidth),
+  const task = String(options.task || '').trim();
+  const bodyWidth = Math.max(24, width - 2);
+  const actionWidth = Math.min(17, Math.max(12, Math.floor(bodyWidth * 0.24)));
+  const labelWidth = Math.min(18, Math.max(12, Math.floor(bodyWidth * 0.25)));
+  const detailWidth = Math.max(12, bodyWidth - actionWidth - labelWidth - 4);
+  const rows = [
+    `─ Welcome / Pane Management ${'─'.repeat(Math.max(0, bodyWidth - 27))}`,
+    `Selected ${total}/${maxSelected} · ${task ? `task ${boundedText(task, Math.max(8, bodyWidth - 22))}` : 'type a task to start'}`,
+    '',
+    `${padLine('Key', actionWidth)}  ${padLine('Action', labelWidth)}  Detail`,
+    `${'─'.repeat(actionWidth)}  ${'─'.repeat(labelWidth)}  ${'─'.repeat(detailWidth)}`,
+    ...PANEL_ACTIONS.map(([key, label, detail]) => (
+      `${padLine(key, actionWidth)}  ${padLine(label, labelWidth)}  ${boundedText(detail, detailWidth)}`
+    )),
+    '',
+    'Navigation',
+    '↑/↓ or j/k move agent focus · Space toggles selected agent',
+    '+/- adjusts Codex account count · Enter launches new agent',
+    '',
+    'Text input',
+    'Type task text directly · Backspace edits · Ctrl+U clears',
+    '? keeps this shortcut map visible · Esc cancels',
   ];
 
-  return [
-    `┌${'─'.repeat(innerWidth)}┐`,
-    ...body.map((row) => `│${row}│`),
-    `└${'─'.repeat(innerWidth)}┘`,
-  ];
+  while (rows.length < height) rows.push('');
+  return rows.slice(0, height).map((row) => padLine(row, width));
 }
 
 function renderMainRows(options, selections, width, height) {
-  const seed = String(options.task || 'gitguardex')
-    .split('')
-    .reduce((sum, char) => sum + char.charCodeAt(0), 0);
-  const title = ' Welcome ';
-  const rows = [
-    `─${title}${'─'.repeat(Math.max(0, width - title.length - 1))}`,
-  ];
-
-  for (let row = 1; row < height - 1; row += 1) {
-    rows.push(renderMatrixLine(width, row, seed));
-  }
-  rows.push('─'.repeat(width));
-
-  const cardWidth = Math.min(Math.max(56, Math.floor(width * 0.45)), width - 6);
-  const cardRows = renderLogoCardRows(options, selections, cardWidth);
-  const top = Math.max(2, Math.floor((height - cardRows.length) / 2));
-  const left = Math.max(2, Math.floor((width - cardWidth) / 2));
-  cardRows.forEach((cardRow, offset) => {
-    const target = top + offset;
-    if (target >= 0 && target < rows.length) {
-      rows[target] = overlay(rows[target], cardRow, left);
-    }
-  });
-
-  return rows.map((row) => padLine(row, width));
+  return renderPaneManagementRows(options, selections, width, height);
 }
 
 function renderDmuxAgentSelectionPanel(options = {}) {

test/agents-selection-panel.test.js

@@ -45,8 +45,12 @@ test('renderAgentSelectionPanel shows a dmux-style GitGuardex shell', () => {
 
   assert.match(output, /Select Agent\(s\)/);
   assert.match(output, /Welcome/);
+  assert.match(output, /Pane Management/);
   assert.match(output, /gitguardex/);
-  assert.match(output, /\[n\]ew agent/);
+  assert.match(output, /\[n\] launch/);
+  assert.match(output, /\[t\] terminal/);
+  assert.match(output, /Alt\+Shift\+M/);
+  assert.match(output, /Files/);
   assert.match(output, /Selected: 3\/10/);
   assert.match(output, /● Codex cx x3/);
   assert.match(output, /Codex accounts: 3/);
@@ -71,9 +75,15 @@ test('empty interactive panel captures a task before launch', () => {
   });
 
   assert.equal(state.taskInputActive, true);
-  assert.match(renderInteractiveAgentSelectionPanel(state), /Type task, then press Enter/);
+  assert.match(renderInteractiveAgentSelectionPanel(state), /type a task to start/);
+  assert.match(renderInteractiveAgentSelectionPanel(state), /Type task text directly/);
   assert.match(renderInteractiveAgentSelectionPanel(state), /task: _/);
 
+  let help = applyAgentSelectionKey(state, '?');
+  assert.equal(help.action, 'render');
+  assert.equal(help.state.task, '');
+  assert.match(help.state.message, /Shortcut map is shown on the right/);
+
   let next = applyAgentSelectionKey(state, 'n');
   assert.equal(next.action, 'render');
   assert.equal(next.state.task, 'n');
@@ -112,6 +122,12 @@ test('interactive panel keys move focus, toggle agents, and adjust codex account
 
   state = applyAgentSelectionKey(state, '-').state;
   assert.equal(countForAgent(selectionsFromPanelState(state), 'codex'), 2);
+  const terminalHelp = applyAgentSelectionKey(state, 't');
+  assert.equal(terminalHelp.action, 'render');
+  assert.match(terminalHelp.state.message, /Terminal panes are managed in gx cockpit/);
+  const paneMenuHelp = applyAgentSelectionKey(state, '\u001bM');
+  assert.equal(paneMenuHelp.action, 'render');
+  assert.match(paneMenuHelp.state.message, /Pane menu is available in gx cockpit/);
   assert.equal(applyAgentSelectionKey(state, 'n').action, 'launch');
   assert.equal(applyAgentSelectionKey(state, '\r').action, 'launch');
   assert.equal(applyAgentSelectionKey(state, '\u001b').action, 'cancel');