Pane organization friction when orchestrating 6+ agents (P1-P5 + F1-F6 proposals)

[EtanHey]

User-reported friction. Verbatim from 2026-04-30 17:10 IDT after returning from AFK with 6 agents in flight: "Why do I come home to seeing the plans this way? Can you reorganize it?"

Root cause analysis + 6 proposed fixes at orcClaude's collab:

• ~/Gits/orchestrator/collab/2026-04-30-cmuxlayer-pane-organization.md

Quick summary of problems:

• P1 Tab grouping is incidental — agents end up in random panes by spawn order (today: voicelayer / skillCreator / brainlayer ended up in the SAME pane purely because they were new_split'd in that sequence).
• P2 Auxiliary execution shells (zsh panes driven by an agent via cmux send) look identical to agent panes — no visual distinction.
• P3 Stale Claude-resume-prompt panes don't decay (today: a 6h 41m old golemsClaude resume prompt sat in orcClaude's pane until orc tried to use it).
• P4 No API for orcClaude to express logical grouping — new_split only takes a direction, not a logical "swimlane."
• P5 Tab titles go stale — brainlayerCodex PR#261 was actually working on PR fix: prevent retry-enter duplicate submits #263; voicelayerCodex Round 2 was on silence55 W13. Agents don't proactively rename_tab.

6 proposed fixes (F1-F6) including: logical-group hint for new_split, auto-rename on activity, idle-decay visual signal, agent-vs-shell visual distinction, layout JSON spec via new MCP tool, sweep-stale-resume-prompts on session-end.

4 workarounds (W1-W4) orcClaude can apply immediately without cmuxlayer code changes — already starting.

This is friction-tier, not a blocker — but compounds with each new agent spawn. Today the user came home to 6 agents across 4 panes with random grouping; once we routinely run 8-10+ agents, this gets worse fast.

Tracked as imp-7 in BrainLayer. Will store milestone chunk on triage.

[EtanHey]

REFINEMENT from user 2026-04-30 17:35 IDT — the right axis is NOT topic ("group") but layer by remoteness from human attention:

Layer	Position	Who
L0 — General	leftmost	the human's direct conversation partner (orcClaude, coachClaude, single-repo lead)
L1 — Sergeants	middle	sub-agents the General spawned (codex/cursor workers)
L2 — Lieutenants / sergeants'-helpers	rightmost	long-running auxiliaries spawned BY sergeants (e.g., shell terminals driven via cmux send)

Why this beats group-by-topic:

• Topic shifts (an agent switches from FTS to TCC). Layer is stable.
• Maps human eye-attention (left = closest to me) directly onto agent hierarchy.
• Aligns with the sergeant/general framing already canon in /agent-routing (after EtanHey/golems PR #392 merges).

Revised F1 API:

new_split direction=right layer=L1 spawned_by=s:22 title="<task>"
new_split direction=right layer=L2 spawned_by=s:4 title="$ aux-shell driven by s:4"

cmuxlayer enforces: L0 leftmost, L1 next, L2 furthest right. Within a layer, spawn-order is fine.

Visual cue per layer: L0 full chrome / primary color; L1 slight recess; L2 dimmer + smaller — "this is far from you" cue.

Auto-classify when not tagged: parent-of-send_input chain → L2. Direct human-typed Claude → L0.

Naming options: L0/L1/L2 (numeric, scales) vs. General/Sergeant/Helper (matches /agent-routing framing). Recommend numeric for API + alias --layer=general/sergeant/helper for CLI human-readability.

Full refinement in ~/Gits/orchestrator/collab/2026-04-30-cmuxlayer-pane-organization.md REFINEMENT section.

[EtanHey]

REFINEMENT 2 from user 17:42 IDT — aux-shells / servers live in L0, not L2. The distinction is WHO CONTROLS the surface:

• Human/General controls → L0 (multi-tab, leftmost)
• Sergeant drives via cmux send (human shouldn't touch) → L2 (rightmost)
• Ambiguous → bias L0

Final layer model:

Layer	Position	Who
L0 — General zone	leftmost, multi-tab	Interactive Claude + aux-shells + servers + background processes the human controls
L1 — Sergeants	middle	Sub-agents the General spawned
L2 — Lieutenants	rightmost (when present)	Long-running auxiliaries spawned BY sergeants — agent-managed only

Layout executed manually right now via existing move_surface MCP tool (until cmuxlayer ships F1/F5):

• LEFT pane: s:22 orcClaude + s:25 $ aux-shell
• RIGHT pane: 4 sergeant tabs

Source-of-truth chunk: brainbar-... (storing this turn).