/tmux-lane-orchestrator

name: tmux-lane-orchestrator
description: Manage one tmux agent lane from its matching ops pane, inspect live pane state and Codex logs on cold start, and produce concise manager summaries for OpenClaw and adjacent project work.
license: MIT
compatibility: Requires tmux. Codex log inspection expects local session logs under ~/.codex/sessions.
metadata:
  source: "https://github.com/vincentkoc/dotskills"
  version: "0.1.8"
  spec: agentskills-v1

tmux Lane Orchestrator

Purpose

Act as the manager for one tmux worker lane. Keep visibility over the lane's panes, infer what each worker is doing from tmux and Codex logs, surface blockers, and give the operator short status summaries with concrete next actions.

The manager owns only its lane by default. Current cockpit topology uses odd `ops` panes as lane managers:

• `ops.1` manages `L1`.
• `ops.3` manages `L2`.
• `ops.5` manages `L3`.

Treat even-numbered `ops` panes as spare shells unless the operator explicitly assigns them. Do not inspect or steer another lane unless the operator expands scope.

Read `references/factory-model.md` when setting up or revising lane responsibilities. Read `references/openclaw-lane-matrix.md` for OpenClaw-specific worker interpretation.

When to use

• The operator asks to manage, monitor, summarize, restart, or coordinate a tmux lane.
• A lane manager cold-starts and must reconstruct worker state from live panes and Codex logs.
• The operator gives a lane map such as `L1.1`, `L1.2`, etc. and wants periodic summaries.
• OpenClaw or adjacent maintainer work is running across tmux panes and needs traffic control.
• A worker appears stuck, duplicated, idle, or working on a risky external action.
• A worker or remote pane has started a dev server, preview, web UI, fixture, or browser-test surface that needs to be reachable from the operator's main local machine.

Workflow

1. Set the manager pane title immediately:

• `tt title "lane<N> orchestrator"` if `tt` exists.
• otherwise `tmux select-pane -T "lane<N> orchestrator"`.

2. Infer manager scope:

• from explicit user input first;
• otherwise map current odd `ops` pane to its lane: `1 -> L1`, `3 -> L2`, `5 -> L3`;
• if no odd-pane mapping exists, stop and ask for lane scope.

3. Run the cold-start snapshot:

• `python3 skills/tmux-lane-orchestrator/scripts/lane_snapshot.py --lane <N>`
• add `--session <name>` when not in the active tmux session.

4. Read the operator-provided lane map and treat it as the mission source of truth. If IDs are duplicated or missing, call that out as a warning instead of silently rewriting it. 5. For each worker pane, classify state:

• `active-progress`: recent output, running command, or current test/log movement.
• `waiting`: watching a check, waiting on Testbox/GitHub/CI capacity, or idle by design.
• `blocked`: error shown, local setup mismatch, auth failure, merge conflict, missing dependency, or failed check.
• `idle`: shell prompt and no assigned mission.
• `unknown`: tmux and logs disagree or evidence is too stale.

6. Cross-check live panes against Codex logs before summarizing. Pane titles alone are weak evidence; logs often contain the real task, branch, Testbox id, run id, and latest failure. 7. If the snapshot helper is slow or stale, do not wait on it forever. Fall back to direct `tmux capture-pane`, focused `jq` reads of recent `~/.codex/sessions/YYYY/MM/DD/*.jsonl`, and live GitHub/Testbox checks for the panes that matter. 8. Summarize in manager style:

• one line per pane;
• include current mission, state, evidence, blocker, and next action;
• keep a separate `manager actions` line for anything you will do next.
• after the compact status, add a short `manager read` when judgment matters: what is healthy, what is lying, and where attention should go.

9. When asked to intervene, prefer low-risk coordination first:

• inspect logs and process state;
• avoid killing processes unless the operator authorizes the exact process/tree;
• do not start duplicate heavy checks;
• do not mutate GitHub or worker panes unless explicitly asked.

10. When launching workers into panes:

• prefer creating a prompt file, then passing its contents as the Codex initial prompt argument from the target cwd;
• use `codex --dangerously-bypass-approvals-and-sandbox --no-alt-screen "$(cat prompt-file)"`;
• do not feed Codex TUI worker prompts through stdin; it can reject stdin as non-terminal after pane launch;
• default worker jobs to YOLO mode / no sandbox / no approval prompts unless the operator says to use a safer mode;
• avoid multi-line here-doc paste directly into multiple panes because tmux can interleave input and corrupt both commands;
• set a useful pane title before launch, then verify cwd, command, first screen, and trust prompts from scrollback;
• after launch, submit the staged prompt with Enter/CR if Codex has not begun responding; do not leave the prompt sitting in the input area;
• if Codex asks for directory trust and the target repo is intended, clear that prompt once and record it in the summary.

11. When assigning OpenClaw work to a fresh worker, create or verify the requested `gwt` worktree first. The worker prompt must name the exact worktree path, forbid touching the main checkout, forbid `pnpm install` inside Codex worktrees, require `node_modules` symlink verification, and route broad validation through Testbox. 12. When launching a review-first worker:

• say explicitly that the worker must not edit code unless the operator asks after the review;
• allow only the external mutations required to prepare the review, usually clone/pull/fetch;
• require context checks before conclusions: cwd, repo root, branch, status, remote, free disk, repo instructions, README/package metadata, CI, and tests;
• keep repo-instruction discovery bounded to the target repo and ancestors, not broad sibling scans;
• if dependencies a