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 `BCK` 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 use the strict,
41exact-match protocol version. Attach handshakes may carry an exact target, and
42successful Welcomes can return the daemon's committed identity.
43
44## Durable record compatibility
45
46Catalogue record format version 5 stores the protocol version alongside stable
47tab identity metadata. At daemon startup, version 3 and 4 records and version 5
48records written by another protocol are decoded only to retain their session
49names; all other session state is reset before socket publication. Compatible
50version 5 records restore normally. Older binaries reject version 5 records, so
51a downgrade also resets sessions when the older binary can read the catalogue,
52or fails closed when it cannot. Back up the vev state before a rollback.
53
54Remote catalogues are bounded and versioned. Complete catalogues contain ordered
55tab IDs, names, state, active tab, attachment state, and MRU sequence. Stopped
56tab metadata is retained across daemon restart; legacy count-only catalogues are
57read-only compatibility rows and cannot provide exact tab identity.
58
59Remote picker previews are bounded styled-cell snapshots fetched without
60attachment or PTY mutation. They are held in a short-lived in-memory cache only;
61viewport contents are not persisted or written to diagnostics. Live preview
62requests use debounce, same-key single-flight, bounded concurrency, TTL
63stale-while-revalidate, and failure cooldowns. Stopped sessions show a static
64placeholder, and late or canceled preview responses are discarded when the
65picker selection changes.
66
67## Connection limits
68
69- A connection handshake has one 15-second deadline from connection start
70  through Hello, Welcome, and the initial committed publication. The deadline
71  applies to local and remote connections.
72- Each command request has a 10-second deadline for its result. A timeout
73  abandons only that request; it does not complete a later request with a stale
74  result.
75- Shared PTY content geometry follows the latest valid, non-superseded attach,
76  resume, or resize claim. A later attachment can therefore replace the current
77  shared geometry; if the winning attachment detaches, the most recently
78  claimed remaining valid attachment becomes authoritative.
79
80## UDP operation
81
82- The remote host selects a UDP port in `61000-61023` by default. Set
83  `VEV_UDP_PORT_RANGE` to a range, one port, or `0` for an ephemeral port.
84- The UDP carriage authenticates and retransmits protocol frames, preserves
85  frame order, and reports bounded link-health state without logging payloads,
86  addresses, keys, or identities.
87- The attachment reconnects with its resume token after a path change. The
88  remote session and its PTYs remain in place while the attachment is offline.
89
90The raw UDP AEAD key is held only in memory during bootstrap and transport
91setup. It is not written to durable state. Key buffers are cleared on the
92reachable handoff paths on a best-effort basis; cipher implementations and
93other I/O owners may retain internal copies for their lifetime.
94
95## Connection states
96
97| State | Meaning |
98| --- | --- |
99| `connected` | Recent authenticated contact and complete frame progress. |
100| `degraded` | Authenticated packets arrive, but complete-frame or acknowledgement progress is delayed. |
101| `probing` | Authenticated contact is absent and the carriage is probing for a recovered path. |
102| `resuming` | This attachment is opening a replacement connection with its resume token. |
103| `offline` | The attachment is re-establishing the selected remote transport. |
104| `expired` | The session or attachment resume window is no longer available. |
105
106In raw terminal mode, state changes appear as vev status text rather than bytes
107written into the PTY's output stream.
108
109## Diagnostics and checks
110
111At debug level, transport-health logs contain only state, elapsed progress ages,
112and bounded counters. `scripts/debug-remote-attach.sh --udp-health user@host`
113collects redacted health lines and Linux `ss -u -m` socket-memory counters.
114
115Useful checks are:
116
117- block and unblock the configured UDP port range;
118- move between networks or change VPN state;
119- suspend and resume the attachment machine;
120- reconnect to the same named session;
121- verify that a second attachment retains its independent view while the first
122  reconnects.
123
124Keep hostnames, usernames, keys, and local paths out of shared logs and
125screenshots.