Route pane menu actions through a guarded dispatcher (#507)

* Provide a pure cockpit pane menu contract

The cockpit needs the dmux-style pane menu model before any terminal/backend execution is wired. This keeps the menu state, rendering, key handling, and compatibility export reusable and deterministic while leaving backend actions as selected action ids only.

Constraint: User requested no backend execution in this task

Rejected: Include pane action dispatcher changes | separate sibling work is dirty in the same worktree and exceeds the pure menu model scope

Confidence: high

Scope-risk: moderate

Directive: Do not wire these action ids to pane/worktree mutation without a separate backend execution task and focused safety coverage

Tested: node --test test/cockpit-pane-menu.test.js test/cockpit-menu.test.js test/cockpit-control.test.js test/cockpit-keybindings.test.js

Tested: node --test test/cockpit-pane-menu.test.js test/cockpit-menu.test.js test/cockpit-control.test.js test/cockpit-keybindings.test.js test/tmux-session.test.js test/agents-start-dry-run.test.js

Tested: openspec validate agent-codex-dmux-pane-context-menu-2026-04-30-13-54 --type change --strict

Not-tested: npm test is red in existing broad suites: 441/454 passing, 12 failing, 1 skipped

* Route pane menu actions through a guarded dispatcher

Pane menu actions needed one owner surface before wiring more terminal/backend behavior. The dispatcher keeps backend operations explicit, routes merge through gx agents finish, and leaves unsupported items visible as structured status results instead of raw errors.

Constraint: Pane menu actions must not bypass Guardex PR/worktree safety.

Rejected: Keep expanding action-runner.js inline | it hid backend and safety boundaries in one large switch.

Confidence: high

Scope-risk: moderate

Directive: Do not route create-pr or merge through direct git commands; keep PR/finish flows guarded.

Tested: npm test (485 pass, 1 skip, 0 fail); node --test dispatcher/kitty focused 28/28; openspec validate agent-codex-dmux-pane-context-menu-2026-04-30-13-54 --type change --strict; git diff --check

Not-tested: Real terminal backend hide/isolate implementations; no live interactive tmux/Kitty UI session exercised.

---------

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

Author: NagyVikt

openspec/changes/agent-codex-dmux-pane-context-menu-2026-04-30-13-54/proposal.md

@@ -0,0 +1,19 @@
+# dmux pane context menu
+
+## Problem
+
+The GitGuardEx launcher advertises dmux/cockpit pane actions, but the reusable cockpit menu model still exposes older lane actions and does not provide the dmux-style pane menu surface requested by the launcher guidance.
+
+## Scope
+
+- Add a reusable terminal-only pane menu model and renderer.
+- Export stable pane menu action ids for cockpit and future backend wiring.
+- Represent merge and PR as pure action ids only; do not execute backend operations in this task.
+- Add focused `node:test` coverage for rendering, navigation, hotkeys, selection, and cancel behavior.
+
+## Out of scope
+
+- No new dependencies.
+- No backend execution or new action dispatcher.
+- No bypass of Guardex branch/worktree/lock/PR safety.
+- No direct base-branch merge path.

openspec/changes/agent-codex-dmux-pane-context-menu-2026-04-30-13-54/specs/cockpit-pane-menu/spec.md

@@ -0,0 +1,26 @@
+## ADDED Requirements
+
+### Requirement: Cockpit exposes a reusable dmux-style pane menu
+
+GitGuardEx SHALL provide a terminal-only reusable pane menu model and renderer that mirrors the dmux pane action list while preserving Guardex safety boundaries.
+
+#### Scenario: menu renders selected pane actions
+
+- **GIVEN** a selected cockpit pane/session/worktree
+- **WHEN** the pane menu is rendered
+- **THEN** the title is `Menu: <selected pane/session/worktree name>`
+- **AND** the menu shows View, Hide Pane, Close, Merge, Create GitHub PR, Rename, Copy Path, Open in Editor, Toggle Autopilot, Create Child Worktree, Browse Files, Add Terminal to Worktree, and Add Agent to Worktree
+- **AND** the footer says `↑↓ to navigate • Enter or hotkey to select • ESC to cancel`
+
+#### Scenario: menu key handling is deterministic
+
+- **GIVEN** an open pane menu
+- **WHEN** the user presses up/down, j/k navigation, Enter, a direct action hotkey, Escape, or Ctrl-C
+- **THEN** pure menu state updates identify navigation, selected action id, or cancellation without terminal side effects
+
+#### Scenario: actions stay pure until a backend task wires execution
+
+- **GIVEN** a menu action requires branch or worktree context
+- **WHEN** the pane menu model is rendered or keyed
+- **THEN** it only reports enabled state, disabled reasons, cancellation, or selected action id
+- **AND** it does not merge, create PRs, close panes, launch terminals, or mutate worktrees

openspec/changes/agent-codex-dmux-pane-context-menu-2026-04-30-13-54/tasks.md

@@ -0,0 +1,35 @@
+# dmux pane context menu tasks
+
+## 1. Spec
+
+- [x] 1.1 Define the dmux-style pane menu behavior and safety boundaries.
+
+## 2. Tests
+
+- [x] 2.1 Cover menu rendering, item order, hotkeys, navigation, selection, cancel, disabled status, and compatibility exports.
+  - Evidence: `node --test test/cockpit-kitty-integration.test.js test/cockpit-control.test.js test/cockpit-keybindings.test.js test/cockpit-pane-menu.test.js test/cockpit-pane-actions.test.js test/cockpit-action-runner.test.js test/agents-selection-panel.test.js test/agents-start-dry-run.test.js` passed (`58/58`).
+- [x] 2.2 Cover cockpit shortcut wiring for `m` and `Alt+Shift+M`.
+  - Evidence: same focused command passed (`58/58`).
+- [x] 2.3 Run existing focused cockpit/tmux/launcher tests.
+  - Evidence: same focused command passed (`58/58`).
+- [x] 2.4 Cover the safe pane action dispatcher, backend calls, unsupported status results, direct-git merge avoidance, and tmux fallback behavior.
+  - Evidence: included in the focused command (`58/58`), plus full `npm test` passed (`485/486` passing, `1` skipped, `0` failing).
+
+## 3. Implementation
+
+- [x] 3.1 Add reusable pane menu model/rendering module.
+- [x] 3.2 Keep `src/cockpit/menu.js` as a compatibility export.
+- [x] 3.3 Wire cockpit control/action mapping to the pane menu without bypassing Guardex safety.
+- [x] 3.4 Add `src/cockpit/pane-actions.js` as the single dispatcher for pane menu action ids, terminal backend operations, and Guardex-safe status fallbacks.
+
+## 4. Verification
+
+- [x] 4.1 Run `openspec validate agent-codex-dmux-pane-context-menu-2026-04-30-13-54 --type change --strict`.
+  - Evidence: passed.
+- [x] 4.2 Run `npm test`.
+  - Evidence: passed (`485/486` passing, `1` skipped, `0` failing).
+
+## 5. Cleanup
+
+- [ ] 5.1 Commit, push, open PR, merge, and cleanup with `gx branch finish --branch agent/codex/dmux-pane-context-menu-2026-04-30-13-54 --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

@@ -20,7 +20,7 @@ const PANEL_ACTIONS = [
   ['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'],
+  ['P', 'Project focus', 'show only the selected project'],
   ['a/A', 'Add to pane', 'agent or terminal in worktree'],
   ['r', 'Reopen', 'restore a closed worktree'],
 ];
@@ -189,6 +189,12 @@ function rawPanelKey(value) {
 }
 
 function normalizePanelKey(value) {
+  if (value && typeof value === 'object' && !Buffer.isBuffer(value)) {
+    if ((value.meta || value.alt) && value.shift && String(value.name || value.key || '').toLowerCase() === 'm') {
+      return 'alt-shift-m';
+    }
+    return normalizePanelKey(value.name || value.sequence || value.key || '');
+  }
   const raw = rawPanelKey(value);
   if (raw === '\u0003') return 'ctrl-c';
   if (raw === '\u0015') return 'ctrl-u';