Skip to content

A person offers one of their laptop sessions to the plane, shared at offer time with the people they name; the laptop dials one connection the plane relays protocol messages over, both ends hold each message to one table and the laptop to its own record of the share, the plane keeps no copy, and a withdrawal or a drop ends every remote view at once

Decision 921 · accepted · 2026-10-18 · issue #58

Superseded in part

In part by 952.

58, slice 1. The maintainer decided on 2026-10-18 that the first slice is full steering: a

laptop's daemon offers a session to the plane, and its owner and the people they share it with can, from another device (the desktop app or the console), follow it, answer its approvals and questions, send prompts, cancel a turn and switch its agent.

One connection, dialled by the laptop

Nothing listens on the laptop. While at least one session is offered and a client has handed the daemon a plane token (Decision 764), Troupe.Gateway.Remote keeps one WebSocket open to the plane's GET /v1/relay, with that token in Authorization, renewed on the open socket (auth.refresh) each time a client links again with a fresh one. A link naming another person ends it; signing out or unlinking ends it and keeps the record. Over it the daemon says what it offers (relay.sync as it connects, then relay.offer and relay.withdraw), and the plane relays each remote person: relay.open names a viewer, the person and the role the plane holds them to, relay.frame carries one protocol message either way as a string, and relay.close ends one view. One connection per daemon rather than per session, because the limit that matters is the plane's sockets, and a laptop offering five sessions is one laptop.

The plane's half is Troupe.Plane.Remote.Laptop (the laptop's socket) and Troupe.Plane.Remote.Viewer (GET /v1/relay/session, a person's). A laptop's connection holds a :global name per session it offers, so a viewer on any replica finds it, and a connection that dies takes its names with it: online is a live connection, not a column. A page is not a laptop: /v1/relay refuses any request that names an Origin.

Why not the control channel. It is the pods' internal port, enrolled with a projected ServiceAccount token, and its moduledoc and its tests promise it carries no session content. A laptop is on the internet, authenticated as a person, and what it carries is content. A second door on the public surface, with its own two sockets, keeps both promises.

Why not a dedicated relay app. The open question in #58. A relay inside the plane reuses its token verification, its person rows and its clustering, and the seam the two sockets give is narrow enough to move into its own app later without a client noticing: clients only ever see remote.open's endpoint.

Each remote person is a connection like any other

The daemon makes each viewer the plane opens into a Troupe.Gateway.Connection on a new :relay endpoint kind (Troupe.Protocol.Endpoint.relay/2), whose frames Troupe.Gateway.Remote.Viewer owns, the same two-process shape as the loopback WebSocket. So a remote prompt goes through the same dispatcher, the same session and the same rules as one typed at the laptop: the enforced layer, the per-tool rules (Decision 907) and the approvals apply inside the session whichever connection sent the input, and nothing about the connection can widen them. Its principal is the person the plane named, with via: "plane", and initialize says capabilities.relayed. Every steering command writes its author: an input, an answer, a switch, and now a cancel, whose cancelled event carried the system as its actor before and carries who asked, local or remote, from this change.

Who may steer, and checked at both ends

A share made at offer time, not the plane's existing sharing. remote.offer names people by subject or email, each observe (follow) or control (steer); the plane resolves them to people it knows and refuses one it does not by name, so a share never silently reaches fewer people than were named. The owner, the person linked when it was offered, may always steer it, from any of their devices. The plane's session.grant and share links are for the plane's own rows, a pod session's ACL and a capability over it; folding a laptop's offer into them would let a plane-side grant reach a laptop that never made it.

One table, two checks. Troupe.Protocol.Relay lists what a relayed connection may ask, with the scope each needs, in the protocol app, because the plane may not call the daemon's code and the daemon may not call the plane's. The plane checks each request from a viewer against it, at the role the offer holds them to, before relaying it, and again asks the row and the account before each steering command, so a share taken back or a deactivated person stops at their next command. The daemon checks it again in the connection's guard, at the narrower of the plane's role and its own record (<state>/remote.json): a person the plane relays whom the laptop never named is closed before a word reaches the session, and a plane that said control for somebody shared to observe gets them observe.

What the table is. The session's own reading (subscribe on its topics, session.get, a listing narrowed to it, blob.get, agents.list of the session, commands.list, presence.set, the goal and loop reads) and its steering (input.send, commands.run, turn.cancel, profile.switch, approval.respond, question.answer, todo.edit). A request naming another session, fleet, or a path's agents is refused. Nothing of the laptop: no fs.* (editing files remotely is #61), no shell.* (a person's own commands, Decision 813), no tools.* (the laptop's person's tools stay theirs, and a remote person's machine offers none here), and no setting, server, workspace or identity of the laptop.

A remote person cannot loosen the laptop's rules. An approval answered from another device is allow or deny, for that one call; allow_session, which would stop the session asking for that tool for the rest of it, is refused over the relay and is the laptop person's to give at the laptop. Switching the agent is among the session's own agents, the laptop's files, and the stricter rule still holds where they differ (Decision 907).

Offline, withdrawn, and the record

Withdrawn at once. remote.withdraw closes every remote view of the session on the daemon before the plane is told, so a plane that did not hear still relays nothing more; the plane, told, ends its views with relay.closed. Erasing a session withdraws it.

Offline honestly. A dropped connection ends every view on both ends, the plane records offline_since on the offer's row, remote.list says offline with it, and remote.open is unavailable with offline_since. Nothing is queued: a viewer's message has nowhere to go and is not kept. The daemon dials again, backing off from a second to a minute, and on connecting sends relay.sync with exactly what its record still offers of the linked person's; the plane keeps those and drops every other row of that person's from that device, so a session withdrawn while the laptop was away is not offered again, and one still offered is. The device is a random id the daemon keeps beside the record.

The plane keeps no copy. The row is who offered which session from which device, to whom, and since when the laptop has been away, with the workspace's last name as a label; nothing a session says. The plane relays each message and keeps none, no transcript copy: a copy would be a second store of a laptop's content that the laptop's person cannot see, erase or seal under their own key, and a private session exists precisely for the person who wants their content off the laptop. A viewer replays from the laptop's log, which is the session.

A private session is never offered. It is sealed under its person's key, its row is the plane's on other terms (Decision 785), and steering it from another device is claiming it there (session.claim). The daemon refuses the offer with that sentence.

A token never reaches the laptop. A viewer attaches with the token remote.open mints: for one session, at one role, with the relay's own audience (troupe-relay), so it opens no pod and no /rpc; at most fifteen minutes, renewed with remote.open again and auth.refresh on the open socket, which the plane answers itself. The plane takes auth out of a viewer's initialize before relaying it.

Governs: apps/troupe_protocol/lib/troupe/protocol/relay.ex, apps/troupe_gateway/lib/troupe/gateway/remote.ex, apps/troupe_gateway/lib/troupe/gateway/remote/viewer.ex, apps/troupe_gateway/lib/troupe/gateway/plane.ex, apps/troupe_plane/lib/troupe/plane/remote.ex, apps/troupe_plane/lib/troupe/plane/remote/*.ex