vincentkoc/dotskills/tmux-agent-lane-orchestrator

tmux Agent Lane Orchestrator

Purpose

Turn a tmux window of coding-agent workers into a visible, auditable lane with clear state and next actions.

When to use

• Monitor or summarize a tmux worker lane.
• Reconstruct worker state after a manager cold start.
• Detect duplicated, idle, waiting, blocked, or risky work.
• Coordinate several coding-agent panes without mutating them blindly.

Workflow

1. Establish lane scope.

• Prefer an explicit lane number.
• Otherwise infer it from a current tmux window named L<number>.
• Do not inspect other lanes unless the operator expands scope.

1. Capture lane state.

• Resolve this loaded skill's directory, then run

python3 <skill-root>/scripts/lane_snapshot.py --lane <number>. Do not resolve the helper from the worker repository cwd.

• Add --session <name> outside the active tmux session.
• Linux inference requires a native Codex executable and bounded, structured

argv matching codex resume UUID or codex exec resume UUID exactly. Other argument forms stay unknown. Flat ps text cannot establish identity.

• macOS reads executable paths only. Without a separately verified binding,

it reports unknown and the next action. Pass --thread L<number>.<pane>=<thread-id> only from independent evidence. A declaration still requires an unambiguous descendant Codex PID.

• Add --json for machine-readable output.
• Add --cursor-file <path> only when bounded incremental state is wanted;

the helper writes no persistent state by default.

• Records larger than the smaller of --log-bytes and --total-log-bytes

are skipped through their next newline. The cursor reports discarding_record while skipping; later events resume.

1. Cross-check panes and logs.

• Pane titles alone are weak evidence.
• Resolve pane ID to shell PID, descendant Codex PID, exact thread ID, the

state-database rollout path, and the newest turn.

• Shared cwd and generic terms such as CI, failed, or running never

establish ownership.

• Missing or conflicting identity is unknown, never a restore target.

1. Classify each pane.

• Use the newest exact turn and changing event/tool/token counters.
• A completed turn after an earlier error is completed, not blocked.
• Report bounded bytes read and truncation with the state.
• Include the evidence and next action, not only the label.

1. Intervene conservatively.

• Inspect before steering.
• Avoid duplicate heavy checks.
• Do not kill or mutate another pane without explicit scope.
• Prefer reversible actions and targeted commands.

1. Summarize in manager style.

• One line per pane: mission, state, evidence, blocker, next action.
• Add one short manager judgment about where attention belongs.

Read references/factory-model.md when designing lane responsibilities or escalation policy.

Inputs

• tmux session name.
• Lane number or L<number> window.
• Optional capture depth and per-rollout/total log byte limits.
• Optional exact pane/thread declarations and bounded cursor path.
• Optional operator-provided worker mission map.

Outputs

• Current pane ID, shell PID, descendant agent PID, exact thread, and rollout snapshot.
• Per-pane state classification with evidence.
• Per-file and total log bytes read, cursor mode, and truncation status.
• Concise manager summary and safe next actions.

Flow

stateDiagram-v2
    [*] --> ResolveOneLane
    ResolveOneLane --> CaptureAndMatchIdentity
    CaptureAndMatchIdentity --> ReportUnknown: missing or conflicting identity
    CaptureAndMatchIdentity --> ClassifyNewestTurn: identity matched
    ClassifyNewestTurn --> ReportLane: observation only
    ClassifyNewestTurn --> TargetedIntervention: exact scope authorized
    TargetedIntervention --> VerifyAndReport
    ReportUnknown --> [*]
    ReportLane --> [*]
    VerifyAndReport --> [*]