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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(windows): live links on the session host
review1162c02cf7ea
diff --git a/CLAUDE.md b/CLAUDE.mdindex 640506558..0019d394a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -6007,7 +6007,8 @@ one is Pro and the backend is the gate. Reference: **`docs/live-links.md`**. Invviewer holds (`ui-sink-registry.watcher.test.ts`, `pty-reap.test.ts`).- The stream filter sees every byte, has NO length cap (a cap leaked a measured clipboard), and everyjoin resets it `midStream`, never to text mode and never on a keyframe. `captureVisible` never returns- history (exact `=nt-<id>:`, no `-S`; session host, plain shell and a Zellij node get no keyframe). A+ history (exact `=nt-<id>:`, no `-S`; the session host answers its negotiated `captureVisible`, the+ only route that sets `altScreen` itself; plain shell and a Zellij node get no keyframe). Aviewer sizes nothing: `joinOnly` + `sizeVote: false`; its own tmux client is `-E -f ignore-size,read-only`,and a Zellij node never gets one (refused, never a Zellij attach — that client could type).- Node gone is tri-state (only ABSENT ends a link; a lost or corrupt index is never a complete read —@@ -6019,9 +6020,11 @@ one is Pro and the backend is the gate. Reference: **`docs/live-links.md`**. Inv- `src/shared/watch-link/` is vendored byte for byte into nodeterm-web: siblings and `tweetnacl` only,no Node API, type imports spelled `import type` (`isomorphism.guard.test.ts`); a change there owes theweb repo a re-vendor. Chat text is stripped of controls AND bidi controls there, capped by code point.-- Never silent about what a viewer gets. Where local terminals are not tmux (Windows' session host, tmux- off or missing, Zellij) a viewer can watch only a terminal the app has OPEN (there is no read-only- client to spawn): the create dialog says so, and a refused join turns the chip amber `LIVE · 1+- Never silent about what a viewer gets. The session host's read-only client is a negotiated+ `watch-attach` attachment (no claim, no pause ticket, host refuses its writes, never spawns, never+ indexed as the node's session; an older host means refused, never an ordinary attach). Where local+ terminals are neither (tmux off or missing, Zellij, an older host) a viewer can watch only a terminal+ the app has OPEN (there is no read-only client to spawn): the create dialog says so, and a refused join turns the chip amber `LIVE · 1waiting` ("Viewers are waiting — open this terminal in nodeterm…"). The stream is the owner's tmuxCLIENT's output, so its session chooser or a session switch reaches viewers; the warning names it.A controller's input that does not reach the pane is reported (`watch:control {controlling,diff --git a/docs/live-links.md b/docs/live-links.mdindex b844a39d2..de0736e65 100644--- a/docs/live-links.md+++ b/docs/live-links.md@@ -244,9 +244,14 @@ A keyframe is `PtyManager.captureVisible(sessionId)`: **the visible screen, nevewhat makes it visible-only);- **SSH:** the same over the project's ControlMaster (`remoteCaptureVisibleArgs`), again without the`-S -200` the existing remote builder always adds; proven under a real `/bin/sh`;-- **Windows session host and the direct Windows pty: none.** `sessionHostCapture` returns ~200 lines of- scrollback, not the visible screen; a visible-only read needs an additive, negotiated session-host- command (a follow-up). Never history instead. **A plain shell with no tmux: none.**+- **Windows session host:** the host's negotiated `captureVisible` (`sessionHostCaptureVisible`) — the+ visible rows of its headless emulator's ACTIVE buffer, the viewport cursor, and `altScreen` from that+ buffer (no tmux client sits between the pane and the stream, so the pane's buffer IS the stream's;+ this is the one route whose capture sets `VisibleCapture.altScreen`, and the link host prefers it over+ the join's). It keeps the private-mode tail (bracketed paste, application cursor keys, mouse) a+ mid-stream viewer never saw. A host from a build before the feature answers nothing, so `unavailable`;+ never the ~200-line scrollback `capture` in its place.+- **The direct Windows pty: none.** **A plain shell with no tmux: none.**- **A Zellij node (the optional local backend, `settings.sessionBackend`): none.** Its Session is marked`tmuxBacked` like a tmux one, but there is no tmux session to capture, so `visibleCaptureRoute` routesit to none rather than aiming the tmux socket at it. A viewer still co-attaches to a Zellij painter@@ -911,16 +916,22 @@ carry it to teammates and the canvas authority would write it into the git-shareuntouched. **Availability ischecked before the Pro gate** (`liveLinkUnavailable` then `requireProOr`), so a Server Edition or relaytab never sees an Upgrade dialog; an unavailable row is disabled with its reason, never hidden.-- **Desktop where local terminals are not tmux** (Windows' session host; tmux switched off or missing;- the Zellij backend): there is no watcher client of its own, so a viewer can co-attach only to a- terminal this app has OPEN (mounted, or parked) — after a restart, for a background project or an+- **Windows' session host** has its own read-only client: a join-only create (a watcher, or a hosted-relay+ viewer) for a node this app does not hold asks the host STRICTLY (`hasSession`; an unanswered probe+ refuses) and joins through `watch-attach` — an attachment with no geometry claim and no pause ticket,+ whose writes and resizes the host refuses and which never spawns. It is never indexed as the node's+ session, so an owner opening the node gets its own typing attachment. A host from an older build+ lacks the feature: refused (`join-only`), never an ordinary attach that would cast the viewer's size.+ The create dialog's note follows `tmuxStatus().persistence.watchJoin` (the CONNECTED host's answer).+ Control typing needs the node open (a watch attachment has no typing path).+- **Desktop where local terminals are neither tmux nor such a session host** (tmux switched off or+ missing; the Zellij backend; an older host): there is no watcher client of its own, so a viewer can+ co-attach only to a terminal this app has OPEN (mounted, or parked) — after a restart, for a background project or anoffscreen-released node, viewers wait. This is said, never silent (R63): the create dialog states itbefore the link exists (`watchableOnlyWhileOpen`, from the local core's `tmuxStatus().persistence`; anSSH project's node is served by the host's tmux and gets no note), and while a viewer's join isrefused the chip turns amber (`LIVE · 1 waiting`) and its title and the popover say "Viewers are- waiting — open this terminal in nodeterm to let them watch." The fix is a session-host watcher join- (an additive, negotiated attach-only subscribe with no size vote, beside the visible capture): a- follow-up.+ waiting — open this terminal in nodeterm to let them watch."- **The LIVE chip** (`LiveLinkChip`, one component): node header (beside `PresenceChips`), kanban card,card modal header, sessions-sidebar row. `● LIVE`, `● LIVE · 2`, `LIVE · 3 · 1 typing` (someone typedin the last 4 s; the title names who, quoted), amber `LIVE · offline` (reconnecting), amber `LIVE · 1@@ -989,8 +1000,8 @@ Found while building it:per viewer at a 2.7 MB/s flood (measured), ≤ 10 viewers per link.- **Text typed with no escape after a co-attach join lags** until the next escape or the 2 s keyframe(R23): the mid-stream filter swallows it by design.-- **On a backend with no visible capture** (Windows session host, direct Windows pty, plain shell,- Zellij) a throttled viewer shows gaps until the app repaints (R36). A Zellij node with no painter held+- **On a backend with no visible capture** (a session host from an older build, direct Windows pty,+ plain shell, Zellij) a throttled viewer shows gaps until the app repaints (R36). A Zellij node with no painter heldin this process (a closed project, after a restart) cannot be watched at all until one is.- **A single capture failure on a tmux/SSH backend is treated as "no capture"**: no repaint until thenext keyframe or the app's redraw. Retrying there would stall the stream for good on the backends that@@ -1005,9 +1016,9 @@ Found while building it:agents included) or a session switch (`C-b (` / `)`) reaches every viewer. It is the owner's ownaction, shown on the owner's own screen too, and the create dialog's warning says so. Following`#{client_session}` and treating a switch as a lifecycle event is a possible follow-up.-- **Windows, and any machine whose local terminals are not tmux:** a link to a terminal that is not- open in the app cannot be watched until it is (Surfaces, above). Said, never silent; the session-host- watcher join is the follow-up.+- **Any machine whose local terminals are neither tmux nor a `watch-attach` session host:** a link to a+ terminal that is not open in the app cannot be watched until it is (Surfaces, above). Said, never+ silent. On the session host, Control typing still needs the node open.- **A tmux < 3.2 host cannot be watched** (fail closed, "waiting").- **After a run whose index was missing, unreadable or corrupt, node-gone waits for the next launch**(R44/R54): a link to a node deleted in that run lives until its expiry (≤ 24 h) — an Unlimited linkdiff --git a/docs/windows-session-host.md b/docs/windows-session-host.mdindex 5abf4f1de..7e67a8040 100644--- a/docs/windows-session-host.md+++ b/docs/windows-session-host.md@@ -147,6 +147,14 @@ long-lived connection (no positional-FIFO fragility, unlike this app's tmux cont| `detach` | a client's own `tmux detach-client` | full || `listSessions` | `list-sessions -F '#{session_name}'` | full || `ping` | (liveness probe used during the startup race) | full |+| `attachExisting {watch: true}` | `attach-session -E -f ignore-size,read-only` (a live link watcher's client) | feature `watch-attach`: subscribes with NO geometry claim and no pause ticket, refuses `write`/`resize` from that connection, never spawns; on an already-attached connection it withdraws the claim (its last voting subscriber left) |+| `captureVisible` | `capture-pane -p -e` + `display-message '#{cursor_x} #{cursor_y}'` | feature `captureVisible`: visible rows of the ACTIVE buffer only (never history), viewport cursor, `altScreen` — a live link's keyframe |+| `paneCwd` | `display-message -p '#{pane_current_path}'` | feature `paneCwd`: the cwd the pane last REPORTED (OSC 7 / 9;9 / 633, parsed by `cwd-report.ts`), null until one arrives — never the spawn cwd |++The last three are **negotiated at hello** (`SESSION_HOST_FEATURES`) like `geometry`/`shutdown`: the+client never sends one to a host that did not advertise it (an older, long-lived host keeps serving+everything else and is never replaced for them). Without them: a live link viewer of a node this app+does not hold is refused (`join-only`), there is no keyframe (R36), and `paneCwd` is null.**Not implemented — deliberately out of scope for this pass:**@@ -680,6 +688,13 @@ you chose and why") rather than an oversight.live session for every healthy viewer forever.- **Windows named-pipe/unix-socket ACL is not independently audited** — see "Auth" above; thebearer token is the enforced boundary.+- **`paneCwd` only knows what the shell reports.** pwsh, Windows PowerShell and cmd report nothing+ by default (no OSC 7 / 9;9), so a plain Windows shell's relative file links still resolve against+ the launch cwd only; agent CLIs and shell integrations that emit OSC 7 / 9;9 / 633 work. No prompt+ hook is installed for them (it would rewrite the user's prompt); an opt-in one is a follow-up.+- **Control typing into a session-host node needs the node open** in this app: a viewer of a node+ nobody holds rides a read-only `watch-attach` attachment, which has no typing path (the host+ refuses its writes, and keys must not be retyped as a framed `sendKeys` paste).- **No equivalent of `paneOwner` / `bracketPasteRequested` / a standalone `paneCursor` query** —see the protocol table's "Not implemented" note. Nothing in this app currently calls these for asession-host-backed node (they are gated behind `this.tmuxPath` being set), so nothing is