Workspace and session routing: team walkthrough

Focused workspace/pane/surface/session routing, registry-based Codex forks, routing preflight, durable transcript exports, helper visibility, and diagnostic paths for invalid workspace handles, wrong sessions, and missing exports.

Team Learning Goal

Teach focused routing, not terminal window management.

The audience should understand workspace -> pane -> surface/tab -> process/session -> receipt, and should be able to explain why shortcuts must route to the focused surface and correct Codex session.

Walkthrough Depth

Essential Walkthrough

  1. Draw workspace -> pane -> surface/tab -> process/session -> receipt.
  2. Run cmux identify.
  3. Run cmux rpc workspace.current.
  4. Show the invalid --workspace current failure.
  5. Dry-run cmux-fork-focused-codex --preflight-fork.
  6. Show cmux-xport and .exports.

Expanded Walkthrough

Add:

  • cmux-run-surface
  • stable surface lookup
  • registry resolution
  • Esc+P, Esc+Shift+P, Esc+E, Esc+M
  • muxai versus agent_chain

Deep-Dive Walkthrough

Add:

  • workspace focus/open dry-run
  • screen fallback caveat
  • helper function visibility for xfl, xfc, xport, p-f, p-c
  • exercises

Talking Points

Opening:

Focused context is a routing problem, not a prompt problem.

On the graph:

A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable.

On cmux vs tmux:

cmux is the building. tmux is one kind of room layout inside the building.

On focused forks:

Esc+P is not just a shortcut. It is a session-routing pipeline.

On exports:

Clipboard is convenience. .exports is the durable receipt.

Essential Points To Preserve

Preserve:

cmux identify
cmux rpc workspace.current
cmux-focus-or-open-workspace /path/to/project
cmux-run-surface "echo ok"
cmux-fork-focused-codex --dry-run --preflight-fork
cmux-xport

Preserve this route:

focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c

Failure Paths To Preserve

Invalid workspace handle:

cmux top --workspace current --processes --flat --format tsv

Wrong session fork:

cmux-fork-focused-codex --dry-run --preflight-fork

Missing export:

ls -lt .exports | head

Function not found:

zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport'

Boundaries

Section 3 is about helper names and zsh runtime shape. Section 4 is about where those helpers run.

Section 3 Section 4
Is this a function, alias, or executable? Which pane/surface/session does it target?
whence -w cmux identify
type, functions, funcwhere workspace.current, pane.surfaces
zsh helper loading cmux socket routing
executable fallbacks new panes, focused session forks, exports

Section 5 builds the preflight prompt before a routed fork runs.

Further References

Source references