Terminal-first workspace: sidebars, external workspace navigation and developer control surfaces #330

Goal

Organize a rich terminal-native workspace around truthful external-resource navigation, without turning NMSh into an integrated IDE.

User/product motivation

Bring sessions, projects, agents and developer workflows together while keeping the current transcript/composer central and tools independently useful.

UX / interaction model

• LEFT: navigation — where am I going?
• CENTER: current NMSh transcript/composer/work.
• RIGHT: contextual detail — what am I looking at?
• BOTTOM: NMSh Status Strip or integration-owned status.
  Addressable resources may include NMSh sessions, Managed Targets, projects, tmux sessions/windows/panes, supported editor sessions, Git worktrees and GitHub PRs/issues. Only list activatable resources when a supported, truthful navigation path exists; factual nonactivatable information must be labelled accordingly.
  Sidebar means quick navigation/status. Dedicated managers own deep control; do not grow a sidebar into /everything.
  Fullscreen/raw passthrough owns the entire pane and suppresses workspace chrome. Idle/screensaver presentation may own the whole NMSh surface; Vespyr may roam across normal boundaries and normal geometry/focus reconstructs afterward.

Regional focus contract

Depend on and extend the Managed Target input-owner foundation in #329 and semantic actions from closed #166; do not invent a competing dispatcher. Candidate owners: COMPOSER, TRANSCRIPT, LEFT_SIDEBAR, RIGHT_PANEL, SEARCH, APPROVAL, CHOICE, AGENT_MESSAGE. Exactly one owns keys. Active shell drafts win: never steal Left/Right/number keys from active composer text. Focus must be visible through edge, selection and label emphasis, including Safe glyph and NO_COLOR paths. Selection, active resource and keyboard focus are distinct state.

Dependencies

Closed #164/#165/#166/#167 notMyUI foundations; #118 single ScreenPlan; #197 startup picker (closed, reuse only); open #304 Theme Bridge, #305 shared facts, #317 routing, #321 QA; PR #328 strip and PR #329 Managed Targets. Do not reopen foundations.

Security/safety constraints

Navigation is not authority to mutate or execute. Preserve persistent shell state, detached helper isolation and frontend ownership. External owners and capabilities determine available actions. Confirm destructive and remote actions; unknown support stays unavailable.

Narrow / NO_COLOR / Safe expectations

Measured docked/compact/drawer transitions, a useful center at narrow widths, explicit non-color-only focus, draft/cursor/selection and transcript scroll-anchor preservation; unified ScreenPlan geometry for render, hit tests, cursor, viewport and PTY sizing.

Non-goals

Implementing this program in one PR, immediate /agents or /sessions replacement, host-native windows/splits, new PTYs for listed tmux objects, code editing, browser rendering, release work or changes to #328/#329.

Acceptance criteria

• Coherent child specifications linked with dependency and ownership boundaries.
• Deterministic shared regional focus and semantic actions designed before panels ship.
• Truthful resource identity/navigation and selection vs activation defined.
• Responsive geometry, passthrough and idle reconstruction validated.
• Dedicated managers and sidebar have distinct responsibilities.
• Automated tests plus separate physical Ghostty/Terminal.app and tmux QA planned per slice.

Children

• Workspace Sidebar: keyboard-first resource navigation with explicit focus and activation #331 — Workspace Sidebar: keyboard-first resource navigation with explicit focus and activation
• Contextual right panel: keyboard-first diff, detail and review presentation #332 — Contextual right panel: keyboard-first diff, detail and review presentation
• /tmux Studio: status, appearance, Context modules and workspace integration #333 — /tmux Studio: status, appearance, Context modules and workspace integration
• Setup Cat integration profiles: progressive onboarding for tmux, editors and provider agents #334 — Setup Cat integration profiles: progressive onboarding for tmux, editors and provider agents
• Configurable semantic keymap and terminal-host conflict guidance #335 — Configurable semantic keymap and terminal-host conflict guidance
• Terminal-native action controls: reusable styles, semantic states and safe fallbacks #336 — Terminal-native action controls: reusable styles, semantic states and safe fallbacks
• /worktrees: terminal-first Git worktree discovery, navigation and safe management #337 — /worktrees: terminal-first Git worktree discovery, navigation and safe management
• GitHub terminal workspace: PR and issue search, review and supported remote actions #338 — GitHub terminal workspace: PR and issue search, review and supported remote actions
• Managed Targets future: Codex/OpenCode adapters, capability evidence and named provider profiles #339 — Managed Targets future: Codex/OpenCode adapters, capability evidence and named provider profiles
• Future research: Claude Remote Control compatibility and per-profile launch policy #340 — Future research: Claude Remote Control compatibility and per-profile launch policy
• Future security/runtime: enforced isolation for executable NMSh Portable Mods #341 — Future security/runtime: enforced isolation for executable NMSh Portable Mods

Architecture boundary

Terminal first, not terminal minimal. NMSh is a terminal-first control/presentation surface over a persistent real shell. Resource navigation does not transfer ownership: tmux owns sessions/windows/panes/PTYs (pseudo-terminals), layout and detach; editors own source editing; GitHub owns remote truth; provider agents own models, reasoning, context/compaction, native tools and the agent loop. NMSh is not a terminal emulator, multiplexer, replacement shell language, editor, browser engine or independent coding-agent harness. See closed #179.

Planning status and sequencing

Future specification only; no implementation is claimed or authorized by this issue. PR #328 is actively being fixed separately. PR #329 is paused until #328 lands and must remain untouched. References to these PRs are dependencies, not requests to amend or merge them. Automated verification and human terminal validation are separate gates.

Related existing issues / PRs

#14, #20, #164, #165, #166, #167, #169, #175, #179, #197, #297, #304, #305, #317, #321; PR #328 and PR #329.

Roadmap organization and ordering

This is a future program index, not a current-milestone commitment. No release/version is assigned. First let #328 land through its independent fix/QA work; #329 stays paused until then. After the Managed Target foundation is accepted, design shared regional focus, responsive ScreenPlan geometry and semantic actions before dependent workspace surfaces. Each child should ship in bounded reviewed slices with its own automated and physical evidence.

Audited foundations and existing owners

Required audit covered open/closed #14, #20, #164, #165, #166, #167, #169, #175, #179, #197, #297, #304, #305, #317, #321 and read-only PR #328/#329, plus related issue bodies/discussion and repository-wide issue inventory.

• Open CLI and TUI interoperability compatibility suite #14 stays compatibility regression/physical evidence; Ongoing polish: mouse, Unicode, completions, history, performance, and installation #20 stays residual triage, not a second feature spec.
• Closed notMyUI: reusable interaction and presentation toolkit #164/Surface customization: frames, fills and backgrounds #165/Central actions, key bindings and contextual help #166/Reusable form controls for settings and configuration #167/Settings experience v2: searchable registry and progressive disclosure #169 remain reusable UI/settings foundations. Central actions, key bindings and contextual help #166 deferred remapping; Configurable semantic keymap and terminal-host conflict guidance #335 is its focused continuation.
• Closed Research terminal multiplexer interoperability #175 research and Terminal frontend landscape and NMSh product boundary #179 boundary are reference foundations, not reopened implementation trackers.
• Closed Live sessions: user-controlled startup restore (ask / always / never, multi-session picker) #197 remains startup restoration/picker; ongoing workspace navigation is Workspace Sidebar: keyboard-first resource navigation with explicit focus and activation #331.
• Closed Setup Cat, appearance studio and idle visuals above the v0.14 stack #297 remains Setup Cat/appearance/idle foundation; progressive integration profiles are Setup Cat integration profiles: progressive onboarding for tmux, editors and provider agents #334.
• Open Theme Bridge and semantic terminal integration #304 remains generic Theme Bridge architecture; /tmux Studio: status, appearance, Context modules and workspace integration #333 evolves existing /tmux Config Studio and adds focused status/module/workspace policies.
• Open NMSh Native module ecosystem and upstream module ports #305 remains shared facts/modules/discovery; [Context Engine] Surface Router and Context Rail #317 remains routing; [Context Engine] Security, performance, hostile-workspace and physical QA #321 remains Context Engine security/performance/physical QA. Consumers link these instead of duplicating them.
• Add keyboard-first managed Claude targets and unified mod inventory #329 is the first Claude foundation, not proof of future Codex/OpenCode/live-attach/executable-mod support.

Deliberately consolidated ideas

No separate focus-system issue: shared contract here and #331/#332/#335 extends #329.
No separate tmux Chroma, status-coordination or navigation tracker: #333 owns those together, with #331 consuming navigation.
No new generic Theme Bridge or Context Engine tracker: #304/#305/#317 stay authoritative.
No separate agent-shelf/idle/Vespyr migration tracker: #331 owns workspace coexistence; #297 is closed foundation.
No forced /agents or /sessions migration: future design in #331.
Remote Control (#340) and executable Portable Mods (#341) are deferred research/security children linked through #339; not bundled into #329.

Open decisions

Measure width breakpoints and Chroma cadence/defaults; choose command/alias migration only after compatibility audit; define tmux multi-instance publisher arbitration and supported editor addressability; prove each provider/live-attach/Remote Control transport; enforce sandbox isolation before executable mods. Do not imply these are already supported.