Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity
b51c32401c
yoi/work-items/open/20260601-132955-tui-peer-pod-handshake-command/thread.md

4.5 KiB
Raw Blame History

Created

Created by tickets.sh create.

Decision

Clarification

The requested command is not a TUI attach/switch affordance. It should make another existing Pod known to the currently attached Pod so that the current Pod's ListPods tool can see it.

The implementation should therefore focus on Pod-authoritative visibility metadata and ListPods semantics, with the TUI : command only acting as the human-facing control path that registers that relationship.

Decision

Clarification

The requested command is not a TUI attach/switch affordance. It should initiate a Pod-authoritative peer handshake between the currently attached Pod and another existing Pod.

The intended result is broader than one-sided ListPods visibility: after a successful handshake, both Pods should be mutually visible as peers and should be able to exchange messages through an explicit peer-safe tool/method. The relationship must stay distinct from spawned-child delegation: no delegated filesystem scope, no parent/child ownership, no child completion notifications, and no child output cursor authority.

The TUI : command is the human-facing control path for initiating the handshake; the durable relationship and messaging authorization belong in Pod metadata/runtime semantics, not in TUI-local state.

Plan

Delegation intent: peer Pod handshake and messaging

Intent:

  • Investigate the existing Pod visibility/messaging implementation, then implement a TUI-initiated peer Pod handshake and peer messaging path if no design blockers are found.

Requirements:

  • Start with investigation. Map current authority boundaries for ListPods, RestorePod, SendToPod, Pod metadata, spawned-child registry, protocol methods, and TUI : command handling.
  • If there are design blockers or ambiguous authority decisions, write findings to the ticket artifacts and stop for parent decision.
  • If there are no blockers, proceed with implementation in the worktree.
  • Add a TUI : command that initiates peer handshake from the currently attached Pod to a target Pod by name.
  • Make the peer relationship Pod-authoritative, durable where appropriate, and reciprocal by default.
  • Ensure both Pods see each other in ListPods as peer/known, not spawned child.
  • Add or safely broaden messaging semantics so a Pod can message a visible peer without granting spawned-child powers.
  • Record delivered peer messages through an explainable durable path; do not silently mutate hidden context.
  • Preserve explicit boundaries: no delegated filesystem scope, parent/child ownership, completion notification authority, or child output cursor authority for peer Pods.
  • Add focused tests for protocol/runtime behavior, metadata persistence/restore, reciprocal ListPods, peer message authorization/delivery, and TUI command parsing/help where feasible.
  • Update docs/help text for the new command and peer semantics.

Invariants:

  • Do not treat peer Pods as spawned children.
  • Do not reintroduce hidden context injection; model-affecting delivered messages must go through the normal committed history/event path.
  • Do not add broad relationship graph semantics beyond the minimal peer relation.
  • Do not edit the parent workspace; work only in the delegated worktree.
  • Do not read ignored secret-like file contents.
  • Do not close the ticket, merge the branch, delete worktrees, or push.

Non-goals:

  • Arbitrary autonomous Pod-to-Pod background chatter.
  • Replacing the multi-Pod dashboard or Pod picker.
  • Delegated scope sharing between peers.
  • E2E test framework design for real spawned processes.

Escalate if:

  • Reciprocal handshake cannot be made atomic enough to avoid misleading partial state.
  • Peer messaging requires changing history semantics in a way that could violate context/history invariants.
  • Existing protocol or metadata schemas need a broad migration.
  • The TUI command cannot safely deliver the runtime method while preserving current Pod authority.
  • SendToPod broadening would confuse spawned-child and peer semantics.

Validation:

  • Before implementation: write a short investigation summary in the implementation report or a separate artifact.
  • Focused tests for touched crates.
  • ./tickets.sh doctor and git diff --check.
  • nix build .#yoi if feasible; record if skipped and why.
  • Commit the implementation in the worktree when reviewable.