yoi/work-items/open/20260601-132955-tui-pod-connect-command/item.md

id: 20260601-132955-tui-pod-connect-command slug: tui-pod-connect-command title: TUI: add command for connecting to another Pod status: open kind: task priority: P2 labels: [tui, pod, command, orchestration] created_at: 2026-06-01T13:29:55Z updated_at: 2026-06-01T13:29:55Z assignee: null legacy_ticket: null

Background

When a user is attached to one running Pod in the TUI, there is currently no small command-mode affordance for making another Pod reachable/contactable from that session. Existing Pod discovery/restore mechanisms exist at other layers (ListPods/RestorePod, resume picker, multi-Pod dashboard), but the single-Pod TUI command surface only exposes local commands such as :help, :compact, and :rewind.

Add a : command that lets a user connect to another visible Pod from within the running TUI. The exact UX can be refined during implementation, but it should be command-mode based and should not make background notifications or transient socket state into durable authority.

Requirements

• Add a TUI command-mode entry point for connecting to another Pod, tentatively :pod <name> or :connect <pod-name>.
• The command should use the existing Pod visibility/attach/restore authority rather than inventing a separate registry.
• It should work from a single-Pod TUI session without requiring the user to exit to a dashboard.
• It should handle at least:
  • target Pod is live and attachable;
  • target Pod is stopped but restorable;
  • target Pod is not visible;
  • current Pod is busy/streaming and command execution would be unsafe.
• The current Pod's durable history must not be rewritten or polluted merely because the user connects to another Pod.
• The UX should make it clear whether the command switches the active TUI attachment, opens a temporary contact/send operation, or enters a small Pod picker. Choose one behavior and document the rationale.
• Avoid duplicating old tool names or semantics; prefer current ListPods / RestorePod-style state concepts.
• Add focused tests for command parsing/availability and any pure model logic. If runtime socket/TUI E2E is not feasible, record the manual validation path.

Non-goals

• Do not implement arbitrary Pod-to-Pod autonomous messaging unless explicitly designed.
• Do not replace the multi-Pod dashboard.
• Do not make child completion notifications authoritative.
• Do not add a new persistent relationship graph between Pods unless required by a later design.

Acceptance criteria

• A user can invoke a documented : command from a single-Pod TUI to connect to another visible Pod by name or through a small selection flow.
• The command uses existing Pod attach/restore/discovery mechanisms and preserves Pod/session authority boundaries.
• Failure modes produce clear actionbar/command diagnostics.
• Tests cover parser/availability/model behavior, and implementation notes record any manual validation required for live attach behavior.
• Documentation/help text for TUI commands is updated.
• Validation includes relevant TUI/client tests, ./tickets.sh doctor, git diff --check, and nix build .#yoi unless explicitly deferred with rationale.