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(windows): live links on the session host

review1162c02cf7ea
diff --git a/CLAUDE.md b/CLAUDE.md
index 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`**. Inv
viewer 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 every
join 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). A
viewer 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 the
web 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 · 1
waiting` ("Viewers are waiting — open this terminal in nodeterm…"). The stream is the owner's tmux
CLIENT'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.md
index 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, neve
what 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` routes
it 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-share
untouched. **Availability is
checked before the Pro gate** (`liveLinkUnavailable` then `requireProOr`), so a Server Edition or relay
tab 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 an
offscreen-released node, viewers wait. This is said, never silent (R63): the create dialog states it
before the link exists (`watchableOnlyWhileOpen`, from the local core's `tmuxStatus().persistence`; an
SSH project's node is served by the host's tmux and gets no note), and while a viewer's join is
refused 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 typed
in 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 held
in 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 the
next 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 own
action, 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 link
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 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; the
bearer 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 a
session-host-backed node (they are gated behind `this.tmuxPath` being set), so nothing is