Skip to main content

Module: share

Put another person inside this workspace.

The app can already put two people on the same pane — that is the collab channel: one document, rev-checked last-writer-wins, addressed to a person through the roster. What it could not do is put two people in the same session, and it could not show anything at all to somebody who has never installed it.

share is both, because they serve different people. A friend on the fabric gets the high-fidelity, interactive thing. A stranger with a link gets a video stream and a chat box with no setup at all. One module, two egress paths off one origin.

Status: Phases 1-6 implemented (Phase 6 partially — see below) — the session, the permission model, the semantic mirror, the pixel stream between friends, and the public link. A host opens a session, invites friends by person, moves each guest along a grant ladder that every guest action is checked against, and a guest sees a live redacted map of the host's workspace and — when the host starts a capture — their actual screen. Anyone else can be handed a URL that plays in a plain browser with no install and no account, served by the share relay. Guest actions are wired to real capabilities through two gates, and everything a guest does — or was refused — is written down where the host can read it.

Contributions to the layout shell​

  • Panels: share.session (role tool, singleton) — the host's control surface. It is a permission surface, not a video one; see why that ordering. share.mirror (role document, singleton) — the guest's window onto the host's workspace.
  • Commands: share.open, share.openMirror, share.start, share.stop, share.stopScreen, share.revokeAll ("Share: Drop every guest to view-only" — phrased as what it does, because somebody reaching for it in the palette is in a hurry).
  • Keybindings: none. Nothing here should be one keystroke away.
  • Shell indicator: share.live — "you are broadcasting", drawn in the shell chrome while the pane is closed. See knowing you are live.
  • Neither share pane declares share, so neither ever appears in a projection. A guest looking at the host's own grant controls would be the module leaking itself.

The grant ladder​

Friendship grants reachability, not authority — the same rule agent.ask_peer already enforces. Being trusted enough to reach this node says nothing about what you may do inside a session on it, so every guest action passes gate.require before it touches anything.

view → cursor → edit → terminal → agent → control
RungWhat it buys
viewSee shared panes. Change nothing. The rung every guest joins at.
cursorAlso show their pointer and selection.
editEdit panes that support collaborative editing.
terminalRun commands — subject to your own agent permission rules.
agentDrive your agent — subject to your own agent permission rules.
controlFull control. Grant only to someone you would hand the keyboard.

A participant sits at exactly one rung, and a rung answers every capability question below it. A ladder rather than a grid of independent flags on purpose: the interesting failure here is granting terminal to somebody you meant to give edit, and an ordered ladder makes "more than I meant" visible at a glance instead of hiding it in a checkbox matrix.

Three rules that are bugs if forgotten:

  • An unknown rung reads as the weakest. A peer on a newer build can name a rung this one has never heard of, and the safe reading of "something I do not understand" is view, never control.
  • terminal and agent carry no permission logic of their own. They hand off to backend/modules/agent/permissions.py, so a guest can never exceed what the host's own agent rules allow. One gate, not two — a second, laxer implementation of "may this run?" is exactly where the gap appears.
  • A public-URL viewer holds no rung at all. Relay viewers are not participants and never enter a session's roster, so there is nothing for require() to be reached on their behalf with. Interactivity requires an authenticated person on the fabric.

share.revoke_all drops every guest back to view in one move without ending the session: the panic button should not dump anybody out mid-sentence, it should just mean nothing anyone holds can still act.

The agent can take rights away, never hand them out​

share.grant is deliberately not an agent tool, while share.revoke_all is. Raising a guest to terminal is a decision about how much of your machine somebody else gets, and a model that can make it from a sentence is a model that can be talked into making it. The asymmetry is the design.

The semantic mirror​

A guest sees a map of the host's workspace, not a copy of it, and that distinction is load-bearing. A pane component renders local data, so seeding the host's FrameState into a guest's dashboard would open that guest's own editor and their own terminal, arranged like the host's — a layout copy wearing a mirror's clothes, and a dangerous thing to put in front of somebody who has been told they are looking at another person's screen. So each tile states exactly what is known: which pane is there, whether it is shared, and whether the host is looking at it. Content arrives per pane type — a collab pane already has a protocol for it, and the video stream drops into this same pane next phase.

Deny by default​

A pane is shared only if it declares share in its manifest (PaneShareDecl):

modeGuest sees
(absent — the default)A redacted tile. The pane exists and takes up this much room. That is all.
collabLive and editable through the pane's existing collab room.
mirrorLive, read-only, structured.
pixelsVisible only in the video stream.

Declared so far: scratch.note (collab — it already had a room, so a guest gets real editable content for free), plus editor.buffer, terminal.instance and agent.chat (mirror). Everything else — settings, connectors, the database console, and every pane written next year that forgets to declare — is redacted with no further work.

params are a second allowlist: declaring a pane shareable does not declare its params shareable, because params are routinely where the sensitive part lives (a file path, a URL, a row id). A pane gets no params at all unless it names keys.

Where redaction happens, and why there​

In the host's own browser, before anything reaches the wire. That is the only place it can be:

  • The backend cannot do it. Pane declarations live in the frontend registry, so the server has no idea what editor.buffer is or whether it may be shared. It holds the projection opaquely and never reinterprets it — a backend that reached in to help would be a second authority on a decision that already has one.
  • The guest's browser must not do it. That is the untrusted end, and asking it to hide things is asking the wrong machine.

So an undeclared pane is not merely unrendered by the guest: its view id, its params and its instance title never leave the host.

One trap worth stating, because it was a real bug the tests caught: a pane's instance id encodes its view id (editor.buffer#3). Dropping the viewId field while forwarding the id leaves the view id in the payload anyway, in the one field that looks like plumbing. Redacted panes therefore carry a hashed stand-in, and focusedInstanceId and activeTool are mapped through the same table — the host is often looking at a pane the guest cannot see.

What a redacted tile may say​

The module's manifest title — "Editor", "Settings" — never the instance title. A manifest title comes from the registry and so can never be a filename, a URL or a row id; an instance title very much can. The layout stays legible without the title leaking anything, and the guest is told the count outright ("3 hidden") rather than left to wonder about unexplained gaps.

Split geometry is preserved exactly, so "the pane on the left" means the same thing to both people.

The projection is still shaped as windows (MirrorFrame.windows[], each with a pixel rect), although the host has a docked workbench. That is what guests on every build since this module shipped know how to draw, and a group with a rect is a window with no chrome: mirror.ts lays the host's frame out with the same computeWorkbench the host draws with, and each group on screen becomes one window at the rect it occupies. A background tab is in its window's tab list; a group in a hidden dock is sent minimized. Changing the wire shape would blank the mirror for every older guest. The backdrop is dropped (a backdrop ref can carry a wallpaper path), and so is presentedInstanceId, which is not serialized anywhere else either.

Traffic​

The host publishes on layout change, and two things keep that sane — both comparing the projection, never the frame:

  • Nothing is sent when the redacted view is unchanged. The common case — the host typing inside a pane, or working entirely in panes the guest cannot see — produces no traffic at all.
  • Changes coalesce to at most one send per 400ms, leading edge plus a trailing one. A purely trailing throttle makes every change feel late; a purely leading one drops the final position of a drag, which is the one that matters.

The host is told what they are exposing: the session pane shows "1/4 panes visible", counted by the host's own browser and sent alongside the projection. A redaction model nobody can audit from the outside is a redaction model nobody trusts — and it is also the check the pixel phase needs before it can start a stream. The count is counted by the sender, never derived on the server: the backend holds the projection opaquely, and a server that walks its tree to count panes is one refactor from a server that filters them.

Publishing is bound to the session, not to a pane: a host who never opens the share pane is still hosting. A joining guest is handed the stored projection immediately and the host republishes on their arrival, so the first thing they see is current rather than however stale the last layout change left it.

Starting a share​

Share screen is one click from an empty pane: it opens the picker and the session together. It used to be three steps — start a session (which asked for a title before anything visible had happened), share, then mint a link. Nothing about the permission model moved: everyone still joins at view, and a public link is still its own deliberate step. Session only remains, for sharing the workspace layout with no video.

The order inside is load-bearing: the capture is taken before the session is opened, with no await in front of it. getDisplayMedia needs the click's transient user activation, and the /ws round trip that opens a session can outlast it — which surfaces as NotAllowedError, indistinguishable from a dismissed picker, so nothing would say why. startSessionAndWait then resolves on the node's state broadcast (or rejects on its error, or after 8s of silence), and a session that fails to open releases the capture rather than leaving the browser's sharing bar up over nothing.

While live, the pane shows a muted preview of what viewers see. The native picker shows the choice once; after that, which window is going out is otherwise only discoverable by somebody on the other end saying so.

Knowing you are live​

A share outlives the pane that started it, so "you are broadcasting" cannot live only in that pane. The module contributes a shell indicator (ModuleManifest.shellIndicators, see windowing) that the shell draws in the taskbar tray, and in the native titlebar too.

StateReadsStop button
Capture runningLIVE · 1 guest · 3 via linkyes
Link minted, no captureLINK OPENno — it is exposure, not broadcast
Neithernothing at all—

The viewer count is the relay's own, and it is omitted when no capture is running rather than shown as a confident zero: the node only polls the relay while publishing. Clicking the indicator opens the Share pane.

The pixel stream​

The host's browser is the single media origin. getDisplayMedia() captures the dashboard once, and that one MediaStream is what every guest receives. The nodes carry SDP and ICE and nothing else.

Why the nodes never touch the media. Routing pixels through Python would mean a browser-to-node leg, a node-to-node leg and PyAV in the middle — two hops and a near-certain re-encode of a stream the browser has already encoded. The fabric is excellent at exactly one thing here: delivering a signed, authenticated, person-addressed message to a machine that is already trusted. So it carries the handshake, and share_signal stays the documented pass-through it was built as in Phase 1.

It is a mesh, not a broadcast: the host holds one RTCPeerConnection per guest and sends the same track down each. That is the right shape for the handful of people in a workspace session and the wrong shape for an audience — which is what the relay in Phase 4 is for, and why rtc.ts has no fan-out logic to grow into one.

Keeping the mesh up​

The host's offer goes out only once, so anything that loses it, or loses the connection it set up, has to be recoverable without anyone pressing anything:

  • The guest's connection does not belong to the mirror pane. watch.ts holds one ShareSubscriber per joined session and is started at boot by initShare. Inactive tabs unmount, and the pane is often opened after joining. When the subscriber lived in the pane, an offer that arrived while the pane was unmounted was lost, and the host's connection waited in have-local-offer forever. The pane now only renders whatever stream watch.ts has.
  • ready (guest → host) means "I hold no connection for you; offer me one". A guest sends it when it joins a session and when its connection fails, so a reload recovers in seconds. The host answers only nodes that are guests of the session, only while it is sharing, and at most once per 1.5s per guest. share_signal reaches the host from any trusted peer.
  • The host re-offers on its own, with a backoff of 1, 2, 4, 8 and 16s and then every 30s, when a connection failed, stays disconnected for more than 5s, or an offer goes unanswered for 15s. disconnected gets a grace period because it is often a blip, but it is not guaranteed to reach failed.
  • Every offer is a fresh RTCPeerConnection on both ends, tagged with an epoch that the answer and the ICE candidates repeat. Without the tag, an answer to a replaced offer could land on its successor and pair it with the wrong DTLS fingerprint: the connection looks negotiated but never carries a frame. The field is optional on the wire, and a frame without it matches whichever connection is current.

On the guest's screen, "showing video" means the first decoded frame (requestVideoFrameCallback or loadeddata), not ontrack, and the stage says it is waiting until then. Playback tries with sound first. If the browser refuses sound without a click, the video plays muted with a labelled Unmute button. If the browser refuses even muted playback, a Play button appears. This is the same pattern as the public viewer page. The logic is in playback.ts and is tested without a DOM.

The pre-flight check​

A video frame does not know what a pane is. The semantic mirror can withhold a pane because it forwards structure and can omit it; a capture forwards light, so every pane the host can see is in the stream whether or not it was declared.

So the guarantee changes shape between the two modes, and the pre-flight exists to say so before the capture starts rather than after. It lists the visible panes that never declared themselves shareable, by name, and blocks until the host either closes them or explicitly chooses to share anyway.

Two rules keep the warning trustworthy:

  • Any declaration counts, not only mode: 'pixels'. A pane declaring collab or mirror has already agreed to be seen; being in the video too tells a guest nothing new. Reading pixels as a stricter permission would flag every shared pane in the workspace and train the host to click through.
  • Only panes actually on screen are checked (visiblePanes). A background tab and a hidden dock are not in the light, and a warning with false positives is one people learn to dismiss.

This is a warning, not a boundary. redactFrame enforces; preflight explains. Saying otherwise would be the most dangerous thing this module could do.

Capture support is probed, then checked against the shell​

Display capture is feature-detected: capture.ts probes the exact API it is about to call rather than standing a desktop-shell check in for it. It works in a browser and in the desktop shell on every platform — Electron has no picker of its own, so the shell answers getDisplayMedia (setDisplayMediaRequestHandler in apps/desktop/src/sessions.ts) with the primary screen, plus system audio on Windows; macOS 15+ shows the system picker instead, and on Wayland the desktop portal's picker appears.

System audio is a bonus, never a requirement. The Windows loopback fails when another app (Voicemeeter, for example) holds the default output exclusively, and Chromium then rejects the whole capture with NotReadableError: Device in use. So startCapture retries once without audio on NotReadableError. Viewers still hear the mixer's Viewers bus.

The probe reports four states, the hardware module's rule: available, unavailable, insecure-context, or unsupported-shell. The insecure-context state is real and distinct — a page served over plain HTTP off localhost has no mediaDevices at all, and reporting that as "your browser cannot do this" blames the browser for an origin problem.

unsupported-shell exists because feature detection has exactly one blind spot, and the old Tauri shell's macOS build sat in it. WKWebView exposed getDisplayMedia and then rejected it with NotAllowedError — the same error, indistinguishable, that the host produces by dismissing the picker. So the API detects as present, the call fails, and startStream stays silent because it is right to read that error as a cancel: click Share screen, nothing happens, no message anywhere. Nothing observable from the page separates the two, so the shell asserts it instead — a shell that cannot capture withholds the media.displayCapture capability (desktopCapabilities()), and the probe checks it before believing the API. Every platform grants it today; moving that check after the feature detection would silently restore the bug the day one does not.

Every state carries a sentence, and the pane renders it as visible text, not just the button's title: a tooltip never appears on a touch device, is never read aloud, and cannot be seen at all on the disabled button most people look at.

A dismissed picker is likewise not an error: CaptureError.cancelled tells a deliberate cancel apart from a real refusal, so the UI stays quiet about the first and loud about the second.

What the viewers hear​

A Viewers bus in the audio mixer, whose output is a MediaStreamDestination instead of a device. "What the viewers hear" is then an ordinary column in the matrix: karaoke to the viewers but not to your headphones, or your microphone to both, are one checkbox each — which is precisely the VoiceMeeter-shaped problem the audio module exists to solve.

It starts with nothing routed to it, the same rule addBus follows and for a stronger reason: this output is another person's ears, and defaulting it to carry whatever the host is playing would make starting a screen share silently broadcast their music and their notifications. The share pane says so, so silence reads as a choice rather than a bug.

The bus deliberately has no <audio> element — this is what other people hear, and playing it locally too would double every sound the host is already listening to and echo their own microphone back at them.

getDisplayMedia({audio:true}) is requested as well, but never required: it yields tab or system audio on Chromium and nothing at all elsewhere, so treating it as mandatory would break capture entirely on Firefox and Safari. The mixer bus is the portable path; the capture's own track is a bonus when the engine offers one.

Two different silences​

ensureShareBus awaits ensureLoaded() rather than assuming the mixer document is there. Sharing a screen can be the first thing in a session to want a bus, and nothing on that path mounts the mixer pane; returning early on an unloaded document left the bus uncreated, so the stream went out with no audio path at all while the pane told the host to route a strip into a bus that did not exist.

That makes the two silences distinguishable, which is the point:

What happenedWhat the pane says
The bus exists, nothing is routed to it"Guests hear nothing. Route a strip to the Viewers bus…"
The mixer never came up, so there is no busaudioFault — "no Viewers bus to carry sound", video only

Whether audio is flowing is read from the routing document (busHasSource), never from the outgoing track count: a MediaStreamAudioDestinationNode always carries exactly one audio track, silent or not, so counting tracks reports every share as "screen + audio" the moment the bus exists — a stream claiming to send sound it is not sending. A muted strip still counts as routed; it is one click from audible and the mixer already shows it as muted. The chip follows the matrix live, because routing a strip is exactly what a host does after reading the hint.

Stopping​

The capture can end from four places — the pane's Stop button, the browser's own "Stop sharing" bar, the session ending in another tab, or the agent. stream.ts owns all of them, because the failure worth preventing is a stream that is partly stopped: a capture released while a peer connection still claims to be live leaves the UI confident about a picture nobody is receiving.

A guest whose host stops gets an explicit bye frame rather than a dropped connection, so the pane can say "they stopped sharing" instead of leaving a frozen frame that looks like a broken network. Re-offering after a failure never sends bye, because in that case the share is still live and the picture is on its way back.

Backend surface​

backend/modules/share/, mounted at /api/share.

RoutePurpose
GET /api/shareEverything this node knows: what it hosts, what it has joined, live invitations
POST /api/share/sessionOpen a session (retitles rather than orphaning guests if one is live)
DELETE /api/share/sessionClose it, telling every guest
GET /api/share/inviteesFriends who could join right now
POST /api/share/inviteInvite one person — every online machine of theirs
POST /api/share/grantMove a person to a rung
POST /api/share/revoke-allEveryone back to view
POST /api/share/join · /leaveThe guest side

The session is process-global on the host node (session.py), the same shape as karaoke's and hassault's: the server owns intent and every client is a renderer. Every mutation bumps a revision and rebroadcasts the whole state, so a second tab, a phone on the LAN and the agent with no pane open all see the same thing without any of them owning it — and a client drops an out-of-order broadcast instead of showing a participant list that jumps backwards.

A node hosts at most one session. That is a limit, not a stub: a session mirrors this node's workspace, and there is only one of those — a second concurrent session would be the same thing with a different guest list, which is a grant list, not a session. The guest side is plural: this node may have joined several sessions hosted elsewhere.

The /ws share channel​

DirectionEventData
instate{} — pull the snapshot
instart / stop{title, mode} / {}
ininvite{personId}
ingrant / revoke_all / kick{personId, grant} / {} / {nodeId}
injoin / leave / dismiss_invite{sessionId, hostNode}
inmirror{frame} — the redacted projection, passed through untouched
outremote_mirror{sessionId, frame} — a host's projection, for the mirror pane
in · outsignal{to, payload} — SDP/ICE, passed through untouched
outstate · session · endedthe whole session, revision-stamped
outinvite · joined · left · remote_sessionthe guest side
outactiona guest did something inside their rung — the audit trail
outerror{message}

Inbound mutations are dispatched with create_task rather than awaited: each one dials or messages a peer, and a handler that blocks the receive loop would stall every other channel on the same socket.

share/signal, share/mirror and share/remote_mirror are excluded from the observability recorder (_SKIP_WS_EVENTS in telemetry/instrument.py). The signal frame is a WebRTC SDP blob relayed verbatim between two browsers — kilobytes of codec lines this node never interprets — and the mirror is a few KB of structure republished on every layout change. The rest of the share channel is small and genuinely useful in the panel, which is why the existing channel-level skip would have been the wrong instrument.

The peer wire​

backend/modules/share/fabric.py declares its own message types (share_invite, share_join, share_leave, share_state, share_end, share_action, share_signal, share_mirror, share_error) rather than adding them to network/protocol.py — the training-ads and hassault precedent: a module owns its own vocabulary and registers handlers for it, so adding a feature never edits the fabric core.

Every inbound handler gates on session.info.trusted first. Note what that is not enough for: knowing a session id is not membership, so a trusted friend presenting the wrong id gets the same answer as a stranger — no such session, with nothing confirmed about its shape.

Invitations are addressed to a person and fan out to every machine of theirs that is online; you invite a human and they pick a box. An invite to an offline machine is held by the sender (_pending) rather than lost — peer_hub.send_to is a direct send with no relay in the path, so an offline friend does not mean a queued invite somewhere, it means nothing was sent and nobody would ever find out. It is deliberately not persisted: it expires with INVITE_TTL (300s), and a session does not outlive the process hosting it.

Names are labels; the node id is the identity. A joined session's RemoteSession.host_name is what the share pane, the mirror header and anything reading share_manager.joined shows, so it must be a name. _host_display_name resolves it once, at join, most trustworthy first: the display_name this node's own roster keeps for the person that machine belongs to (the only answer that is not the remote side's claim); the invite that brought you in; the host participant's name in the join reply; and only then a short node id. It used to be the reply's host_person — an opaque person id, found with two real nodes friended over the fabric, where the guest saw gdnekr7j7kqovny4 where a friend's name belonged. host_node stays the authenticated key everything is looked up by.

A departing peer is swept out of the participant list by _on_peer_event. A guest has no browser socket on this node, so nothing else would ever notice they left — without the sweep they sit in the list forever, holding whatever rung they had.

share is advertised in hub.capabilities(), so a friend's UI offers only people whose machine could actually accept. A friend on an older build is listed but not offerable, rather than absent and unexplained.

Why the pane is a permission surface​

The obvious first version of this module is a video tile. It is the wrong thing to build first. What has to be right before any pixels move is that a host can see every rung at a glance and take all of them away in one click — which is why the grant sits on the participant row itself rather than behind a dialog, and why anything past edit is drawn as a warning. "Somebody else can run commands here" should never be a quiet row.

Roadmap​

Phases 1 to 5 ship complete. Phase 6 ships its RTMP half: a shared screen can be broadcast to Twitch, YouTube Live or any RTMP server, via an ffmpeg subprocess off the relay's existing ingest, with the stream key held in a streaming connector (Fernet-encrypted in secrets.db, never a setting, never sent to the browser). See share relay.

Two parts of Phase 6 are deliberately not built, for reasons rather than time:

  • The HLS branch — the answer to the SFU ceiling for large audiences. ffmpeg would segment happily, but Chrome does not play HLS natively, so serving it while keeping the viewer page's no-CDN promise means vendoring hls.js. That is a decision, not an afternoon. The RTMP path covers "broadcast to an audience" today by handing the problem to a platform that has already solved it.
  • TikTok — out of reach rather than unimplemented. It has no generally available live-ingest API; endpoints are issued per-account through a partner programme.

Two limitations worth stating now rather than discovering later:

  • Pixel mode cannot redact. A video frame does not know what a pane is, so the per-pane deny-by-default model protects the semantic path only. The pre-flight check names the panes that would be exposed and blocks until the host agrees — but it is a warning, not a guarantee, and the semantic path is the one that is actually safe.
  • The desktop shares the whole primary screen (Windows, X11): there is no window or tab picker outside macOS 15+ and Wayland, which bring the OS's own.
  • A mesh does not scale. One peer connection per guest means the host's upstream carries a copy of the stream per person. Fine for a working session, wrong for an audience — which is what the relay is for: the host sends one copy to it and it fans out. The relay has its own ceiling (tens of viewers per small machine), documented in share relay.

Minting is never implicit. Starting a share does not create a URL, and share.copyLink copies the existing one rather than making one — a command that silently published a screen to the open internet because somebody was looking for a link would be the most surprising thing this module could do. The pane puts it on its own row with its own button, Create & copy link, and a passphrase only behind Add passphrase.

Deliberate is not the same as slow, though, so the deliberate step is one click:

  • The new link goes straight onto the clipboard. The only thing anyone does with a fresh link is send it; a line under the card says whether the copy worked or the link has to be copied by hand.
  • "Also make a public link" on the empty state takes that step before the picker, so Share screen → pick a window → paste is the whole flow. It is unticked every time and never remembered: a remembered tick would make some later Share click public by default, and it does nothing if the picker is dismissed.
  • The relay is woken when the pane opens. It scales to zero, and the first request after a quiet spell waits for a machine to boot. GET /api/share/relay pings it on open, so the cold start happens while the host is choosing what to share instead of under the Create click — and the pane learns early whether public links are possible at all (no share.relayUrl reads as a sentence, not a button that fails).
  • The LIVE chip in the shell has a copy button while a link is open, because sending the link again is the most common thing anyone does mid-share.

The public-link Field points its label at the passphrase input on purpose (htmlFor). A <label> with no named control activates its first labelable child, which with the passphrase box closed is the Create button — so a click on the hint text would otherwise mint a link.

Once minted, the link is drawn as a shareable link card (ShareableLink, also used by notebook publishing) rather than a bare URL. Elsewhere in the app a link is somewhere to go; here the URL is the artefact being handed to somebody else, so the card is built for giving it away:

  • the address without its scheme, with a copy button;
  • a QR code for the person across the room — always black on white with a quiet zone, whatever the theme, because an inverted code fails on many readers;
  • Copy invite: a message with the link, when it expires, and whether it needs a passphrase. Never the passphrase itself — the invite is the thing that gets forwarded and pasted into the wrong channel;
  • an expiry countdown, in minutes, that turns into a warning in the last ten. A link that dies mid-sentence is only a surprise if nothing on screen was counting down.

The expiry and whether a passphrase is set ride the session model (link_expires_at, link_protected); the passphrase does not, and the node never keeps it. The card duplicates the share.copyLink command deliberately: the command is for someone who already knows it exists, and the pane is where everyone else is looking.

Six things about the link are worth knowing:

  • The link carries a watch code; publishing needs a different token. A link looks like horrible-share.fly.dev/k7m2x9qp — eight characters a person can read aloud — and it lets you watch and chat, nothing else. The long token that publishes video (/whip/<token>) is a separate value, served only to the host's own browser from GET /api/share/link and never part of the session model, which is broadcast verbatim to every guest. The two used to be one token, and because the relay replaces whoever is publishing, anyone holding the public link could push their own video into the host's stream. See share relay.
  • The relay leg fails independently. Friends on the fabric can be watching happily while the relay is unreachable, so relaying and relayError are their own fields rather than folded into the stream's error. A relay that is down is a chip and a sentence, never a stopped share.
  • Revoking is immediate and node-side. It works with the pane closed, after a tab crash, and from the agent, because the token lives on the node — and stopping the session revokes the link rather than leaving it to expire.
  • Minting attaches an already-running share. Minting is deliberately independent of sharing, so a share is often live before a link exists. The relay publish used to happen only at stream start, which made the order silently decide whether the feature worked: mint-then-share published, share-then-mint produced a link nobody could ever watch. The host saw relaying; every viewer sat on an endless 409 "not started yet". makeLink now calls attachRelay(), which is a no-op when nothing is being captured.
  • The capture is hinted as detail. A video track's default contentHint leaves the encoder guessing, and its guess is tuned for camera footage: under pressure it protects motion smoothness by dropping resolution — exactly backwards for a dashboard. 'detail' flips the trade, so a strained share degrades into a slideshow of readable text rather than smooth mush. Free: no constraint negotiation, no extra CPU.
  • The relay is polled, because nothing else reports it dying. A successful WHIP POST proves the relay accepted us once; it is not a subscription. The relay keeps its registry in one process's memory, so a crash, an OOM kill or a redeploy drops every token while the host's peer connection sits there believing it still has a peer — WebRTC to a dead relay does not raise, it just stops. So stream.ts asks GET /api/share/link/status every 5s while it is streaming, and that route asks the relay's GET /streams/{token}. This is not hypothetical: it is what put relaying on the pane over a link that served "this link has expired" to everyone who opened it.

The four relay states​

LinkStatusOut.state carries four values and the pane renders all four, because collapsing them swaps one wrong chip for another:

statechipmeansthe fix
liverelayingthe relay is holding published media for this tokennothing
idleno picturethe token is valid, nothing is arrivingrepublish
gonelink deadthe relay answered and disowned the tokenmint a new link
unknownrelay unknownwe could not asknothing yet

The load-bearing distinction is gone vs unknown. Both look identical from the host's side — no picture is reaching viewers either way — but they call for opposite reactions, and a flaky hop between node and relay rendered as "your link is dead" sends the host off to re-mint and re-share a URL that was fine all along. reconcileRelay therefore leaves relaying untouched on unknown rather than clearing it, in both directions: it will not resurrect a link already known dead either. Same three-state rule the hardware probe and the audio providers follow — found it, looked and it is absent, and could not ask.

viewers on this route is the relay's watcher count, deliberately not merged with StreamState.peers (fabric guests). They are different audiences and one number would misreport both.

The mapping is a pure function in its own file (relay-status.ts) for the reason net.ts is: stream.ts owns a capture, a peer connection and the audio graph, so it cannot be imported in a unit test — and this mapping is precisely the part that was wrong.

The relay URL is a setting (share.relayUrl, public — it is in every link); the relay key is env-only (SHARE_RELAY_KEY). A node with no relay configured is fabric-only, which is the default and a perfectly good state; minting then reports what to configure rather than failing with a status code.

What a guest may actually do​

Every guest action passes two gates, in this order, and neither can be skipped:

  1. The ladder (gate.require) — is this participant on a high enough rung?
  2. The host's own permission engine (agent/permissions.evaluate) — for the rungs that map onto tools the host's agent can also call.

Actuation happens only after both, and the audit log is written on every path including both refusals.

actions.py is the whole vocabulary, and it is deny by default: an action name this build has never heard of is refused rather than falling through to a permissive base case. That is what makes it safe for a peer on a newer build to ask for something new.

Three things here are load-bearing and quiet if wrong:

  • The needs rung on the wire is advisory and ignored. The requirement comes from the registry, keyed by action name. Letting the caller nominate the permission its own action needs is letting the caller pick its own lock — a guest on view could claim their terminal command needs view.
  • The tool names must be the host's real ones. terminal.exec, not a share-local spelling: that exact name is in permissions.SHELL_TOOLS, and that membership is what selects shell-aware per-subcommand rule matching and arms the rm -rf circuit breaker. A plausible near-miss like terminal.run would pass the ladder, match no host rule, skip the breakers, and read as allowed. Same for the layout tools, which are bare open_pane/close_pane.
  • ask stops. When the host's rules say a tool call needs a human, the action is refused for now and recorded as asked, not denied — the policy did not refuse it, it asked for approval. Actuating on ask without that human is precisely the gap the two-gate design exists to prevent.

The agent rung maps onto no tool at all. A remote agent turn is not a tool call; it is the path network/agent_bridge.py already owns and already gates, so agent.ask delegates to that node's existing network.allowRemoteAgent admission. A guest holding the second-highest rung on a node whose owner has not enabled remote agents still gets nothing — a session grant is reachability, not authority, the same rule friendship follows.

The audit log​

A grant ladder nobody can audit is a grant ladder nobody should trust. The pane lets a host hand a friend terminal; the only honest way to offer that is to show afterwards, in order, exactly what was run.

  • Denials are recorded and are the more interesting half. A refused guest leaves no other trace anywhere, so a log of successes only would be silent in exactly the case a host wants to know about.
  • Bounded and in-memory (the last 250 entries), cleared when the session ends. A session is a live thing, not a compliance record — and carrying one session's actions into the next would attribute them to whoever is in the room then.
  • Host-only. It is broadcast on the local /ws channel and never over the fabric: one guest reading it would learn what every other guest did.
  • Cursor movement is actuated but not logged. Otherwise the log is nothing but cursor rows and the terminal command that matters scrolls off the top.

Broadcasting​

A public link can be pushed onward to a platform. It sits below the link in the pane and only appears once a link exists, because the relay restreams that stream — and, like minting, it never happens implicitly: starting somebody's public broadcast is not a side effect of anything.

The stream key never reaches the browser. It is stored in the streaming connector, resolved on the node, and sent node → relay; the pane is given a label ("Twitch") and never the target URL. A node with no key stored is told which connector to add one to, and where the provider shows it.

Revoking the link or stopping the share stops the broadcast too — a link that dies while the stream carries on to Twitch is the worst possible reading of "stop".

Guest cursors​

A guest on the cursor rung reports their pointer as fractions of their viewport, never pixels — the two ends are different windows at different sizes, and a pixel offset from somebody else's screen means nothing on this one. It is throttled to ~20/s and drawn over the host's session pane with pointer-events: none, so a host never finds their own clicks landing on somebody else's pointer.

Stale cursors are dropped rather than left frozen. A guest who closes their tab sends no goodbye, and a pointer that stopped moving three minutes ago misrepresents where somebody is looking, which is the entire content of the feature.

Browser vs desktop​

BrowserDesktop
Session, invites, grants✅✅
Semantic mirror✅✅
Pixel capture✅✅ (primary screen; the OS picker on macOS 15+ and Wayland)
Viewers audio bus✅✅

Watching a friend's agent​

A participant holding view in a session this node hosts also receives this node's live trajectory runs from datasets marked shared — see trajectories. The mirror cannot carry that: it relays layout, not pane content. So trajectories streams its own traj_live frames, but asks gate.require(participant, "view") for every recipient rather than keeping a second permission check. Leaving the session stops the stream; being a friend without being a participant never starts it.

See also​