P4.0: Spike — team-dashboard zellij behaviour (multiplexer Phase 4)

[takemo101]

Phase 4, issue P4.0 (spike) — part of the multiplexer backend abstraction implementation plan.

Design: docs/designs/cuekit-multiplexer-backend-design.md

Prerequisites: Phase 3 (#410-#415) all merged. This issue must close before P4.2 starts.

Outcome

The four Phase 4 spike open questions answered on real zellij before implementation begins.

Files

(Throwaway branch.)

Steps

• Verify zellij action write-chars --pane-id support; document workaround if absent (focus-then-write).
• Pin exact zellij attach --create-background + inline-layout invocation form in the target version.
• Confirm rename-pane of a held (exited-command) pane preserves the exit-code line and stays readable.
• Confirm new-pane stdout reliably yields a parseable pane id (and what format the id takes).

Acceptance

Issue resolution comment lists each question's answer + reference command output. P4.2 cites this comment.

[takemo101]

P4.0 spike findings (zellij 0.43.1, macOS)

Tested locally on zellij 0.43.1 from the cuekit repo.

Summary / recommendation

Do not start Phase 4 team-dashboard implementation on the current assumptions. zellij 0.43.1 can create additional child processes in a detached session, but the CLI does not expose a stable pane id and live operations (write-chars, dump-screen, rename-pane) target the focused pane/screen state in ways that are not reliable without a connected client. This is not enough for cuekit's existing steer/capture/cancel semantics for multiple team members in one session.

Recommended next step: either defer Phase 4 until a newer zellij version with verified pane targeting is required, or reduce Phase 4 scope to an attach-only dashboard where cuekit does not claim per-member steering/capture in the shared zellij session.

Environment

zellij 0.43.1
macOS

1. attach --create-background with initial layout

This works and is still the safe bootstrap pattern for detached sessions.

Command form:

zellij attach --create-background <session> \
  options --default-cwd "$PWD" --default-layout <layout.kdl>

Minimal layout used:

layout {
  pane name="coord" command="sh" {
    args "-c" "printf 'coord-start\\n'; sleep 300"
  }
}

Observed:

create_exit=0
<session> [Created 1s ago]

2. Adding a pane to a detached session

Both forms exit successfully and start a child process:

zellij --session <session> action new-pane -n worker -- sh -c "printf 'worker-start\\n'; sleep 300"
zellij --session <session> run -n runner -- sh -c "printf 'runner-start\\n'; sleep 300"

Observed for new-pane:

newpane_exit=0
stdout: <empty>
stderr: <empty>
...
sh -c printf 'worker-start\n'; sleep 300
sleep 300

Observed for run:

run_exit=0
stdout: <empty>
stderr: <empty>
...
sh -c printf 'runner-start\n'; sleep 300
sleep 300

Important caveat: neither command printed a pane id. action dump-layout also did not provide runtime pane ids for the added panes; it showed only the layout/template shape. So P4 cannot persist a real pane handle from these commands in 0.43.1.

3. Stable pane targeting / steering

write-chars has no pane-targeting option in 0.43.1:

USAGE:
    zellij action write-chars <CHARS>

There is no --pane-id flag. rename-pane and dump-screen similarly operate on the focused pane only.

In a detached session with no connected client, write-chars and write 13 exited 0 but did not deliver input to a simple cat > file command in the pane:

write_exit=0 out= err=
enter_exit=0 out= err=
file: <empty>

This means focus-based steering is not a safe backend primitive for a shared team session when no client is attached.

4. dump-screen / live capture

In the detached test session, dump-screen --full <path> exited 0 but did not create useful output for the focused pane:

dump_exit=0 out= err=
cat: <dump path>: No such file or directory

This reinforces that live capture for a shared detached team session is not reliable in 0.43.1 without additional verified targeting/client behavior.

5. rename-pane / held panes

rename-pane <name> has no targeting option and only renames the focused pane. In detached tests it exited 0, but because stable pane targeting and reliable dump/capture were not available, I could not verify a robust held-pane rename workflow for a specific completed team member.

6. Session naming

Use compact names. Phase 3's ct-<task_id> avoided macOS socket path limits. For team sessions, prefer a compact form such as:

ctm-<short_team_id>

Do not use long cuekit-team-<team_id> names unless a separate socket-path test proves them safe.

Conclusion

For zellij 0.43.1, Phase 4 as originally described is too risky:

• add-pane starts processes but returns no stable pane id
• write/rename/dump are focus-based only
• focus operations are unreliable without a connected client
• live capture and steering would not match cuekit's per-task semantics

Recommended implementation gate before P4.2:

1. Require a newer zellij version only if it provides verified stable pane targeting, or
2. Redesign Phase 4 as an attach-only human dashboard and explicitly keep per-task steering/capture on per-task sessions, or
3. Defer Phase 4 and improve the existing TUI team view instead.

[takemo101]

P4.0 spike completed on zellij 0.43.1. Result: do not proceed to P4.2 on the current design; stable pane targeting/steering/capture for shared detached team sessions is not available/reliable. See the resolution comment above for command output and recommended alternatives.

[takemo101]

Updated P4.0 spike findings after upgrading to zellij 0.44.2

Supersedes the earlier 0.43.1 conclusion for environments that can require zellij 0.44.2+.

Summary

zellij 0.44.2 adds the primitives Phase 4 was missing:

• action new-pane returns a pane id (terminal_N).
• action write-chars, write, dump-screen, and rename-pane accept --pane-id / -p.
• Detached new-pane against a session with no connected client starts the child process and returns a usable pane id.
• dump-screen -p <pane> --full works and can print to stdout or write to --path.
• rename-pane -p <pane> works for running and held/exited panes.

This makes a real zellij team-dashboard implementation viable if Phase 4 raises the zellij requirement to 0.44.2+ for team sessions. Phase 3 solo-task support can continue to support 0.43.x if desired.

Environment

/opt/homebrew/bin/zellij --version
zellij 0.44.2

Note: this machine still has an older cargo-installed ~/.cargo/bin/zellij earlier on PATH. Tests used /opt/homebrew/bin/zellij explicitly.

1. Detached session bootstrap

Initial layout create still works:

zellij attach --create-background <session> \
  options --default-cwd "$PWD" --default-layout <layout.kdl>

Observed:

create_exit=0 stdout= stderr=
<session> [Created 1s ago]

The initial layout pane is addressable as terminal_0 in this simple one-pane layout:

zellij --session <session> action write-chars -p terminal_0 "msg-terminal_0"
zellij --session <session> action write -p terminal_0 13
zellij --session <session> action dump-screen -p terminal_0 --full

Observed file/input and dump:

file=msg-terminal_0|msg-0|
coord-ready
msg-terminal_0
msg-0

Caveat: writing to a non-existent pane id exited 0 but had no effect in one quick test, so cuekit should still validate pane ids from spawn results and not assume command success proves delivery.

2. Adding panes to detached team session

new-pane now returns a pane id and starts the child process:

zellij --session <session> action new-pane -n worker -- sh -c "printf 'worker-ready\\n'; cat > '<worker_file>'"

Observed:

new_exit=0 new_id=terminal_1 stderr=

Using the returned id for steering worked:

zellij --session <session> action write-chars -p terminal_1 "hello-worker"
zellij --session <session> action write -p terminal_1 13

Observed:

worker_file=hello-worker

zellij run also starts a process in the detached session, but action new-pane is preferable because its help explicitly documents returning the created pane id.

3. Pane-targeted capture

dump-screen now accepts --pane-id/-p and can print to stdout:

zellij --session <session> action dump-screen -p terminal_1 --full

Observed:

dump_worker_exit=0 stderr=
worker-ready
hello-worker

The new CLI also supports --path <PATH> if file output is preferred.

4. Pane-targeted rename and held pane behavior

rename-pane now accepts --pane-id/-p:

zellij --session <session> action rename-pane -p terminal_1 renamed-worker

Observed in dump-layout:

pane command="cat" name="renamed-worker" size="50%" {
    start_suspended true
}

Held/exited pane test:

zellij --session <session> action new-pane -n held -- sh -c "printf 'held-output\\n'; touch '<marker>'; exit 0"
# returned terminal_2
zellij --session <session> action rename-pane -p terminal_2 'held-completed'
zellij --session <session> action dump-screen -p terminal_2 --full

Observed:

held_marker_exists=yes
rename_held_exit=0 stderr=
dump_held_exit=0 stderr=
held-output

And dump-layout showed:

pane command="sh" name="held-completed" ... {
    args "-c" "printf 'held-output\\n'; touch '<marker>'; exit 0"
    start_suspended true
}

5. Session naming

Compact team session names are still recommended (ctm-<short_team_id>), because socket path limits remain relevant on macOS. The spike session names used ctm044-* successfully.

Revised conclusion

Proceeding with Phase 4 is now reasonable under these constraints:

1. Team dashboard requires zellij >= 0.44.2.
2. Use action new-pane and persist the returned terminal_N as the zellij team-member pane id.
3. Use pane-targeted operations:
   • write-chars -p <pane_id> + write -p <pane_id> 13
   • dump-screen -p <pane_id> --full [--path <path>]
   • rename-pane -p <pane_id> <name>
4. Keep compact team session names.
5. Keep a fallback/diagnostic path for invalid or stale pane ids because some commands may exit 0 even when targeting a non-existent pane.
6. Still dogfood attach/resize manually before shipping interactive team dashboard UX; the headless spike verifies pane targeting but not human resize behavior inside an attached team dashboard.

[takemo101]

Reopened briefly to record updated zellij 0.44.2 spike results. The new findings indicate Phase 4 can proceed if team dashboard requires zellij >= 0.44.2 and uses pane-targeted commands.

[takemo101]

P4.0 spike is complete with updated zellij 0.44.2 findings recorded. Phase 4 may proceed under the constraints in the latest comment.