1# Remote resilience
2
3Remote attachments connect directly to the selected vev daemon. UDP is the
4normal carriage: SSH bootstraps an authenticated endpoint, then the attachment
5carries the vev protocol over UDP. Set `VEV_REMOTE_TRANSPORT=stdio` to use an
6SSH-only carriage explicitly when UDP is unavailable. vev must be installed on
7the remote host.
8
9The session remains shared across all attachments. It owns PTYs, VT state, tabs,
10panes, shared PTY content geometry, and ordered mutations. Each attachment keeps
11its own window size, selected tab and pane, copy mode, overlays, render/output
12acknowledgements, and reconnect state. Reconnecting one attachment resumes that
13attachment without replacing its peers or changing their attachment-local
14windows/views; its latest claim may still update shared PTY geometry.
15
16## Remote picker identity
17
18The session picker shows remote live, stopped, broken, stale, and unavailable
19rows using the same expandable session/tab shape as local rows. A row carries a
20lifecycle ID and stable tab selector separately from its display origin; labels
21are never parsed back into routes. Cached and stale rows remain navigable, but
22activation is gated until the host catalog and the exact lifecycle/tab identity
23are current. A successful picker handoff sends the structured target to the
24owning daemon without creating a local shadow session. Picker-selected remote
25attachments use the daemon's environment and persisted session working
26directory; direct CLI remote attaches retain their client-request semantics.
27
28Remote attachments remain direct: the selected remote daemon owns the session,
29PTYs, rendering, input, resize, effects, and teardown. The client does not
30proxy remote content through the local daemon. A single client process keeps a
31bounded, in-memory route history across local, direct remote, and picker-
32discovered attachments. The daemon renders the latest attachment snapshot;
33active routes are metadata-only, while `JRS` and `BSK` send typed key/generation
34actions back to the client. History is process-local and is not persisted or
35shared between clients.
36
37A picker-selected remote target is a direct handoff with one input pump. Exact
38lifecycle/name identities are carried separately from display labels, and a
39successful daemon-local switch publishes a new committed identity before the
40client republishes its snapshot. These navigation actions and the strict
41handshake layout use protocol v27. Attach handshakes may carry an exact target,
42and successful Welcomes can return the daemon's committed identity.
43
44## Durable record compatibility
45
46The catalogue record format is currently version 4 because records now retain
47stable tab identity metadata. Readers accept version 3 for one-way upgrades, but
48older binaries reject records written at version 4. Back up the vev state
49before a rollback; downgrading after an upgrade can leave newer catalogue
50records unreadable and may require recreating those sessions.
51
52Remote catalogues are bounded and versioned. Complete catalogues contain ordered
53tab IDs, names, state, active tab, attachment state, and MRU sequence. Stopped
54tab metadata is retained across daemon restart; legacy count-only catalogues are
55read-only compatibility rows and cannot provide exact tab identity.
56
57Remote picker previews are bounded styled-cell snapshots fetched without
58attachment or PTY mutation. They are held in a short-lived in-memory cache only;
59viewport contents are not persisted or written to diagnostics. Live preview
60requests use debounce, same-key single-flight, bounded concurrency, TTL
61stale-while-revalidate, and failure cooldowns. Stopped sessions show a static
62placeholder, and late or canceled preview responses are discarded when the
63picker selection changes.
64
65## Connection limits
66
67- A connection handshake has one 15-second deadline from connection start
68  through Hello, Welcome, and the initial committed publication. The deadline
69  applies to local and remote connections.
70- Each command request has a 10-second deadline for its result. A timeout
71  abandons only that request; it does not complete a later request with a stale
72  result.
73- Shared PTY content geometry follows the latest valid, non-superseded attach,
74  resume, or resize claim. A later attachment can therefore replace the current
75  shared geometry; if the winning attachment detaches, the most recently
76  claimed remaining valid attachment becomes authoritative.
77
78## UDP operation
79
80- The remote host selects a UDP port in `61000-61023` by default. Set
81  `VEV_UDP_PORT_RANGE` to a range, one port, or `0` for an ephemeral port.
82- The UDP carriage authenticates and retransmits protocol frames, preserves
83  frame order, and reports bounded link-health state without logging payloads,
84  addresses, keys, or identities.
85- The attachment reconnects with its resume token after a path change. The
86  remote session and its PTYs remain in place while the attachment is offline.
87
88The raw UDP AEAD key is held only in memory during bootstrap and transport
89setup. It is not written to durable state. Key buffers are cleared on the
90reachable handoff paths on a best-effort basis; cipher implementations and
91other I/O owners may retain internal copies for their lifetime.
92
93## Connection states
94
95| State | Meaning |
96| --- | --- |
97| `connected` | Recent authenticated contact and complete frame progress. |
98| `degraded` | Authenticated packets arrive, but complete-frame or acknowledgement progress is delayed. |
99| `probing` | Authenticated contact is absent and the carriage is probing for a recovered path. |
100| `resuming` | This attachment is opening a replacement connection with its resume token. |
101| `offline` | The attachment is re-establishing the selected remote transport. |
102| `expired` | The session or attachment resume window is no longer available. |
103
104In raw terminal mode, state changes appear as vev status text rather than bytes
105written into the PTY's output stream.
106
107## Diagnostics and checks
108
109At debug level, transport-health logs contain only state, elapsed progress ages,
110and bounded counters. `scripts/debug-remote-attach.sh --udp-health user@host`
111collects redacted health lines and Linux `ss -u -m` socket-memory counters.
112
113Useful checks are:
114
115- block and unblock the configured UDP port range;
116- move between networks or change VPN state;
117- suspend and resume the attachment machine;
118- reconnect to the same named session;
119- verify that a second attachment retains its independent view while the first
120  reconnects.
121
122Keep hostnames, usernames, keys, and local paths out of shared logs and
123screenshots.