tmux-lane-orchestrator

What this skill does

# 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.

## 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 private-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 are missing, verify documented install/test paths in a temp environment outside the checkout and clean it up;
   - for package or CLI repos, check the installed artifact path, not just editable/source-checkout tests; editable installs can hide missing package data;
   - ask for findings first with file/line evidence, commands run, pass/fail results, quick wins, strategic risks, and a ship/hold/fix-first recommendation.
   - when the review finishes, summarize only the top severity, main recommendation, and whether implementation needs a new explicit go-ahead; keep the worker open for follow-up.
13. When reallocating active work:
   - name exactly which pane is now the sole coordinator for final integration or push;
   - tell superseded panes to finish only their already-running command, then stop/report branch HEAD, check result, and blockers;
   - preserve useful in-flight Testbox or CI evidence, but do not start duplicate broad gates;
   - coordinator must re-verify cwd, branch, status, symlinks, drift, cheap checks, and final rebase before pushing.
14. When running a multi-job queue:
   - keep a visible queue with job URL/id, assigned pane, worktree, state, and next action;
   - do live metadata before assignment because "merge as-is" can become conflicts, failed checks, or unresolved review comments;
   - batch merge/closure jobs conservatively to avoid rebase churn;
   - each worker prompt must include exact scope, review/comment obligations, merge/closure policy, and final report shape.
15. When deciding whether to allocate more work:
   - scrape live lane state first;
   - allocate only when there is idle capacity and a concrete next slice;
   - do not allocate just to use empty panes; more workers without a crisp slice creates coordination sludge;
   - if the right next action is waiting for CI/CodeQL/Testbox or one closeout watcher, say that and leave panes idle;
   - when fresh scanners or runners were just added, validate the live result set before assigning fixers. If new analyses report zero results and open alerts are old-profile residue, allocate closeout/dismissal buckets or a watcher, not implementation lanes.
16. For metric tracking:
   - store baseline and samples in a local TSV or similar lightweight artifact when the operator asks to track progress over time;
   - report absolute counts plus deltas from baseline, not vibes;
   - verify the tracker process is still alive before relying on it, and restart or sample manually if it died;
   - if new automation is opening work while workers close work, call out the slope honestly.
17. For secrets and repo s