{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-workspace-routing-team-guide",
  "slug": "workspace-routing-team-guide",
  "title": "Workspace and session routing: team walkthrough",
  "summary": "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.",
  "category": "Team practice",
  "tags": [
    "cmux",
    "tmux",
    "orchestration",
    "team-guide"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Preserve If Short On Time",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Failure Paths To Preserve",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Boundaries",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Presenter References",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 449,
  "url": "/topics/codex-workspace-routing-team-guide/",
  "markdownUrl": "/markdown/codex-workspace-routing-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-workspace-routing-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "essential-points-to-preserve",
      "text": "Essential Points To Preserve",
      "level": 2
    },
    {
      "id": "failure-paths-to-preserve",
      "text": "Failure Paths To Preserve",
      "level": 2
    },
    {
      "id": "boundaries",
      "text": "Boundaries",
      "level": 2
    },
    {
      "id": "further-references",
      "text": "Further References",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Workspace and session routing: team walkthrough\n\n## Team Learning Goal\n\nTeach focused routing, not terminal window management.\n\nThe 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.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Draw `workspace -> pane -> surface/tab -> process/session -> receipt`.\n2. Run `cmux identify`.\n3. Run `cmux rpc workspace.current`.\n4. Show the invalid `--workspace current` failure.\n5. Dry-run `cmux-fork-focused-codex --preflight-fork`.\n6. Show `cmux-xport` and `.exports`.\n\n### Expanded Walkthrough\n\nAdd:\n\n- `cmux-run-surface`\n- stable surface lookup\n- registry resolution\n- `Esc+P`, `Esc+Shift+P`, `Esc+E`, `Esc+M`\n- `muxai` versus `agent_chain`\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- workspace focus/open dry-run\n- screen fallback caveat\n- helper function visibility for `xfl`, `xfc`, `xport`, `p-f`, `p-c`\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Focused context is a routing problem, not a prompt problem.\n\nOn the graph:\n\n> A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable.\n\nOn `cmux` vs `tmux`:\n\n> cmux is the building. tmux is one kind of room layout inside the building.\n\nOn focused forks:\n\n> `Esc+P` is not just a shortcut. It is a session-routing pipeline.\n\nOn exports:\n\n> Clipboard is convenience. `.exports` is the durable receipt.\n\n## Essential Points To Preserve\n\nPreserve:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ncmux-focus-or-open-workspace /path/to/project\ncmux-run-surface \"echo ok\"\ncmux-fork-focused-codex --dry-run --preflight-fork\ncmux-xport\n```\n\nPreserve this route:\n\n```text\nfocused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c\n```\n\n## Failure Paths To Preserve\n\nInvalid workspace handle:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nWrong session fork:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nMissing export:\n\n```bash\nls -lt .exports | head\n```\n\nFunction not found:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\n```\n\n## Boundaries\n\nSection 3 is about helper names and zsh runtime shape. Section 4 is about where those helpers run.\n\n| Section 3 | Section 4 |\n| --- | --- |\n| Is this a function, alias, or executable? | Which pane/surface/session does it target? |\n| `whence -w` | `cmux identify` |\n| `type`, `functions`, `funcwhere` | `workspace.current`, `pane.surfaces` |\n| zsh helper loading | cmux socket routing |\n| executable fallbacks | new panes, focused session forks, exports |\n\nSection 5 builds the preflight prompt before a routed fork runs.\n\n## Further References\n\n- team member cheatsheet: `cheatsheets/04-agentic-dev-environment-orchestrator.md`\n- Exercises: `exercises/04-agentic-dev-environment-orchestrator.md`\n- tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html\n- tmux GitHub wiki: https://github.com/tmux/tmux/wiki\n- OpenAI Codex: https://openai.com/codex/\n- Model Context Protocol: https://modelcontextprotocol.io/\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
