Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

docs(spec): live links — a read-only, expiring browser link to one terminal (Pro)

review6d420fa56998
diff --git a/docs/superpowers/specs/2026-09-28-live-share-link-design.md b/docs/superpowers/specs/2026-09-28-live-share-link-design.md
new file mode 100644
index 000000000..9cc79b4af
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-28-live-share-link-design.md
@@ -0,0 +1,582 @@
+# Design: Live links — a read-only, expiring browser link to one terminal (Pro)
+
+**Date:** 2026-09-28 (brainstorm finished 2026-09-30)
+**Branch:** `feat/live-share-link` (worktree `/root/nodeterm/wtshare`, off `origin/main` @ `ce621e2d`)
+**Status:** DESIGN — approved section by section in chat; this written spec awaits enes's review.
+No product code exists yet.
+**Repos:** nodeterm (desktop + Server Edition core), nodeterm-server (API), nodeterm-web (viewer page).
+**Builds on:** `docs/hosted-team-relay.md` (roles, `access-policy.ts`, `relay-host.ts` hooks,
+`hosted-scheduler.ts`), `docs/team-presence.md` (co-attach), `docs/remote-sessions.md` (relay).
+**Prerequisite:** `feat/shared-canvas-authority` (local, unpushed at the time of writing) must land
+on `main` first; see [Sequencing](#sequencing).
+
+## Naming
+
+In this codebase "share" already means *a project shared with a hosted team* (`team share`,
+`sharedProjects`, `sharedProjectId`, `onSharedChange`). To keep the two apart:
+
+- **UI:** "Live link".
+- **Code:** `watchLink` (IPC prefix `watchLink:`, modules `watch-link/`), the relay role is
+ **`watcher`**, a connected browser is a **viewer session**.
+
+## Problem / goal
+
+Desktop Pro sells almost nothing of its own (`ProCompare.tsx` lists two lines). The agreed direction
+is server-backed Pro value: the repo is public under BUSL, so a local `isPremium()` is an honesty
+gate, while a feature that runs through `api.nodeterm.dev` and the relay has a real cost to justify
+and cannot be patched out.
+
+A **live link** lets a nodeterm user hand anyone a URL. Opening it in a plain browser tab, with no
+install, no account and no Team Access seat, shows **one terminal or agent node live, read-only**,
+until the link expires or is stopped. Creating a link is Pro; viewing is free and needs nothing,
+and every viewer lands on nodeterm.dev, so it is also a growth loop.
+
+It is distinct from Team Access / the hosted team: those are seats, a whole canvas, SAS approval and
+a nodeterm install on the other side. A live link is one node, a browser, a bearer capability, and a
+time limit.
+
+Success means:
+
+- the owner's terminal is unaffected by viewers: no input, no resize, no pause, no slowdown;
+- a leaked link exposes that node's live screen and nothing else, and only until it expires;
+- the relay and the API never see terminal content;
+- nothing in "Core — free forever" is taken away.
+
+## Decisions (settled with enes, 2026-09-28 … 30)
+
+| # | Question | Decision |
+|---|---|---|
+| D1 | Role of a link | **Viewer or Commenter**, chosen at creation. Viewer watches; Commenter watches and can chat. No "request control": control means joining a team with an invite code, a SAS and the Editor role. |
+| D2 | Where Commenter messages go | **Live, ephemeral chat only.** Shown to the owner and to the link's other viewers, never written to any file. The owner can copy one message to the card's comments by hand. |
+| D3 | Scope of a link | **One terminal/agent node.** The protocol leaves room for several nodes later; v1 is always one. |
+| D4 | Viewer page host | **`https://nodeterm.dev/s/<linkId>#1.<S>`**, an Astro route in nodeterm-web. |
+| D5 | What a viewer sees on join | **The visible screen only, never scrollback.** If the owner scrolls back (tmux copy-mode), viewers see that too, as it happens. No "include history" option. |
+| D6 | Limits | Expiry choices 15 min / **1 h (default)** / 8 h / 24 h, **max 24 h**, no extension. **10** concurrent viewers per link, **5** active links per machine, **50** creations per license per 24 h (server). Per-viewer bandwidth ~256 KB/s sustained, then one keyframe per second at most. Commenter: 1 message / 2 s, 500 chars. |
+| D7 | Lifetime buyers / Pro lapse | Lifetime ($299, Apple non-consumable surfaced to the desktop as an `apple:` license) is **included with no extra cap**: the limits are structural, not quotas. Creation checks the license is **live** (keygen validate / live Apple row; `free:` and companion tokens refused). A lapse lets open links **run out their term** (≤ 24 h); host re-mints check only the token and the link row. |
+| D8 | App restart | Links **survive restarts**. Active links (secret included) are persisted, `safeStorage`-encrypted on the desktop and in a 0600 file on the Server Edition, and resume at launch. |
+| D9 | Surfaces | **Desktop and Server Edition** can create links (one core service, both shells register it). **Mobile** opens links in Safari in v1; creating/revoking from the phone is a follow-up for nodeterm-ios. Kanban card, card modal and sessions sidebar carry the action and the indicator (mandatory, CLAUDE.md). |
+| D10 | Architecture | **Approach 1** (below): the narrowest new relay role on the existing core relay host. |
+
+## Non-goals (v1)
+
+- Input of any kind from a viewer: keys, paste, mouse, resize, flow control.
+- More than one node per link (groups, projects).
+- Scrollback/history delivery.
+- Persistent comments, or comments written to `board-log.jsonl`.
+- Link extension, custom expiry values, per-viewer identity or accounts.
+- Teammates (Team Access / hosted) seeing that a node is being broadcast: the LIVE state is
+ machine-local.
+- Creating/revoking links from the phone, and an in-app phone viewer.
+- Canvas-control (agent) verbs for links: an agent must never be able to publish a terminal.
+- Relay-side metering and a one-to-many relay room (see [Follow-ups](#follow-ups)).
+
+## Approaches considered
+
+1. **Chosen — a `watcher` role on the core relay host.** Reuse `relay-socket` (handshake unchanged),
+ `relay-host` (session + hooks), `hosted-scheduler` (one per link), the deny-by-default
+ `access-policy` framework, the pty viewer mode (`joinOnly`, `sizeVote: false`) and the
+ UiSinkRegistry drop-and-redraw. New code is mostly glue plus a few narrow flags. Risk: a viewer
+ is a core client, so every outbound path must stay closed to it; answered by two independent
+ layers (no broadcast enumeration, plus a deny-by-default sink filter) and guard tests.
+2. **A bespoke share protocol with a direct pty tap.** Smallest conceivable surface (never a core
+ client), but new crypto code, and a second copy of seed/resync/sizing logic that drifts from the
+ hosted Viewer path. Rejected.
+3. **A broadcast room in the relay broker.** Host uploads once, the relay fans out. Needs a new broker
+ primitive, a relay deploy, relay limits that do not exist today, and keyframe-on-join
+ coordination. Unnecessary at 10 viewers; kept as the scale path.
+
+## Architecture
+
+```
+ Owner (desktop / Server Edition) api.nodeterm.dev Viewer (browser)
+ ┌───────────────────────────────────────┐ ┌────────────────┐ nodeterm.dev/s/<id>#1.<S>
+ │ renderer: Live link dialog, chip ×4 │ │ watch_links │ ┌───────────────────┐
+ │ │ host-only IPC (watchLink:*) │ mint │ create │ join │ #S → keys │
+ │ core/watch-link/ │───────▶│ host-token │◀─────│ POST join{joinKey}│
+ │ registry (≤5, persisted) │ │ status │ │ │
+ │ per link: hosted-scheduler (≤10) │ │ join │ │ relay client │
+ │ └ connectRelayHost(link keys, │ │ revoke(-all) │ │ (e2ee_hello as │
+ │ autoApprove = viewer key, │ └────────────────┘ │ today) │
+ │ watcher hooks) │ relay.nodeterm.dev │ xterm, read-only │
+ │ per viewer: no-broadcast client, │◀══════ 1:1 E2E bridge ══════════▶ chat (Commenter) │
+ │ host-initiated pty join │ (broker unchanged) └───────────────────┘
+ │ (joinOnly, sizeVote:false), │
+ │ string-sequence filter, │
+ │ drop-and-redraw, never pause │
+ └───────────────────────────────────────┘
+```
+
+### Units
+
+| Unit | Where | One job |
+|---|---|---|
+| Protocol + keys + browser client | `src/shared/watch-link/` | Link encode/parse, key derivation from `S`, message types, and the browser relay client (tweetnacl + WebCrypto only, no Node APIs). Test vectors in `vectors.json`. nodeterm-web keeps a byte-identical copy. |
+| Registry | `src/core/watch-link/registry.ts` | Active links, limits, lifecycle (create / revoke / revoke-all / expire / node gone), persistence, owner state events. |
+| Link host | `src/core/watch-link/link-host.ts` | One `hosted-scheduler` per link; each listener runs `connectRelayHost`; attaches viewer sessions, sends keyframe + meta, relays chat. |
+| Watcher policy | `src/core/watch-link/watcher-policy.ts` | The `RelayHostHooks` for a viewer session: `access` (refuse everything except a Commenter's chat cast) and `wrapSink` (deliver only this session's pty channels and `watchLink:*` events). |
+| Output filter | `src/core/watch-link/stream-filter.ts` | Stateful per-session parser that removes string-type escape sequences from the watcher's pty stream. |
+| Backend client | `src/core/watch-link/api.ts` | create / host-token / status / revoke / revoke-all calls. |
+| Existing-code changes | `ui-sink-registry.ts`, `pty-manager.ts`, `hosted-scheduler.ts`, `host-control.ts` | Registry client flags `broadcast: false` and `pausesPty: false` (+ a per-client resync provider), `captureVisible(sessionId)`, scheduler `maxBridged`, `watchLink:` host-only prefix. |
+| Shell wiring | `src/main` and `src/server` | Register the same core service; desktop persists secrets with `safeStorage`, Server Edition with a 0600 file in its data dir. |
+| API | nodeterm-server | `watch_links` table and six routes. |
+| Viewer page | nodeterm-web | `/s/[id]` route and the vendored client. |
+| Renderer | `src/renderer` | `watchLinks` transient store, `LiveLinkChip` (one component, four surfaces), create dialog, popover, Settings section, palette commands, `requireProOr`, ProCompare line. |
+
+## Link, keys and handshake
+
+### Link format
+
+```
+https://nodeterm.dev/s/<linkId>#1.<S>
+```
+
+- `linkId`: 16 random bytes chosen by the **server**, base64url (22 chars). It names a link and
+ unlocks nothing.
+- `S`: 32 random bytes chosen by the **host**, base64url (43 chars). In the fragment, so it never
+ reaches an HTTP request, a server log or a referrer.
+- `1.` versions the fragment format.
+
+### Derivations from `S`
+
+Hash-based and synchronous, using tweetnacl's SHA-512 only, so Node and the browser compute
+identical bytes:
+
+| Value | Derivation | Known to |
+|---|---|---|
+| Host key pair | `nacl.box.keyPair.fromSecretKey(SHA512("nodeterm-watch-link-v1/host" ‖ S)[0..32])` | host, anyone holding the link |
+| Viewer key pair | same with `…/viewer` | host, anyone holding the link |
+| `joinKey` | `SHA512("nodeterm-watch-link-v1/join" ‖ S)[0..32]` | + the API, which stores only `sha256(joinKey)` and sees `joinKey` only in a join request |
+
+The API never sees `S` or either key pair; the domain-separated derivations make `joinKey` useless
+for recovering them.
+
+### Relay room
+
+Pairing id **`wl.<linkId>`**. The broker does no format validation, so **the broker is not changed**.
+The prefix makes watch-link traffic recognizable in the relay's join/close log lines, which print the
+first 12 characters of the id.
+
+### Handshake — `relay-socket.ts` is not changed
+
+1. The viewer sends `e2ee_hello {publicKeyB64: viewerPub, nonceB64}`, exactly as a client does today.
+2. The host derives the base and session keys (unchanged `e2ee.ts`), replies `e2ee_ready`; the
+ encrypted `e2ee_auth` / `e2ee_authenticated` exchange runs as today.
+3. The `relay-host` trust gate for a link session:
+ - `autoApprove(peerKeyB64)` compares the handshake's peer key with the **expected viewer key from
+ the host's own registry**, never with anything the peer sent.
+ - Any other key reaches `onPeerPending`, which **denies immediately**. A link session never raises
+ an approval dialog.
+ - The viewer sends its own `trust:confirm` automatically: holding the link is its consent.
+ - No SAS is shown and no pin store is passed.
+
+The role (Viewer/Commenter) is **host-side registry state**, never in the link: a holder cannot
+upgrade themselves. Different roles need different links.
+
+### Messages inside the tunnel (`rpc.ts` framing)
+
+Host → viewer:
+
+- `ev watchLink:meta {v: 1, role, label, title, expiresAt, cols, rows}`
+- pty output as binary `encodePtyData` frames; `ev pty:size:<sid>`
+- keyframe: visible screen + cursor + alt-screen flag, in the `pty:resync` shape
+- `ev watchLink:chat {id, name, text, at, from: 'viewer' | 'sharer'}`
+- `ev watchLink:end {reason}`, `reason ∈ revoked | expired | node-gone | session-ended |
+ host-stopping | kicked`
+- `ev watchLink:waiting {}` — the node has no running session right now
+
+Viewer → host: `cast watchLink:chat {name, text}` (Commenter only), `trust:confirm`, keepalive.
+Everything else is refused by the watcher policy. **There is no input, resize or flow message in the
+protocol.**
+
+## Host side
+
+### Registry
+
+- At most **5** active links per machine. A record is
+ `{linkId, nodeId, role, label, createdAt, expiresAt, secret}`.
+- **Persistence:** `<userData>/watch-links.json` through `writeFileAtomic`.
+ - Desktop: `secret` is `safeStorage`-encrypted. With no `safeStorage`, links are **not persisted**
+ (they work, and end at quit), and the user is told once. There is no plaintext fallback on the
+ desktop.
+ - Server Edition: a 0600 file in its data dir, the same rule as the hosted team's host key
+ (headless Linux has no keyring).
+ - At launch, expired records are pruned and each remaining link's listeners reopen.
+- **Clock:** the expiry timer is derived from the server's `expiresAt` and the response's `Date`
+ header (`tokenTtlMs`'s rule), never from the local clock alone.
+- **Create order:** generate `S` → `POST /v1/watch-links` → persist locally → start listeners. If the
+ local write fails, the server row is revoked best-effort and the owner sees an error; no
+ half-created link survives.
+- **Revoke:** delete and write the record first, then end the sessions with `end{revoked}`, then a
+ best-effort server revoke. Local revoke is complete even offline, because the host is the only
+ listener.
+- **Node gone:** on every workspace-store change and before every join, the registry asks
+ `projectIdsForNode(nodeId)`. An empty answer ends the link with `node-gone` and revokes it
+ server-side. This covers a node removed by the canvas authority on a peer's op, which the local
+ renderer's delete funnel never sees.
+- **Link state is never canvas content.** No field on `CanvasNodeState`, `ProjectKanban` or any
+ `CanvasMutation`: canvas sync would carry it to teammates and the canvas authority would write it
+ into the git-shared `project.json`. It lives in the registry and in a transient renderer store.
+
+### Listener pool
+
+- One `hosted-scheduler` instance per link, with a watch-link `mint()` (the host-token route) and a
+ new **`maxBridged`** option: at 10 bridged sessions no replacement listener opens, so the broker
+ closes extra clients ("no host waiting").
+- The scheduler's existing rules apply unchanged: refresh 30 s before expiry, backoff reset only on
+ proof the relay works, 429 waits ≥ 60 s, 402/403 stops minting, 200 mints per hour cap.
+- While a link holds no idle listener (it is full), the host calls the **status** route every
+ **5 min**, so a server-side revoke still reaches it.
+- A 410 from host-token or status ends the link locally with the reason it names.
+
+### Attaching a viewer session
+
+1. `PeerAttach.attach(sink)` registers the watcher client **without joining presence** (no cursor or
+ facepile on the owner's canvas), with registry flags `broadcast: false` (absent from `ids()` and
+ `clientIds()`; reachable only by `sendTo`) and `pausesPty: false`.
+2. The host makes the pty join itself:
+ `ptyManager.create(watcherId, {persistKey: nodeId, joinOnly: true, sizeVote: false,
+ cols/rows: the session's last applied size, sshRemote/requireRemote: from the host's own node
+ records, viewerId: 'watch-<sessionId>'})`. **No argument comes from the viewer.** (The hosted
+ Viewer path strips `sshRemote` because a peer supplied it; here the host builds it.)
+3. A keyframe from **`captureVisible(sessionId)`** (new; never history):
+ - local tmux and session-host: the `captureSnapshot` path (`capture-pane -p -e`,
+ `sessionHostCapture(name, false)`);
+ - SSH: `capture-pane -p -e` over the ControlMaster, **without** `-S`;
+ - a plain shell with no tmux: no capture exists. The viewer starts from the live stream, and the
+ page says so.
+4. `watchLink:meta`, then the live stream.
+
+If the join answers `unavailable: 'join-only'`, or the session later sends `pty:exit` /
+`pty:recycled`, the viewer gets `watchLink:waiting` and the host joins again when a session for that
+node appears.
+
+### Backpressure — a viewer never slows the owner
+
+- `pausesPty: false` skips `sendTo`'s 1 MB pause block entirely for a watcher client, closing for
+ links the residual `docs/hosted-team-relay.md` documents for hosted Viewers.
+- Drop-and-redraw at **512 KB** buffered for a watcher, with resync through **`captureVisible`** (the
+ default resync provider returns history for session-host and SSH; watchers must never get it).
+- A per-viewer token bucket (**256 KB/s sustained, 1 MB burst**). Past it the stream stops and at most
+ one keyframe per second is sent. This bounds relay traffic during a flood (`yes`, a verbose build).
+
+### Output filter
+
+The watcher's pty stream passes a per-session, stateful parser that **removes every string-type
+sequence**: OSC, DCS, APC, PM and SOS. They carry clipboard contents (OSC 52 from tmux
+`set-clipboard on`), titles, hyperlink targets, file transfers and palette changes, none of which is
+text on the screen. CSI, other ESC sequences and text pass unchanged. Sequences split across chunks
+are handled; an unterminated string sequence past **64 KB** is dropped and the parser resets.
+
+### Commenter chat
+
+- Host validation per viewer session: 1 message / 2 s, text ≤ 500 chars, name ≤ 32 chars, control
+ characters stripped. A viewer's name is always shown with "(link viewer)".
+- Delivered to every session of that link and to the **local owner clients only**, never to relay
+ peers or teammates.
+- The last 200 messages per link are kept in memory and cleared on revoke or restart.
+- The owner replies from the node popover (`from: 'sharer'`, name = the link's label). "Copy to card
+ comments" writes one board-log comment **as the owner**, an explicit act; nothing is written
+ automatically.
+
+### Owner state and host-only IPC
+
+- The registry emits `watchLink:state {linkId, nodeId, role, label, expiresAt,
+ status: live | reconnecting | refused, viewers: [{sessionId, name?, joinedAt}]}` to local owner
+ clients only.
+- IPC: `watchLink:create | list | revoke | revoke-all | kick | chat-send | chat-history`, plus the
+ `watchLink:state` / `watchLink:chat` events. **`watchLink:` joins `HOST_ONLY_CHANNEL_PREFIXES`**
+ (`src/shared/host-control.ts`): no relay peer can reach them, hosted owners and editors included
+ (an editor passes every access check, and a link consumes the host's Pro and publishes a host
+ terminal to the world). A test proves the refusal on the hosted path as well as the Team Access
+ path.
+- **No canvas-control verb** creates, lists or revokes a link.
+
+## Backend (nodeterm-server)
+
+### Table `watch_links`
+
+| Column | Notes |
+|---|---|
+| `id` text PK | 16 random bytes, base64url |
+| `license_id` text not null | the license that created it |
+| `join_key_hash` text not null | `sha256(joinKey)`, hex |
+| `created_at`, `expires_at` | `expires_at` clamped server-side |
+| `revoked_at` null | |
+
+Indexes on `license_id` and `expires_at`. Rows more than 7 days past expiry are deleted
+opportunistically on each create. Migration numbered after the latest on `main` (0013 at the time
+of writing).
+
+### Routes
+
+All registered with the licensing routes, so they exist only when the licensing env is set.
+
+| Route | Body | Rules | Answer |
+|---|---|---|---|
+| `POST /v1/watch-links` | `{entitlement, joinKeyHash, ttlSeconds}` | Token verifies; no `via` (companion) and no `free:` license. **Liveness:** keygen license → validate; `apple:` → a live purchase row. `ttlSeconds ∈ {900, 3600, 28800, 86400}` (max from env). Per license ≤ **15** active and ≤ **50** created per 24 h. Per IP 30/min. | `{linkId, expiresAt}`; 402 `not_entitled`, 400, 429 `{scope}` |
+| `POST /v1/watch-links/:id/host-token` | `{entitlement}` | Token verifies, its `licenseId` equals the row's, row live. No keygen call (D7). Per link 120/h, per IP 30/min. | `{pairingToken (role host, pairingId wl.<id>, 120 s), exp}`; 410 `{reason}`, 402, 404, 429 |
+| `POST /v1/watch-links/:id/status` | `{entitlement}` | Owner match. | `{state: live \| revoked \| expired}` |
+| `POST /v1/watch-links/:id/join` | `{joinKey}` | Timing-safe compare of `sha256(joinKey)` with the row. Per IP 30/min, per link 300/h. **CORS for `https://nodeterm.dev` on this route only.** | `{pairingToken (role client, wl.<id>, 120 s), relayEndpoint, exp}`; **the same 404** for an unknown id and a wrong key; 410 `{revoked \| expired}` only when the key matches; 429 |
+| `POST /v1/watch-links/:id/revoke` | `{entitlement}` | Owner match; idempotent. | 204 |
+| `POST /v1/watch-links/revoke-all` | `{entitlement}` | All the license's live rows. | 204 |
+
+- **The relay is not changed.** It checks a token only at join, so it cannot cut a bridge; the host
+ does. A server-side revoke reaches the host through its next mint (≤ ~90 s) or status poll
+ (≤ 5 min).
+- **Admin:** `/admin` gains link lookup and revoke by `linkId`. The viewer page's "Report" is a
+ `mailto:[email protected]` carrying the `linkId`. Content is end-to-end encrypted; revoke is
+ the moderation tool.
+- **Logging:** the existing `[api] … ip= status=` lines. `joinKey`, request bodies and tokens are
+ never logged.
+
+## Viewer page (nodeterm-web)
+
+### One source for the client
+
+The browser client lives in the desktop repo (`src/shared/watch-link/`) and is exercised there
+end-to-end against the real core host (see [Testing](#testing)). nodeterm-web vendors that module and
+`vectors.json` **byte-identically** (the iOS `KanbanDefaults` pattern) and runs the same vectors in
+its own test (vitest added as a dev dependency). A protocol change lands in the desktop repo first,
+with new vectors, and is then copied.
+
+### Route `src/pages/s/[id].astro`
+
+- Validates the id's shape and returns the page shell. The server fetches nothing.
+- Headers on this route only:
+ - `Content-Security-Policy: default-src 'none'; script-src 'self'; style-src 'self'
+ 'unsafe-inline'; connect-src https://api.nodeterm.dev wss://relay.nodeterm.dev;
+ img-src 'self' data:; font-src 'self'; frame-ancestors 'none'; base-uri 'none';
+ form-action 'none'` (xterm injects `<style>` elements; scripts stay `'self'`)
+ - `Referrer-Policy: no-referrer`, `X-Robots-Tag: noindex, nofollow`, `Cache-Control: no-store`,
+ `X-Content-Type-Options: nosniff`
+- No remote fonts, analytics or third-party scripts. The page does not import site CSS that loads
+ remote fonts.
+- New dependencies: `@xterm/xterm` (the desktop's 5.5 line), `@xterm/addon-unicode11`, `tweetnacl`.
+
+### Flow
+
+Parse `id` and `1.<S>`; derive keys; `POST …/join`; open `wss://relay…?token=`; handshake;
+`trust:confirm`; `meta`; paint the keyframe; stream. The fragment is never sent anywhere and is not
+removed from the address bar (the link must stay copyable).
+
+### xterm
+
+- `disableStdin: true`; `onData` is not wired to anything.
+- No web-links addon; OSC 8 never arrives (host filter). **No clickable links.**
+- A CSI handler swallows mouse-tracking DECSET/DECRST (1000/1002/1003/1006), so a viewer can always
+ select text.
+- Fixed `cols`/`rows` from `meta`, no FitAddon; font size computed to fit the width, floor 7 px,
+ horizontal scroll below that; pinch zoom allowed on mobile.
+- Scrollback 1000 lines: what this viewer itself watched on a plain shell, never host history.
+
+### Fixed chrome (outside the terminal area; terminal output cannot draw over it)
+
+- Top bar: "● LIVE · Read-only terminal · shared with nodeterm", the node title, "by <label>",
+ "ends in 42 min". Owner-supplied strings are set with `textContent` and marked "(set by the
+ sharer)".
+- Footer: "Get nodeterm" (growth loop) and "Report".
+- Commenter links: a chat side panel (a bottom sheet on mobile). A name is required to chat,
+ remembered in `localStorage` (try/catch). Messages carry "(link viewer)" / "(sharer)". Rate-limit
+ feedback is visible.
+
+### States
+
+| State | Copy |
+|---|---|
+| Connecting | "Connecting…" |
+| No running session | "The terminal isn't running right now — this page will pick it up when it starts." |
+| Live | the terminal |
+| Relay closed / cannot connect | "Can't reach the sharer right now — their nodeterm may be offline, or this link is at its 10-viewer limit. Retrying…" (1, 2, 4, 8, 15 s, then every 30 s). Both causes are named because the page cannot tell them apart. |
+| 404 | "This link isn't valid." Final. |
+| 410 / `end{revoked}` | "The sharer stopped this live link." Final. |
+| 410 / `end{expired}` | "This live link has expired." Final. |
+| `end{node-gone}` / `end{session-ended}` | "The shared terminal was closed." Final. |
+| `end{kicked}` | "The sharer ended your connection." Final for this tab. |
+| 429 | Waits for `Retry-After`. |
+| Unsupported `meta.v` | "Reload to update this viewer." (`no-store` makes a reload fetch the current page.) |
+
+## UX (renderer)
+
+### Entry points
+
+All go through `requireProOr('Live links', …)`. That is the UX; the server is the gate.
+
+- **Node context menu** (terminal and agent nodes): "Share live link…". The sessions sidebar row
+ shares the `selectionItems` builder; the kanban card menu gets the same row from the same builder.
+ Hideable from Settings → Appearance as `live-link` (`HIDEABLE_MENU_ITEMS`).
+- **Card modal header:** a "Share live link" action on terminal cards.
+- **Command palette:** "Manage live links" (opens the Settings section) and "Stop all live links".
+- **Disabled with a reason, never hidden:**
+ - relay-tab node: "Live links are created on the machine that runs this terminal."
+ - unpackaged build (`relayAllowed()` false): "Live links need the installed app."
+ - 5 active links: "Stop a live link first — 5 can be active at once."
+- Creating a link does not need the node on screen (`joinOnly` attaches in core), so the Omni
+ board's cards of other projects can create links too.
+
+### Create dialog
+
+- "Share a live link to <node title>".
+- Role: **Can watch** (default) / **Can watch and chat**.
+- Expiry: 15 min / **1 hour** / 8 hours / 24 hours.
+- "Shown to viewers as": prefilled with the presence name, ≤ 40 chars.
+- An always-visible warning: "Anyone with the link sees everything this terminal shows: what's on
+ screen now, anything printed later (tokens, env dumps), and anything you scroll back to. They
+ can't type or resize it."
+- "Create live link" → the URL with **Copy**, "Anyone with this link can watch until 15:42", and
+ **Stop sharing**.
+- Errors: 402 → "Live links need an active Pro plan." + Upgrade; 429 → which limit; network →
+ "Couldn't reach nodeterm's service. Nothing was shared."
+
+### `LiveLinkChip` — one component, four surfaces
+
+Node header (beside `PresenceChips`), kanban card, card modal header, sessions sidebar row.
+
+- `● LIVE` (a link, no viewers), `● LIVE · 2` (watchers), amber `LIVE · offline` (reconnecting),
+ muted `LIVE · refused` (the API refuses mints). A dot marks unread Commenter chat.
+- **Not hideable.** It is the owner's signal that a terminal is being broadcast; it is not in
+ `HIDEABLE_HEADER_BUTTONS`, pinned by a guard test.
+- Click → popover, per link (a node may have several, e.g. one Viewer and one Commenter link):
+ role, countdown, Copy link, Stop sharing; the viewer list (name or "Viewer 1", joined time, **Kick**
+ with the note "Kick ends this connection; anyone with the link can rejoin. Stop sharing to end it
+ for everyone."); for Commenter links the chat thread, a reply box, and "Copy to card comments" per
+ message.
+- **Join notice:** an info strip, "Someone started watching <title> (2 watching)." It is how an owner
+ notices a leaked link. Not an OS notification.
+
+### Settings → "Live links"
+
+Every active link (node, project, role, viewers, remaining time, Copy, Stop) and "Stop all". Non-Pro
+users see a short pitch and Upgrade.
+
+### ProCompare
+
+One Pro line: "Live read-only links to a terminal — viewers need nothing installed". The Core list is
+untouched. (`UpgradeDialog`'s outdated quota sentence is being fixed in a parallel PR; this feature
+only calls `requireProOr`, which today has zero callers.)
+
+### Surfaces
+
+- **Desktop:** full.
+- **Server Edition:** the same renderer; the ws-bridge gets a real `watchLink` API member (not a stub),
+ backed by the same core service. Its browser clients are the host's own user, not relay peers, so
+ the host-only prefix does not refuse them.
+- **Relay tab:** the API stub refuses; the menu row is disabled with its reason.
+- **Mobile:** no UI in v1; links open in Safari. Follow-up for nodeterm-ios below.
+
+## Error handling
+
+| Situation | Behavior |
+|---|---|
+| API unreachable at create | Nothing is created locally. "Nothing was shared." |
+| Server row created, local persist failed | Best-effort server revoke, visible error. |
+| host-token 402/403 | Scheduler stops (existing rule); chip `refused`. No tight loop. |
+| host-token or status 410 | Link ends locally with that reason. |
+| 429, relay unreachable | Existing backoff rules; chip `offline`; viewers see "can't reach". |
+| `safeStorage` unavailable (desktop) | Links not persisted; told once; they still work until quit. |
+| Sleep / lid closed | Sockets drop; the scheduler reconnects on wake; viewer pages resume on their own. |
+| Node deleted (locally or by the canvas authority) | `node-gone`, link ends, server revoke. |
+| Terminal exited or recycled | Viewers wait; the host rejoins when a session appears. |
+| Slow viewer | Drop-and-redraw; the pty is **never** paused. |
+| Hostile viewer | Any request → `E_ROLE`; chat floods hit the rate limit; wrong key → immediate deny; a sink that throws twice in a row is evicted (existing rule). |
+| Pro lapsed | Open links run out their term; new creation gets 402. |
+| Two instances on one data dir | Desktop relies on its single-instance lock. A Server Edition that does not own its data dir (the hosted relay's admin-socket rule) does not host links, and logs it. |
+
+## Security properties and residuals
+
+- **Confidentiality:** the relay and the API never see plaintext; `S` never leaves the owner's
+ machine and the viewer's browser.
+- **Viewer authentication:** only holders of `S` complete the handshake. The API's `joinKey` gate also
+ keeps anyone without `S` from spending the host's listener slots.
+- **Host authenticity:** a link holder can derive the host key pair, but registering as host in
+ `wl.<linkId>` needs a host token minted with the owner's entitlement for that link's license.
+- **Replay:** per-session nonces (existing).
+- **Read-only:** there is no input channel in the protocol; the watcher policy refuses every request
+ (deny-by-default); the pty join is `joinOnly` + `sizeVote: false`; a watcher never takes a pause
+ ticket.
+- **Isolation from the canvas:** a watcher receives no broadcast (absent from `ids()`), and its sink
+ filter passes only its session's pty channels and `watchLink:*` events. Canvas ops, presence,
+ agent status and context updates cannot reach it by either path.
+- **Residual — no forward secrecy**, as for the relay today: a recorded session plus a later-leaked
+ `S` is plaintext. `S` is deleted from the registry on revoke/expiry; lifetime ≤ 24 h.
+- **Residual — all viewers of a link share one viewer key**, so they are cryptographically
+ indistinguishable; identity is the session. Kick is per session; only Stop ends access.
+- **Residual — the fragment lives in browser history** and can be synced by the browser to the
+ viewer's other devices. Answered by the short default expiry and Stop.
+- **Residual — the owner-supplied label and node title are shown to viewers.** They are rendered as
+ text inside fixed nodeterm chrome, marked as sharer-set; terminal output cannot draw over the
+ chrome and has no clickable links.
+
+## Testing
+
+- **Pure units:** key derivation against vectors; link encode/parse; the stream filter (chunk
+ boundaries, the 64 KB cap, CSI untouched); the token bucket; the chat sanitizer; registry lifecycle
+ on a fake clock; scheduler `maxBridged`.
+- **Core integration** (in-process transport, the real `relay-host`, the real watcher policy, and the
+ **browser client itself** from `src/shared/watch-link/`):
+ - handshake; a wrong viewer key is denied;
+ - **one request for every channel in `IPC`**: all refused with `E_ROLE`, except a Commenter's chat;
+ - **one broadcast on every channel**: zero frames reach the watcher;
+ - a watcher with a tiny window does not shrink the pty;
+ - a watcher whose socket is stalled does not pause the pty;
+ - resync returns the visible screen only, on the session-host and SSH paths too;
+ - no OSC 52 in the delivered stream;
+ - `node-gone` and expiry end sessions.
+- **Guard tests:** `watchLink:*` is host-only and in no role table, refused on both the Team Access
+ and the hosted paths; `CanvasNodeState`, `CanvasMutation` and `ProjectKanban` carry no link field;
+ `LiveLinkChip` is not in any hideable list; the canvas-control verb table names no link verb.
+- **Mutation checks:** break each load-bearing rule on purpose (host-only prefix, `broadcast: false`,
+ `pausesPty: false`, `captureVisible`, the stream filter, `autoApprove`'s key comparison) and confirm
+ a test turns red.
+- **Backend:** every refusal path in the routes table, owner mismatch, TTL clamping, license limits,
+ the timing-safe compare, the same 404 for unknown id and wrong key, no 410 leak on a wrong key,
+ CORS on the join route only.
+- **Web:** the vendored vectors.
+
+### Device checklist (owed; this server cannot run Electron)
+
+1. Create a link on a Mac; open it in Safari on a phone.
+2. Typing in the viewer does nothing.
+3. Narrowing the viewer's window does not resize the owner's terminal.
+4. The owner scrolling back (tmux copy-mode) is visible to the viewer.
+5. Stop sharing cuts viewers immediately.
+6. Expiry ends the link with the expired message.
+7. Quit and relaunch: the link resumes and the viewer page reconnects by itself.
+8. Lid closed and reopened: the link recovers.
+9. A non-Pro account gets the upgrade dialog; the server refuses a forged request.
+10. The 11th concurrent viewer sees the "offline or at its limit" message.
+11. `yes` in the shared terminal with a throttled viewer: the owner's terminal stays smooth.
+12. Text copied in tmux does not appear in the viewer's decoded stream (debug flag).
+13. A Server Edition creates a link from its browser UI.
+14. The chip appears on all four surfaces; Kick and chat work both ways.
+15. **A viewer stays connected for more than 2 minutes without a drop** — whether production ends a
+ bridged socket at its token's lifetime is unverified (the same open question as hosted checklist
+ item 8).
+
+## Sequencing
+
+1. **Backend:** table and routes. Inert without clients, so it can deploy first.
+2. **Core:** `src/shared/watch-link` (protocol, keys, browser client, vectors), registry, link host,
+ watcher policy, registry flags, `captureVisible`, stream filter, scheduler `maxBridged`, host-only
+ prefix.
+3. **Shells + IPC + renderer:** desktop and Server Edition wiring, bridge member, dialog, chip,
+ popover, Settings, palette, ProCompare.
+4. **nodeterm-web:** the route, headers and vendored client.
+
+**Start implementation only after `feat/shared-canvas-authority` is on `main`**, and branch from it:
+both change `Canvas.tsx`, the access-policy guard test, `hosted-service.ts` and `workspace-store.ts`,
+and the node-gone rule relies on the authority's store being the source of node membership.
+
+## Follow-ups
+
+- **nodeterm-ios (for @eneskirca):** create/list/revoke links from the phone (needs `watchLink.*`
+ verbs on the phone dialect of the desktop's host service); optionally open `nodeterm.dev/s/` links
+ in an in-app viewer (universal links).
+- **Terms of service:** a clause that the sharer is responsible for shared content (legal decision,
+ owed by enes).
+- **Relay metering:** per-bridge byte caps in the broker; today the relay has no limits at all.
+- **Broadcast room** (approach 3) if links need audiences well beyond 10.
+- **Teammates seeing LIVE:** whether Team Access / hosted peers should see that a node is broadcast.
+- **Commenter → card:** a persistent, moderated comment path, if ephemeral chat proves too little.
+- **Host-token proof of possession:** the existing `/v1/relay/host-token` gap (hosted-team threat
+ notes) does not apply here, since watch-link host tokens require the owner's entitlement, but the
+ general fix stays owed.