yoi/.yoi/tickets/closed/20260601-132955-tui-peer-pod-handshake-command/item.md

id	slug	title	status	kind	priority	labels	created_at	updated_at	assignee
20260601-132955-tui-peer-pod-handshake-command	tui-peer-pod-handshake-command	TUI: add peer Pod handshake and messaging command	closed	task	P2	tui pod command orchestration	2026-06-01T13:29:55Z	2026-06-02T13:54:50Z	null

Background

When a user is attached to one running Pod, there is currently no user-facing way to introduce that Pod to another existing Pod as a peer. Existing visibility is mostly self/spawned-child/current-state based, so the current Pod's ListPods tool does not represent arbitrary peer Pods and SendToPod is effectively limited to previously spawned children.

The desired : command is not a TUI attach/switch command. It should initiate a Pod-authoritative peer handshake so the currently attached Pod and a target Pod can become mutually visible and can exchange messages through the existing Pod tooling surface or a new explicitly peer-safe messaging surface.

This relationship must be separate from spawned-child delegation. A peer handshake should not imply filesystem scope delegation, parent ownership, child completion notifications, or child output cursor authority.

Requirements

• Add a TUI command-mode entry point for initiating a peer Pod handshake, tentatively :peer <name>, :know-pod <name>, :link-pod <name>, or similar.
• The command should send an explicit Pod/runtime method to the currently attached Pod; it must not be a TUI-only local list mutation.
• Add protocol/runtime support for registering peer visibility between two existing Pods.
• The relationship should be reciprocal by default: after a successful handshake, both Pods should be able to see each other through ListPods with a source/state label that identifies the relationship as peer/known, not spawned child.
• The durable effect should live in Pod current-state metadata or an equivalent Pod-authoritative visibility record so it survives reconnect/restore where appropriate.
• ListPods from either peer should include the other Pod after the handshake succeeds.
• Extend messaging semantics so a Pod can send a message to a visible live/restorable peer, not only to a spawned child. This may reuse SendToPod if its contract is broadened safely, or introduce a distinct peer-send tool/method if keeping spawned-child semantics separate is clearer.
• A peer message should be delivered as an explicit user-visible/control-plane message according to the chosen messaging semantics; it must not silently mutate hidden model context.
• Peer messaging must not grant delegated filesystem scope, output cursor authority, parent/child lifecycle authority, or completion-notification authority.
• The command should resolve the target by Pod name using existing Pod metadata/live registry visibility that is available to the controller/human, then perform a safe handshake with the target Pod.
• Handle at least:
  • target Pod is live and can accept the handshake;
  • target Pod is stopped but restorable;
  • target Pod name is unknown or ambiguous;
  • target Pod rejects or cannot persist the reciprocal relationship;
  • current TUI is not attached to a Pod;
  • current Pod is in a state where the handshake method cannot be safely delivered.
• Define whether a one-sided fallback is allowed when reciprocal registration fails. If allowed, it must be clearly labeled and must not imply mutual messaging.
• The current Pod's model conversation history must not be polluted merely because the user registers a peer. The handshake is Pod metadata/control state, not a user message to the model.
• Message delivery, however, must be recorded through the normal history/event path appropriate for delivered messages so later turns can explain why the receiver saw the message.
• Provide clear command diagnostics/actionbar feedback.
• Add focused tests for command parsing, protocol/runtime method handling, metadata persistence/restore, reciprocal ListPods visibility behavior, and peer messaging authorization/delivery. If full live TUI/socket E2E is not feasible, document the manual validation path.

Non-goals

• Do not implement arbitrary autonomous Pod-to-Pod scheduling or background chatter.
• Do not switch the TUI's active attachment as the primary behavior of this command.
• Do not replace the multi-Pod dashboard or Pod picker.
• Do not treat registered peer Pods as spawned children.
• Do not make child completion notifications authoritative.
• Do not add delegated scope or reclaim behavior for peer Pods unless a later design explicitly requires it.
• Do not add a broad social graph or arbitrary persistent relationship model beyond the minimal peer visibility/messaging relationship needed here.

Acceptance criteria

• A user can invoke a documented : command from a single-Pod TUI to handshake the current Pod with another existing Pod.
• After successful handshake, each Pod's ListPods tool output includes the other Pod with a state/source label that does not misrepresent it as a spawned child.
• A Pod can send a message to the registered peer through the chosen tool/method, and the receiver records the delivered message through the appropriate durable path.
• RestorePod or other visibility-scoped Pod tools can operate on registered peers according to the existing state-aware rules.
• The peer relationship is persisted in Pod-authoritative current state and survives ordinary TUI reconnect/Pod restore where both Pods remain visible/restorable.
• Failure modes produce clear diagnostics and do not modify history or create partial misleading visibility records.
• Tests cover parser/model/runtime visibility and peer messaging behavior, and implementation notes record any manual validation required for live TUI behavior.
• Documentation/help text for TUI commands, Pod visibility semantics, and peer messaging semantics is updated.
• Validation includes relevant TUI/client/protocol/pod-store/pod tests, ./tickets.sh doctor, git diff --check, and nix build .#yoi unless explicitly deferred with rationale.