| name | foxctl-room-view |
| description | Viewer-layer guidance for room panes: tmux or zellij setup, PTY inspection, manual pane pokes, and transport-vs-viewer debugging. |
foxctl-room-view
Use this skill when you need the presentation layer for a room participant:
- create or inspect tmux/zellij panes
- read PTY output
- place or relabel viewer panes
- send a one-off manual poke into a pane
- debug viewer state separately from room transport
This skill is not the room source of truth.
Mental model
foxctl is the headless room/runtime kernel.foxctl room is canonical coordination and delivery.- participant transport is canonical execution.
- room-scoped clients should consume
GET /api/rooms/{room-id}/events?workspace_id=... for room timeline updates; the global /api/events feed is broader transport, not the room-specific contract.
delivery_binding is the canonical room member routing record; mux metadata is a viewer/presentation layer and older top-level member transport fields are not emitted in room member API responses.last_delivery_trace is the canonical explanation surface for the last delivery decision:
when debugging “why did this message route here,” prefer room status / loop status over PTY guesswork.tmux, zellij, GUI PTY previews, and future xterm viewers are presentation attachments only.foxctl mux is for viewer setup, pane reads, and manual live interaction.
Hard boundary:
- mux is not the room core
- mux is not the delivery authority
- mux is not the source of room truth
Default flow
When a room already exists:
foxctl room status <room-id>
foxctl mux list
foxctl mux read <target> --lines 80
Use room status to understand health. Use mux list/read to understand viewer placement and PTY state.
What mux is for
foxctl mux create for pane/session creationfoxctl room restore when the real goal is to revive an existing room participant in one stepfoxctl mux list for viewer metadatafoxctl mux read for PTY inspectionfoxctl mux observe when a live pane exchange should become durable ContextWiki evidencefoxctl mux send for a manual terminal poke outside the normal room transport pathfoxctl room restore should be preferred over manual mux create + room rebind when you are reviving an existing participant runtime
Launch-mode rule:
foxctl mux create --agent droid --mode auto enables the Droid-specific startup profile used by the transport-first wrapper.- That profile waits for the Droid UI to reach its
Auto (Off) state and then sends Ctrl+L three times to clear/advance the runtime into its intended high-autonomy startup path.
--mode interactive does not use that startup profile.- So if someone launches Droid with
--mode interactive, they have explicitly bypassed the Droid auto-start behavior and may still see approval-gated runtime behavior.
- Treat that as a launch/runtime choice, not a room-delivery failure.
What mux is not for
- canonical room history
- task state
- reminder execution
- proof of participant membership
- proof of participant transport health
Viewer debugging rules
- If pane output looks wrong but
room status shows healthy transport/runtime, debug the viewer layer.
- If the pane looks fine but room delivery fails, debug participant transport and membership before touching tmux/zellij.
- A missing PTY is a presentation issue until room transport also fails.
- If reminder behavior is surprising, remember that reminder-instance
ack does not stop the schedule by itself; check loop state, linked work, and chain satisfaction before blaming the viewer layer.
Regression Check
- When you need to confirm the hardened room-runtime invariants end to end, use
bash tests/regression/run.sh.
Compatibility
Older docs may still refer to:
Treat those as compatibility names for this presentation-layer role. The architecture now belongs to foxctl-room + foxctl-room-agent + foxctl-room-operator.
