Make launcher panel real TTY before spawning agents (#489)

The static panel already communicated selection intent, but --panel still fell through to scripted dry-run output. Route TTY invocations through a raw-mode controller so keyboard selection happens in the terminal before dry-run or launch execution.

Constraint: Non-TTY and JSON flows must keep existing deterministic output.

Rejected: Replacing static renderer | tests and scripted users depend on stable text output.

Confidence: high

Scope-risk: moderate

Directive: Keep interactive key handling in pure reducer helpers so CLI behavior remains testable without a TTY.

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

Tested: openspec validate agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55 --type change --strict

Tested: git diff --check

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

Author: NagyVikt

openspec/changes/agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55/.openspec.yaml

@@ -0,0 +1,2 @@
+tier: T2
+change: agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55

openspec/changes/agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55/proposal.md

@@ -0,0 +1,16 @@
+# Interactive dmux launcher panel
+
+## Why
+
+`gx agents start --panel` currently prints a static panel and then immediately prints launch plans. The panel advertises keyboard controls, but operators cannot actually use arrows, Space, plus/minus, Enter, or ESC in the terminal the way dmux-style launchers do.
+
+## What Changes
+
+- Make `gx agents start <task> --panel` open an interactive terminal panel when stdin/stdout are TTYs.
+- Keep non-TTY and scripted behavior unchanged.
+- Let Enter either print dry-run plans or create lanes depending on `--dry-run`.
+- Keep ESC/Ctrl-C as cancel without creating work.
+
+## Impact
+
+The CLI start path and panel renderer gain interactive behavior. Existing dry-run output remains available for scripts and tests.

openspec/changes/agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55/specs/agents-interactive-launcher/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Panel launches interactively on TTY
+
+`gx agents start <task> --panel` SHALL open an interactive terminal launcher when stdin and stdout are TTYs.
+
+#### Scenario: operator changes Codex account count before dry-run launch
+
+- **WHEN** an operator runs `gx agents start "fix auth tests" --panel --codex-accounts 1 --dry-run` in a TTY
+- **AND** presses `+`
+- **AND** presses Enter
+- **THEN** the command SHALL print dry-run plans for two Codex lanes
+- **AND** it SHALL NOT create branches, worktrees, session metadata, or agent processes.
+
+#### Scenario: scripted panel output stays static
+
+- **WHEN** `gx agents start "fix auth tests" --panel --codex-accounts 3 --dry-run` runs without a TTY
+- **THEN** the command SHALL keep printing the static panel and dry-run plans as before.
+
+#### Scenario: operator cancels interactive panel
+
+- **WHEN** an operator presses ESC or Ctrl-C in the interactive panel
+- **THEN** the command SHALL exit with cancellation status
+- **AND** it SHALL NOT create branches, worktrees, session metadata, or agent processes.

openspec/changes/agent-codex-interactive-dmux-launcher-panel-2026-04-30-10-55/tasks.md

@@ -0,0 +1,26 @@
+# Tasks
+
+## 1. Spec
+
+- [x] 1.1 Capture interactive terminal-panel behavior.
+
+## 2. Tests
+
+- [x] 2.1 Cover panel key handling.
+- [x] 2.2 Cover interactive dry-run launch output.
+
+## 3. Implementation
+
+- [x] 3.1 Add panel state and key reducer.
+- [x] 3.2 Route TTY `gx agents start --panel` through the interactive controller.
+- [x] 3.3 Preserve non-TTY/static dry-run output.
+
+## 4. Verification
+
+- [x] 4.1 Run focused Node tests.
+- [x] 4.2 Validate OpenSpec.
+
+## 5. Cleanup
+
+- [ ] 5.1 Commit, push, PR, merge, and cleanup the agent worktree.
+- [ ] 5.2 Record merged PR URL and final cleanup evidence.

src/agents/selection-panel.js

@@ -72,6 +72,139 @@ function countForAgent(selections, agentId) {
   return selection ? selection.count : 0;
 }
 
+function countsFromSelections(selections) {
+  const counts = {};
+  for (const selection of selections) {
+    counts[selection.agent.id] = selection.count;
+  }
+  return counts;
+}
+
+function clampIndex(index, length) {
+  if (length <= 0) return 0;
+  if (!Number.isInteger(index)) return 0;
+  return Math.max(0, Math.min(index, length - 1));
+}
+
+function createAgentSelectionPanelState(options = {}) {
+  const definitions = getAgentDefinitions();
+  const maxSelected = options.maxSelected || DEFAULT_MAX_SELECTED_AGENTS;
+  const selections = normalizeAgentSelections({ ...options, maxSelected });
+  const counts = countsFromSelections(selections);
+  const firstSelectedIndex = definitions.findIndex((agent) => (counts[agent.id] || 0) > 0);
+  return {
+    task: options.task || '',
+    base: options.base || '',
+    claims: Array.isArray(options.claims) ? [...options.claims] : [],
+    maxSelected,
+    focusIndex: firstSelectedIndex >= 0 ? firstSelectedIndex : 0,
+    counts,
+    message: '',
+  };
+}
+
+function selectionsFromPanelState(state = {}) {
+  const counts = state.counts || {};
+  return getAgentDefinitions()
+    .map((agent) => ({
+      agent,
+      count: Number.isInteger(counts[agent.id]) ? counts[agent.id] : 0,
+    }))
+    .filter((selection) => selection.count > 0);
+}
+
+function selectedCountFromPanelState(state = {}) {
+  return selectedAgentCount(selectionsFromPanelState(state));
+}
+
+function focusedAgent(state = {}) {
+  const definitions = getAgentDefinitions();
+  return definitions[clampIndex(state.focusIndex, definitions.length)] || definitions[0];
+}
+
+function withCount(state, agentId, count, message = '') {
+  return {
+    ...state,
+    counts: {
+      ...(state.counts || {}),
+      [agentId]: Math.max(0, count),
+    },
+    message,
+  };
+}
+
+function normalizePanelKey(value) {
+  if (!value) return '';
+  const raw = Buffer.isBuffer(value) ? value.toString('utf8') : String(value);
+  if (raw === '\u0003') return 'ctrl-c';
+  if (raw === '\u001b') return 'escape';
+  if (raw === '\r' || raw === '\n') return 'enter';
+  if (raw === '\u001b[A') return 'up';
+  if (raw === '\u001b[B') return 'down';
+  return raw.toLowerCase();
+}
+
+function applyAgentSelectionKey(state = {}, rawKey) {
+  const definitions = getAgentDefinitions();
+  const current = {
+    ...state,
+    focusIndex: clampIndex(state.focusIndex, definitions.length),
+    counts: { ...(state.counts || {}) },
+    message: '',
+  };
+  const key = normalizePanelKey(rawKey);
+
+  if (key === 'ctrl-c' || key === 'escape' || key === 'q') {
+    return { state: current, action: 'cancel' };
+  }
+  if (key === 'enter') {
+    if (selectedCountFromPanelState(current) <= 0) {
+      return { state: { ...current, message: 'Select at least one agent before launch.' }, action: 'render' };
+    }
+    return { state: current, action: 'launch' };
+  }
+  if (key === 'up' || key === 'k') {
+    return {
+      state: {
+        ...current,
+        focusIndex: (current.focusIndex - 1 + definitions.length) % definitions.length,
+      },
+      action: 'render',
+    };
+  }
+  if (key === 'down' || key === 'j') {
+    return {
+      state: {
+        ...current,
+        focusIndex: (current.focusIndex + 1) % definitions.length,
+      },
+      action: 'render',
+    };
+  }
+
+  const codexCount = current.counts.codex || 0;
+  const selectedCount = selectedCountFromPanelState(current);
+  if (key === '+') {
+    if (selectedCount >= current.maxSelected) {
+      return { state: { ...current, message: `Selected agent count cannot exceed ${current.maxSelected}.` }, action: 'render' };
+    }
+    return { state: withCount(current, 'codex', codexCount + 1), action: 'render' };
+  }
+  if (key === '-') {
+    return { state: withCount(current, 'codex', Math.max(0, codexCount - 1)), action: 'render' };
+  }
+  if (key === ' ' || key === 'space') {
+    const agent = focusedAgent(current);
+    const nextCount = current.counts[agent.id] > 0 ? 0 : 1;
+    if (nextCount > 0 && selectedCount >= current.maxSelected) {
+      return { state: { ...current, message: `Selected agent count cannot exceed ${current.maxSelected}.` }, action: 'render' };
+    }
+    return { state: withCount(current, agent.id, nextCount), action: 'render' };
+  }
+
+  return { state: current, action: 'render' };
+}
+
 function padLine(value, width) {
   const text = String(value || '');
   if (text.length >= width) return text.slice(0, width);
@@ -107,26 +240,44 @@ function renderAgentSelectionPanel(options = {}) {
       const count = countForAgent(selections, agent.id);
       const marker = count > 0 ? '●' : '○';
       const suffix = count > 1 ? ` x${count}` : '';
-      return `${marker} ${agent.label} ${agent.shortLabel.toLowerCase()}${suffix}`;
+      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}` : null,
     '',
     '↑/↓ navigate · Space toggle · +/- Codex accounts · Enter launch · ESC cancel',
-  ];
+  ].filter((row) => row !== null);
   return `${framePanel('Select Agent(s)', rows)}\n`;
 }
 
+function renderInteractiveAgentSelectionPanel(state = {}) {
+  return renderAgentSelectionPanel({
+    task: state.task,
+    base: state.base,
+    claims: state.claims,
+    maxSelected: state.maxSelected,
+    selections: selectionsFromPanelState(state),
+    focusedAgentId: focusedAgent(state)?.id,
+    message: state.message,
+  });
+}
+
 module.exports = {
+  applyAgentSelectionKey,
+  createAgentSelectionPanelState,
   DEFAULT_MAX_SELECTED_AGENTS,
   countForAgent,
   framePanel,
   normalizeAgentSelections,
   parseAgentSelectionSpec,
+  renderInteractiveAgentSelectionPanel,
   renderAgentSelectionPanel,
+  selectionsFromPanelState,
   selectedAgentCount,
 };