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

9.9 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.

Implementation report

Implementation report: peer Pod handshake command

Date: 2026-06-02

Investigation

The current boundaries are documented in artifacts/investigation-summary.md. No escalation blocker was found. The main concern identified was avoiding reuse of spawned-child state (SpawnedPodRegistry, delegated scope, output cursors, and child completion semantics) for peer communication; the implementation therefore adds separate peer metadata and a separate peer send tool.

Implemented behavior

  • Added reciprocal peer metadata to PodMetadata as peers, separate from spawned_children and reclaimed_children.
  • Added protocol Method::RegisterPeer { name } and Event::PeerRegistered { result }.
  • Added controller handling for RegisterPeer, idle/paused only, validating an existing target Pod and rejecting self-handshakes.
  • Added PodDiscovery::register_peer that persists both metadata directions and rolls back the first side on ordinary second-side write failure.
  • Extended ListPods visibility to include VisibilityReason::Peer; a successful handshake makes both Pods see each other as peer through Pod metadata.
  • Added SendToPeerPod as a distinct LLM tool. It only sends to visible live peer Pods, delivers Method::Notify with a source label, and does not use child delegation, output cursors, parent ownership, or child completion notifications.
  • Added TUI command :peer <pod-name> for idle attached Pods. Success is reported through a transient actionbar notice when the controller returns PeerRegistered.
  • Documented peer semantics in docs/design/pod-session-state.md and added prompt guidance that peer Pods are not spawned children.

Tests and validation run

  • cargo test -p protocol -p pod-store -p pod -p tui --lib
  • ./tickets.sh doctor
  • git diff --check
  • nix build .#yoi

Notes

The two-file reciprocal metadata update is not crash-transactional because the existing Pod metadata store has no multi-record transaction boundary. The implementation avoids successful replies with one-sided state for normal validation/write failures by rolling back the first write if the reciprocal write fails.

Implementation report

Implementation report: peer Pod handshake command

Date: 2026-06-02

Investigation

The current boundaries are documented in artifacts/investigation-summary.md. No escalation blocker was found. The main concern identified was avoiding reuse of spawned-child state (SpawnedPodRegistry, delegated scope, output cursors, and child completion semantics) for peer communication; the implementation therefore adds separate peer metadata and a separate peer send tool.

Implemented behavior

  • Added reciprocal peer metadata to PodMetadata as peers, separate from spawned_children and reclaimed_children.
  • Added protocol Method::RegisterPeer { name } and Event::PeerRegistered { result }.
  • Added controller handling for RegisterPeer, idle/paused only, validating an existing target Pod and rejecting self-handshakes.
  • Added PodDiscovery::register_peer that persists both metadata directions and restores the exact prior source-side peer state on ordinary second-side write failure.
  • Extended ListPods visibility to include VisibilityReason::Peer; a successful handshake makes both Pods see each other as peer through Pod metadata.
  • Added SendToPeerPod as a distinct LLM tool. It only sends to visible live peer Pods, delivers Method::Notify with a source label, and does not use child delegation, output cursors, parent ownership, or child completion notifications.
  • Added TUI command :peer <pod-name> for idle attached Pods. Success is reported through a transient actionbar notice when the controller returns PeerRegistered.
  • Documented peer semantics in docs/design/pod-session-state.md and added prompt guidance that peer Pods are not spawned children.

Reviewer blocker fixes

  • SendToPeerPod now reuses the existing one-shot Pod socket client path (connect_and_send), which drains connect-time Alert / Snapshot traffic before writing Notify and returns an error if method delivery fails.
  • Added a regression test where the target socket emits an alert and snapshot before reading the peer Notify, proving the peer send drains the prelude and still delivers the message.
  • Registration failure rollback now restores the exact prior source peer list instead of unconditionally removing source -> target; a target-side injected failure test verifies a pre-existing source relation is preserved.
  • Wording now describes :peer as metadata-level reciprocal registration rather than live target-controller consent, and documents that SendToPeerPod fails for non-live peers instead of auto-restoring them.

Tests and validation run

  • cargo test -p protocol -p pod-store -p pod -p tui --lib
  • ./tickets.sh doctor
  • git diff --check
  • nix build .#yoi

Notes

The two-file reciprocal metadata update is not crash-transactional because the existing Pod metadata store has no multi-record transaction boundary. The implementation avoids successful replies with one-sided state for normal validation/write failures by restoring the exact prior source-side peer list if the reciprocal write fails.