Make the agent launcher feel like a terminal cockpit (#491)

The existing panel was functionally interactive but still looked like a compact form. This change gives gx agents start --panel the dmux-style shell the operator expects: blue GitGuardex rail, matrix field, centered welcome card, and keyboard-first new-agent affordance.

Constraint: Preserve existing branch planning, dry-run output, and session behavior.

Rejected: Replace gx default status with the launcher | too broad for this panel-focused request.

Confidence: high

Scope-risk: narrow

Directive: Keep branch/worktree/session logic out of the renderer; this surface is presentation and key handling only.

Tested: node --test test/agents-selection-panel.test.js test/agents-start-dry-run.test.js test/agents-start.test.js test/cli-args-dispatch.test.js test/agents-start-claims.test.js

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

Tested: openspec validate agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18 --type change --strict

Tested: node bin/multiagent-safety.js agents --target /home/deadpool/Documents/recodee/gitguardex start 'fix auth tests' --panel --codex-accounts 3 --base main --dry-run

Not-tested: Real interactive terminal screenshot capture; verified through TTY-render unit coverage and dry-run smoke output.

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

Author: NagyVikt

openspec/changes/agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18/.openspec.yaml

@@ -0,0 +1,2 @@
+tier: T2
+change: agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18

openspec/changes/agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18/proposal.md

@@ -0,0 +1,16 @@
+# Blue dmux gx agent launcher
+
+## Why
+
+`gx agents start --panel` already supports interactive selection, but its visual shell is still a compact form. Operators expect the launcher to open like dmux: a full terminal surface with a left project rail, a matrix-style main field, a centered brand card, and keyboard-first create flow.
+
+## What Changes
+
+- Render the agent start panel as a dmux-style full-terminal GitGuardex shell.
+- Use a blue/cyan terminal palette for the TTY surface.
+- Preserve existing dry-run, multi-account planning, and keyboard selection behavior.
+- Add `[n]` as a launch alias so the welcome prompt matches the dmux-style "new agent" affordance.
+
+## Impact
+
+The change is isolated to the `gx agents start --panel` renderer/controller and focused tests. It does not alter branch creation, lock claims, sessions, finish flow, or non-panel agent startup.

openspec/changes/agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18/specs/agents-interactive-launcher/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Panel uses blue dmux-style terminal shell
+
+`gx agents start <task> --panel` SHALL render a full-terminal GitGuardex launcher shell with a blue/cyan visual style, a left project rail, a matrix-style main field, and a centered GitGuardex welcome card.
+
+#### Scenario: scripted panel output includes dmux shell
+
+- **WHEN** `gx agents start "fix auth tests" --panel --codex-accounts 3 --dry-run` runs without a TTY
+- **THEN** the output SHALL include a left `gitguardex` rail
+- **AND** the output SHALL include a `Welcome` main field
+- **AND** the output SHALL include `Press [n] or Enter to create a new agent`
+- **AND** the command SHALL keep printing dry-run plans as before.
+
+#### Scenario: TTY panel uses blue ANSI styling
+
+- **WHEN** an operator runs `gx agents start "fix auth tests" --panel --codex-accounts 1 --dry-run` in a TTY
+- **THEN** the interactive panel SHALL render with blue/cyan ANSI styling
+- **AND** it SHALL preserve keyboard controls for navigation, toggling, Codex account count, launch, and cancel.
+
+#### Scenario: operator launches with new-agent shortcut
+
+- **WHEN** an operator presses `n` in the interactive panel
+- **THEN** the command SHALL launch the selected agent plan the same way Enter does.

openspec/changes/agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18/tasks.md

@@ -0,0 +1,31 @@
+# Tasks
+
+## 1. Spec
+
+- [x] 1.1 Capture dmux-style blue launcher behavior.
+
+## 2. Tests
+
+- [x] 2.1 Cover dmux shell rendering and blue ANSI output.
+- [x] 2.2 Cover `[n]` launch key alias.
+- [x] 2.3 Run focused launcher tests.
+
+## 3. Implementation
+
+- [x] 3.1 Replace compact default panel with dmux-style terminal shell.
+- [x] 3.2 Pass TTY dimensions/color into the interactive renderer.
+- [x] 3.3 Preserve compact renderer as an explicit compatibility path.
+
+## 4. Verification
+
+- [x] 4.1 Run focused Node tests.
+  - Evidence: `node --test test/agents-selection-panel.test.js test/agents-start-dry-run.test.js test/agents-start.test.js test/cli-args-dispatch.test.js test/agents-start-claims.test.js` passed (`30/30`).
+- [x] 4.2 Validate OpenSpec change.
+  - Evidence: `openspec validate agent-codex-blue-dmux-gx-agent-launcher-2026-04-30-11-18 --type change --strict` passed.
+- [x] 4.3 Smoke `gx agents start "fix auth tests" --panel --codex-accounts 3 --base main --dry-run`.
+  - Evidence: `node bin/multiagent-safety.js agents --target /home/deadpool/Documents/recodee/gitguardex start "fix auth tests" --panel --codex-accounts 3 --base main --dry-run` rendered the blue dmux-style GitGuardex shell and planned three dry-run lanes without creating branches/worktrees.
+
+## 5. Cleanup
+
+- [ ] 5.1 Run the finish pipeline: `gx branch finish --branch agent/codex/blue-dmux-gx-agent-launcher-2026-04-30-11-18 --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] 5.2 Record PR URL, final `MERGED` state, and sandbox cleanup evidence.

src/agents/selection-panel.js

@@ -6,6 +6,17 @@ const {
 } = require('./registry');
 
 const DEFAULT_MAX_SELECTED_AGENTS = 10;
+const DEFAULT_PANEL_WIDTH = 118;
+const DEFAULT_PANEL_HEIGHT = 30;
+const SIDEBAR_WIDTH = 36;
+
+const ANSI = {
+  reset: '\x1b[0m',
+  blue: '\x1b[34m',
+  brightBlue: '\x1b[94m',
+  cyan: '\x1b[36m',
+  inverse: '\x1b[7m',
+};
 
 function parsePositiveInteger(value, flagName) {
   const parsed = Number.parseInt(String(value || ''), 10);
@@ -157,7 +168,7 @@ function applyAgentSelectionKey(state = {}, rawKey) {
   if (key === 'ctrl-c' || key === 'escape' || key === 'q') {
     return { state: current, action: 'cancel' };
   }
-  if (key === 'enter') {
+  if (key === 'enter' || key === 'n') {
     if (selectedCountFromPanelState(current) <= 0) {
       return { state: { ...current, message: 'Select at least one agent before launch.' }, action: 'render' };
     }
@@ -211,6 +222,31 @@ 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];
+  return code ? `${code}${value}${ANSI.reset}` : value;
+}
+
+function panelWidth(options = {}) {
+  const width = Number(options.width);
+  if (!Number.isFinite(width)) return DEFAULT_PANEL_WIDTH;
+  return Math.max(80, Math.floor(width));
+}
+
+function panelHeight(options = {}) {
+  const height = Number(options.height);
+  if (!Number.isFinite(height)) return DEFAULT_PANEL_HEIGHT;
+  return Math.max(24, Math.floor(height) - 1);
+}
+
 function framePanel(title, rows, width = 92) {
   const safeWidth = Math.max(40, width);
   const titleText = ` ${title} `;
@@ -224,7 +260,158 @@ 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;
+  const codexAccounts = countForAgent(selections, 'codex');
+  const claims = Array.isArray(options.claims) && options.claims.length > 0
+    ? options.claims.join(', ')
+    : 'none';
+  const topBars = '█'.repeat(Math.max(0, width - 13));
+  const rows = [
+    `─ gx ${'─'.repeat(Math.max(0, width - 5))}`,
+    `▦ gitguardex ${topBars}`.slice(0, width),
+    '  [n]ew agent  [t]erminal',
+    '',
+    '  Select Agent(s)',
+    `  Selected: ${total}/${maxSelected}`,
+    '',
+    ...definitions.map((agent) => {
+      const count = countForAgent(selections, agent.id);
+      const marker = count > 0 ? '●' : '○';
+      const suffix = count > 1 ? ` x${count}` : '';
+      const focus = options.focusedAgentId === agent.id ? '› ' : '  ';
+      return `${focus}${marker} ${agent.label} ${agent.shortLabel.toLowerCase()}${suffix}`;
+    }),
+    '',
+    '  Settings',
+    `  task: ${options.task || '-'}`,
+    `  base: ${options.base || 'current branch'}`,
+    `  Codex accounts: ${codexAccounts}`,
+    `  claims: ${claims}`,
+    options.message ? `  status: ${options.message}` : '',
+  ];
+
+  while (rows.length < height - 5) {
+    rows.push('');
+  }
+
+  rows.push(
+    '─'.repeat(width),
+    '  [l]ogs  •  [p]rojects',
+    '  Press [?] for keyboard shortcuts',
+    '  Tip: Hidden panes keep running.',
+    '',
+  );
+
+  return rows.slice(0, height).map((row) => padLine(row, width));
+}
+
+function renderLogoCardRows(options, selections, width) {
+  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('Press [n] or Enter to create a new agent', innerWidth),
+  ];
+
+  return [
+    `┌${'─'.repeat(innerWidth)}┐`,
+    ...body.map((row) => `│${row}│`),
+    `└${'─'.repeat(innerWidth)}┘`,
+  ];
+}
+
+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));
+}
+
+function renderDmuxAgentSelectionPanel(options = {}) {
+  const definitions = getAgentDefinitions();
+  const maxSelected = options.maxSelected || DEFAULT_MAX_SELECTED_AGENTS;
+  const selections = options.selections || normalizeAgentSelections({ ...options, maxSelected });
+  const width = panelWidth(options);
+  const height = panelHeight(options);
+  const sidebarWidth = Math.min(SIDEBAR_WIDTH, Math.max(28, Math.floor(width * 0.38)));
+  const mainWidth = Math.max(42, width - sidebarWidth - 1);
+  const sidebar = renderSidebarRows({ ...options, maxSelected }, selections, definitions, sidebarWidth, height);
+  const main = renderMainRows({ ...options, maxSelected }, selections, mainWidth, height);
+  const keyLine = padLine(' ↑/↓ navigate · Space toggle · +/- Codex accounts · [n]/Enter launch · ESC cancel ', width);
+  const lines = [];
+
+  for (let index = 0; index < height; index += 1) {
+    const left = colorize(sidebar[index] || ''.padEnd(sidebarWidth, ' '), 'cyan', options);
+    const divider = colorize('│', 'blue', options);
+    const right = colorize(main[index] || ''.padEnd(mainWidth, ' '), 'brightBlue', options);
+    lines.push(`${left}${divider}${right}`);
+  }
+
+  lines.push(colorize(keyLine, 'inverse', options));
+  return `${lines.join('\n')}\n`;
+}
+
 function renderAgentSelectionPanel(options = {}) {
+  if (!options.compact) {
+    return renderDmuxAgentSelectionPanel(options);
+  }
+
   const definitions = getAgentDefinitions();
   const maxSelected = options.maxSelected || DEFAULT_MAX_SELECTED_AGENTS;
   const selections = options.selections || normalizeAgentSelections({ ...options, maxSelected });
@@ -251,12 +438,12 @@ function renderAgentSelectionPanel(options = {}) {
     `claims: ${claims}`,
     options.message ? `status: ${options.message}` : null,
     '',
-    '↑/↓ navigate · Space toggle · +/- Codex accounts · Enter launch · ESC cancel',
+    '↑/↓ navigate · Space toggle · +/- Codex accounts · [n]/Enter launch · ESC cancel',
   ].filter((row) => row !== null);
   return `${framePanel('Select Agent(s)', rows)}\n`;
 }
 
-function renderInteractiveAgentSelectionPanel(state = {}) {
+function renderInteractiveAgentSelectionPanel(state = {}, options = {}) {
   return renderAgentSelectionPanel({
     task: state.task,
     base: state.base,
@@ -265,6 +452,7 @@ function renderInteractiveAgentSelectionPanel(state = {}) {
     selections: selectionsFromPanelState(state),
     focusedAgentId: focusedAgent(state)?.id,
     message: state.message,
+    ...options,
   });
 }
 

src/agents/start.js

@@ -238,7 +238,11 @@ function startInteractiveAgentPanel(repoRoot, options, deps = {}) {
     if (stdout && stdout.isTTY) {
       writeStream(stdout, '\x1b[?25l\x1b[H\x1b[2J\x1b[3J');
     }
-    writeStream(stdout, renderInteractiveAgentSelectionPanel(state));
+    writeStream(stdout, renderInteractiveAgentSelectionPanel(state, {
+      color: Boolean(stdout && stdout.isTTY),
+      width: stdout && stdout.columns,
+      height: stdout && stdout.rows,
+    }));
   }
 
   function finish(result) {

test/agents-selection-panel.test.js

@@ -35,7 +35,7 @@ test('normalizeAgentSelections merges repeated agents and enforces the max', ()
   );
 });
 
-test('renderAgentSelectionPanel shows selected count and codex account setting', () => {
+test('renderAgentSelectionPanel shows a dmux-style GitGuardex shell', () => {
   const output = renderAgentSelectionPanel({
     task: 'repair auth',
     base: 'main',
@@ -44,12 +44,23 @@ test('renderAgentSelectionPanel shows selected count and codex account setting',
   });
 
   assert.match(output, /Select Agent\(s\)/);
+  assert.match(output, /Welcome/);
+  assert.match(output, /gitguardex/);
+  assert.match(output, /\[n\]ew agent/);
   assert.match(output, /Selected: 3\/10/);
   assert.match(output, /● Codex cx x3/);
   assert.match(output, /Codex accounts: 3/);
   assert.match(output, /task: repair auth/);
   assert.match(output, /base: main/);
   assert.match(output, /claims: src\/auth\.js/);
+
+  const blueOutput = renderAgentSelectionPanel({
+    task: 'repair auth',
+    agentSelectionSpecs: ['codex:1'],
+    color: true,
+  });
+  assert.match(blueOutput, /\x1b\[36m/);
+  assert.match(blueOutput, /\x1b\[94m/);
 });
 
 test('interactive panel keys move focus, toggle agents, and adjust codex accounts', () => {
@@ -73,6 +84,7 @@ test('interactive panel keys move focus, toggle agents, and adjust codex account
 
   state = applyAgentSelectionKey(state, '-').state;
   assert.equal(countForAgent(selectionsFromPanelState(state), 'codex'), 2);
+  assert.equal(applyAgentSelectionKey(state, 'n').action, 'launch');
   assert.equal(applyAgentSelectionKey(state, '\r').action, 'launch');
   assert.equal(applyAgentSelectionKey(state, '\u001b').action, 'cancel');
 });