vincentkoc / 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.

2. Capture lane state.

   • python3 scripts/lane_snapshot.py --lane <number>
   • Add --session <name> outside the active tmux session.

   • If a descendant command does not contain its resumed thread ID, repeat
     --thread L<number>.<pane>=<thread-id> from separately verified evidence.

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

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

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

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

6. 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 log keywords and capture depth.
• 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 --> [*]