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.
Windows session host
What this is: a tmux-equivalent session-persistence backend for Windows (and any other
platform where a real tmux cannot be found), so closing the app — or the app crashing — no
longer kills every running terminal and every agent CLI mid-task. It is a standalone,
long-lived Node process that owns the real PTYs and outlives the Electron app.
This document describes the Windows desktop implementation. It does not embed Microsoft Windows Terminal, and it does not change the Server Edition or mobile companion.
Selected automatically, per session, in this order:
Windows + tmuxEnabled → session host (this document)
POSIX + real tmux found → tmux (unchanged)
POSIX + no tmux, tmuxEnabled → session host (this document)
tmuxEnabled off → plain shell (no persistence)
Stock Windows provides no native tmux, and Windows tmux-compatible binaries do not implement the
Unix tmux control and console semantics this application relies on. The session host is therefore
the authoritative Windows persistence backend even when a tmux.exe appears on PATH. On
macOS/Linux nothing changes: a real tmux installation remains preferred there.
Why not just port tmux's approach
tmux does not exist on Windows, full stop — there is no binary to bundle. The session host is a from-scratch analogue built out of three pieces this codebase (or the wider Node ecosystem) already has good building blocks for:
- A real PTY per session —
node-pty, the same dependency the rest of the app already uses. - A server-side terminal emulator per session —
@xterm/headless+@xterm/addon-serialize, so the host can answer "what does this screen currently look like" without a human ever having looked at it. This is the piece tmux gets from its own C implementation; here it's the same xterm.js core the renderer itself uses, just running headless in Node. - A tiny bespoke IPC protocol (newline-delimited JSON over a local named pipe / unix socket) instead of tmux's binary control-mode protocol, because there is no existing "attach to a named session and stream its output" primitive to reuse on Windows.
Architecture
Electron main process Session-host process (standalone, detached)
┌─────────────────────┐ ┌──────────────────────────────────────────┐
│ PtyManager │ │ net.Server (named pipe / unix socket) │
│ spawnSession() │ local IPC │ ── per-connection: hello + dispatch │
│ └ SessionHostPty ──┼─── (JSON lines) ─┼─→ Map<name, HostSession> │
│ (IPty-shim) │ │ ├─ node-pty IPty (the real process) │
│ │ │ ├─ TerminalEmulator (headless xterm) │
│ session-host-client │ │ └─ subscriber sockets (co-attach) │
│ (one connection, │ │ │
│ auto-spawns host) │ │ exits when its last session is killed, │
└─────────────────────┘ │ plus a grace window (see "Lifetime") │
└──────────────────────────────────────────┘
src/session-host/— the standalone process. Pure Node, no Electron dependency anywhere in this directory (verified: it does not even import../coreor../main). Bundled with esbuild (npm run host:build, mirroring the existingserver:buildscript) toout/session-host/host.cjs, withnode-ptykept external (native module — the same reasonserver:buildexternalizes it).src/core/session-host-client.ts/session-host-launcher.ts/session-host-backend.ts/session-host-pty.ts— the Electron-main-side client.src/corestays Electron-free (no-electron.test.ts); these files import onlynet/fs/cryptoand the pure protocol/paths modules.src/core/pty-manager.ts— the integration seam:Session.sessionHost?: booleanmarks a session-host-backedSession, and every call site that reaches pastsession.procto run a tmux CLI command directly (sendText,paneCommand,captureSession,captureSnapshot,snapshotScrollback,captureForResync, the final kill indestroySession,listNodetermSessions) gained oneelse if (!this.tmuxPath) { … session-host equivalent … }branch, in the same shape the existingsshRemotebranch already used.spawnSession()selects this backend between the tmux branch and the plain-shell fallback, and constructs aSessionHostPtyinstead of callingpty.spawndirectly.
Availability notice
pty:tmux-status retains its tmux-only available field and adds persistence: the
user's enabled setting and the discovered backend (tmux, session-host, or null).
Discovery does not start the host or certify runtime health. POSIX prefers tmux; Windows
uses the session host. A missing/errored status stays unknown, including over Server Edition's
WS bridge. Older peers without the field also remain unknown.
The desktop/browser banner warns when protection is disabled, absent, or unknown; Settings shows the same state and refreshes it after a setting change and periodically. The state is about new local terminals, not SSH/relay hosts or an upgrade of existing plain shells. An installer is offered only from a local project, so it cannot run on the selected remote host by mistake. Runtime session-host attach failures still use the terminal's existing error path; a bundle being present is not proof an individual session attached successfully.
Windows profile resolution
The profile catalog is a trusted desktop service. Its public API returns only a stable id,
display label, kind, availability, and an optional unavailable reason. Executable paths and argv
remain private. PtyCreateOptions.profileId crosses the desktop bridge; the trusted core validates
and resolves it immediately before either node-pty or the session host spawns a process.
Stable ids are auto, pwsh, windows-powershell, cmd, git-bash, custom, and one
wsl:<distribution> per installed WSL distribution. auto is the only profile allowed to search
down a precedence list: PowerShell 7, then Windows PowerShell, then %COMSPEC%/cmd.exe. An
explicit unavailable or malformed profile fails; it never becomes a different shell.
For WSL, distribution discovery parses the UTF-16/NUL-padded output of
wsl.exe --list --quiet. The selected distribution's own wslpath translates the Windows project
directory, after which launch keeps the structured wsl.exe -d <distribution> --cd <linux-path>
prefix and runs a trusted distro-side cwd guard before replacing it with the configured default
shell. The guard independently changes to the positional Linux path so a directory removed after
translation cannot silently open in /. Enumeration,
translation, and launch failures keep their real reason and perform no fallback spawn. A
distribution name containing spaces remains one argv element.
The profile id is a machine-local snapshot, not project content. terminalProfileId, legacy
custom shell, and advanced SSH execution values are removed from shared project files, portable
exports, and inbound canvas traffic. A shared file or peer can therefore neither inject argv nor
select a local executable. See
features/terminals/windows-shell-profiles.md.
Agent launches in a Windows-native shell (pty:execute-launch)
The renderer's agent launch line is POSIX source ('it'\''s', "$(cat '<file>')"). PowerShell
breaks on the apostrophe, Windows PowerShell 5.1 drops embedded double quotes before the CLI sees
them, and cmd.exe splits a single-quoted prompt into separate arguments. So a prompt-bearing
builtin agent node also carries a semantic data.launchIntent (shared/agents/launch-intent.ts),
bound to its exact typed line and never serialized. When the launch writer is about to type that
line into a local session-host pane on a win32 core, it calls pty:execute-launch instead
(renderer/terminal/launch-intent.ts → core/launch-intent-execute.ts): the core resolves the
agent executable against the session's spawn PATH (native image, then .ps1; a .cmd-only
install is refused), reads a --prompt-file itself (whitespace flattened to one argument, exactly
what "$(cat …)" yields in PowerShell), encodes argv for the dialect the HOST recorded for that
generation (launchDialect on the attach result; set at spawn only for pwsh/powershell/cmd),
and delivers through the host's exactly-once launch ledger.
Rules that keep this safe:
- Every other pane (tmux, SSH, Zellij, plain shell, Git Bash/WSL, any POSIX core) answers
unsupported-shellbefore anything is read, and the typed line is used, byte-identical. - A refusal made before the host is asked falls back to the typed line;
delivery-failed(or a lost reply) does NOT — the launch stays held for an explicit Run now, never typed twice. - Excluded from the intent (legacy line only): resumes, custom agents, launch-command overrides, per-node models, SSH nodes. A resume line holds only flag words and a validated id.
pty:execute-launchis host-only for relay peers (shared/host-control.ts).
The IPty-shim (why the integration is this small)
PtyManager's entire co-attach / flow-control / subscriber / park / reap machinery operates on
Session.proc, and only ever calls .onData(), .onExit(), .write(), .resize(), .pause(),
.resume(), .kill()/.destroy() on it — never .pid, never anything ConPTY/Unix-specific.
SessionHostPty (src/core/session-host-pty.ts) implements exactly that subset, backed by the
session-host connection instead of a real OS pty. Cast at the one construction site in
spawnSession() (as unknown as pty.IPty), it is otherwise indistinguishable from a real
node-pty IPty to every other line in pty-manager.ts — every subscriber, every flow-control
ticket, every park/reap decision keeps working unmodified.
The protocol
Newline-delimited JSON, defined in src/session-host/protocol.ts (imported by both sides — it is
the one module the standalone bundle and the Electron-main bundle genuinely share). Every request
carries a monotonic id; the host echoes it on the response, so replies self-correlate over one
long-lived connection (no positional-FIFO fragility, unlike this app's tmux control-mode client).
Verb (SessionHostRequest.cmd) |
tmux equivalent | Coverage |
|---|---|---|
hello |
(no tmux equivalent — auth handshake) | full |
attach |
new-session -A / attach-session |
full, plus a screen the tmux path never needed (see below) |
hasSession |
has-session -t <name> |
full (implemented; not on the hot create path — see below) |
write |
raw bytes on an attached client's stdin | full |
writeDetachedV1 |
send-keys -H into a released session (no client) |
full — additive; an older host answers unknown command and the write fails closed (never re-sent as sendKeys) |
terminateOwnerV1 |
kill -TERM -<foreground pgid> |
Windows shape — taskkill /T /F on the re-proven agent pid, never the console root (see below) |
resize |
ConPTY/pty resize + refresh-client -C |
full; each view claims a size, the app's grid follows its most recently active view (issue #914) |
pause / resume |
node-pty pause()/resume() |
full; per-viewer in core and per-connection in the host (first pause / last resume) |
sendKeys |
send-keys -l -- <text> (+ Enter) |
full — works with no attached client, exactly like tmux |
paneCommand |
display-message -p '#{pane_current_command}' |
approximated — see process-tree.ts |
capture |
capture-pane -p -e [-S -N] |
full, and strictly more (mode restoration — tmux's plain-text capture carries none) |
paneModesV1 |
(none — tmux owns the mouse itself) | additive: the pane app's mouse-tracking protocol, for relay scroll routing; an older host answers unknown command = "no mouse" |
killSession |
kill-session -t <name> |
full |
detach |
a client's own tmux detach-client |
full |
listSessions |
list-sessions -F '#{session_name}' — plus, with sessionDetails, list-windows/list-panes |
full; see "Observability" below |
ping |
(liveness probe used during the startup race) | full |
attachExisting {watch: true} |
attach-session -E -f ignore-size,read-only (a read-only viewer) |
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 — the phone's resume repaint |
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 hosted-relay viewer of a node this
app does not hold is refused (join-only), there is no visible-screen capture, and paneCwd is null.
Not implemented — deliberately out of scope for this pass:
paneOwner/ bracketed-paste detection (bracket_paste_flag) / `#{cursor_x} #{cursor_y}
#{cursor_flag} as a _separate_ query. These are real tmux features this app also uses (pty-manager.ts's paneOwner, bracketPasteRequested, paneCursor), but none of them are in the task's minimum verb list, and cursor position is already carried for free inside capture's output (SerializeAddonrepositions the cursor as part of its own serialization — see below), so a separate cursor query would be redundant for this backend specifically. A session-host-backed node simply never calls the tmux-only paths that use these (they stay gated onthis.tmuxPath`
being set, which it never is when session-host is selected).
- The tmux control-mode "shadow client" / shared background-write client
(
PtyManager.shadowAttach/shared). Session-host does not need an equivalent at all: unlike a tmux CLI command (a whole subprocess per invocation), every session-host verb is a stateless request over the ONE already-open connection, addressed by session name — the exact problem the shadow-client machinery exists to make cheap for tmux is simply not a problem here. See thesendKeys/paneCommand/capturerows above: none of them need an attached client. A raw background write to a RELEASED node (PtyManager.backgroundWrite, the tier tmux serves through a shadow) useswriteDetachedV1: verbatim bytes, addressed by name, no attachment. It is not gated onptyShadowClients(that switch governstmux -Cchildren) and is never retried — a lost reply may still have typed.
The seeding trap (read this before touching spawnNew/join/SessionHostPty)
CLAUDE.md's tmux section states the load-bearing rule for THAT backend: on a warm reattach, the renderer must seed nothing, because tmux's own attaching client repaints the screen by itself (the redraw arrives as ordinary PTY output, over the same channel as everything else). Writing into the buffer yourself on top of that is what produced black bands and duplicated screens in an earlier design.
The session host is not a painter. Attaching a new connection to an existing HostSession
does not make anything repaint itself — nothing writes fresh bytes into the pty on attach. Get
this backwards in either direction and you ship a visible bug:
- Seed nothing on this backend (copying the tmux rule verbatim) → the reattached terminal is blank until the next byte of real output arrives.
- Seed unconditionally on every backend → the tmux backend gets a duplicated screen on top of its own real redraw.
The fix is Session.proc.ready + PtyCreateResult.screen, used exactly the way the pre-existing
co-attach JOIN path (PtyManager.join()) already used screen for a same-process second
subscriber — this task did not have to invent a new field, only populate the existing one from a
new source:
SessionHostPty.readyresolves with{fresh, screen}from the SAMEattachround trip the constructor kicks off.fresh: true(cold start — nothing to paint) orfresh: falsewith ascreenstring reconstructed from the host's live headless terminal.spawnNew()awaitsready(afterspawnSession()returns) and foldsscreeninto thePtyCreateResultit hands back — the exact fieldjoin()already populates for a same-process co-attach.- A rejected
readyis a failed create, never a cold-but-working terminal. The provisional localSessionis detached and removed, queued output is cancelled, and the original error reaches the renderer. Racing creates wait behind that result instead of joining the provisional index entry; a detached relay receives a non-zero sink exit because its legacy API cannot return a promise. - The renderer needed zero changes.
seedPaint()(src/renderer/terminal/terminal-config.ts) already treats any non-emptyscreenon awarm-attachreplay as paintable (create-screen), regardless of whether it arrived via a co-attach join or a plain reattach — that generality already existed, unused by anything butjoin(), before this task. Verified by readingseedPaint's body rather than assumed.
Relay/mobile attach does not use that renderer create round trip: it asks
PtyManager.sessionExists() and captureSnapshot() before attachDetached(). Those two public
leaves must route through sessionHostHasSession / sessionHostCapture when tmux is absent. If
they fall back to the older tmux-only implementation, a live Windows-hosted agent is reported as
fresh and its phone mirror starts blank even though the session host still owns it.
Private-mode restoration (mouse tracking, bracketed paste, …)
A pane's cursor position and its DEC private modes (has the app running inside it requested mouse
tracking? bracketed paste? is it on the alternate screen?) are not visible in plain captured text.
tmux's own answer to this is PtyCreateResult.coAttachMouse / CO_ATTACH_MOUSE_SEQ — a hardcoded
mouse-enable sequence the renderer writes because tmux's capture-pane carries no mode
information at all, and this app always runs tmux with mouse on.
The session host does better, because @xterm/headless + @xterm/addon-serialize know the real
mode state:
- Verified, not assumed (read
SerializeAddon's compiled_serializeModes()innode_modules/@xterm/addon-serialize/lib/addon-serialize.jsrather than trusted the docs):serialize()'s output already restores application-cursor-keys, application-keypad, bracketed-paste, insert mode, origin mode, reverse-wraparound, send-focus, wraparound, the alt-buffer switch, AND the cursor position — all embedded directly in the returned string as ANSI escape sequences. - The one known gap:
SerializeAddondoes not emitCSI ?1006h(SGR extended mouse coordinates) even when mouse tracking is active — there is no separate field on the publicIModesAPI for it to read (mouseTrackingModeonly says which tracking protocol is on: none/x10/vt200/drag/any, not the coordinate encoding). Filled in explicitly byTerminalEmulator.serialize()insrc/session-host/terminal-emulator.ts: whenevermouseTrackingMode !== 'none',\x1b[?1006his appended by hand.
Because all of this rides inside the screen string itself (as real escape sequences the
renderer writes verbatim), PtyCreateResult.coAttachMouse is never set for a session-host
session — there is nothing left for that separate flag to carry.
Which ConPTY: node-pty's bundled one, inbox as the fallback
The restoration above only has something to restore if the modes ever reach an emulator. On
Windows 10 (the 19041 servicing line, 22H2 = build 19045 included) the OS inbox ConPTY does not
pass the DEC private mouse-tracking modes (?1000h/?1002h/?1006h) or the alternate screen
(?1049h) through to the terminal on its far side: it consumes them and repaints the screen in
place. So neither the host's headless emulator nor the renderer's xterm ever enters mouse-tracking
mode, xterm never forwards a wheel event to the pty, and — because ConPTY repaints rather than
scrolls — xterm's own scrollback stays empty. In a full-screen TUI (Claude Code with
/tui fullscreen) the wheel and the trackpad do nothing and earlier conversation is unreachable.
The canvas is not involved: the terminal container is already nodrag nowheel.
node-pty 1.1.0 ships a newer ConPTY (conpty.dll + OpenConsole.exe, from the Windows Terminal
project) and uses it instead of the OS one when spawned with useConptyDll: true. Both spawn sites
— the session host (src/session-host/session.ts) and the PtyManager's direct pty.spawn
(src/core/pty-manager.ts) — spread ONE helper, windowsConptySpawnOptions()
(src/core/windows-conpty-dll.ts):
- Where node-pty looks, exactly. Not
third_party/: the nativeLoadConptyDll(src/win/conpty.cc) loads<directory of the loaded conpty.node>\conpty\conpty.dll, andconpty.nodeis the first oneloadNativeModule(lib/utils.js) finds amongbuild/Release,build/Debug,prebuilds/<platform>-<arch>, each tried relative tolib/..thenlib/.. The helper walks the same list, stops at the firstconpty.node, and answers{ useConptyDll: true }only when BOTH files sit in itsconpty\subfolder. A DLL missing there is a THROWN spawn in node-pty ("Cannot find conpty.dll at …"), not a fallback, which is why the helper checks first. - Fail-open. Any other platform, a missing file, a resolve or fs error ⇒
{}— the inbox ConPTY, and spawn options byte-identical to before. It never throws. Off Windows it touches no file at all. - The files must be STAGED, because our build deletes them. node-pty's own post-install copies
third_party/conpty/<version>/win10-<arch>/intobuild/Release/conpty/, but our postinstall then runselectron-rebuild -f, i.e.node-gyp rebuild, whosecleanremovesbuild/. The rebuiltbuild/Release/conpty.nodeis the one node-pty loads, soscripts/stage-conpty-dll.mjsruns after electron-rebuild (postinstall andnpm run rebuild) and copies the two files back beside it (Windows only; x64 and arm64 — the arches node-pty bundles). Without it every Windows build would quietly run on the inbox ConPTY. - Packaging. The main process gets them through
asarUnpack(**/node_modules/node-pty/**). The session host's own node-pty copy (build.win.extraResources) is an allowlist, and now namesbuild/Release/conpty/conpty.dllandbuild/Release/conpty/OpenConsole.exe; the staged host runtime copiesresources/session-host/**recursively, so they reach it unchanged. - The native close path already handles both values: the Windows leg of
scripts/patch-node-pty.mjspatches theuseConptyDllbranches, andsrc/session-host/windows-conpty.tsreads_useConptyDllinstead of assuming one.
Unverified on a device (no Windows machine here): see "ConPTY selection — device checklist" below.
Output ordering, flow ownership, and geometry
@xterm/headless applies Terminal.write() asynchronously. A PTY data callback therefore does
not mean the emulator is ready to serialize that byte yet. HostSession.recordOutput() chains
those promises in arrival order, and every warm attach, capture, resize and final exit crosses the
same tail before it reads or disposes the emulator. Do not replace that with a fire-and-forget
void term.write(data): a relay/phone can then receive a warm snapshot missing output the host has
already observed, and an attach racing a pending write can get the same chunk once live and once in
its seed. The new socket joins the subscriber set only after the barrier and snapshot, which is
the other half of avoiding that duplicate.
That promise tail is also a memory boundary. Bytes accepted but not yet applied to xterm are
counted as UTF-8; at 4 MiB the host takes an emulator-flow ticket and pauses node-pty, then returns
only that ticket after the queue drains to 1 MiB. This ticket is independent from both explicit
renderer flow control and named-pipe backpressure. Likewise, a socket.write() returning false
takes one transport ticket for every session subscribed on that socket, and only that socket's
drain returns it. A drain must never cancel a renderer pause or an emulator backlog.
Ownership is preserved at both aggregation layers. Every in-process SessionHostPty is a distinct
pause and geometry owner even though all of them share one SessionHostClient socket. The client
sends a pause only on the local 0→1 edge and a resume only on 1→0; the host then combines that one
connection-level ticket with other process sockets. Geometry follows the same shape: the client
reduces its live view claims, the host reduces all socket claims componentwise, and it resizes the
PTY and headless terminal before serializing a warm screen. Detaching a viewer recomputes the grid.
The client's reduction is "most recently active", not "smallest" (issue #914). Under tmux a
phone mirroring a node is its own tmux client, and tmux's default window-size latest gives the
window to whichever client was active last — so a phone that dismissed its keyboard got its rows
back. Here the phone (a relay-served SessionHostPty) and the desktop node share ONE client
socket, and the old componentwise minimum held the phone to the desktop node's rows with nothing on
screen saying why. latestClaimSize (core/pty-size.ts) now picks the claim with the highest
recency: an attach, a claim that CHANGES (a re-fit to the same size does not count, or every fit
would steal the session), and a write that is not a terminal report (core/terminal-reports.ts —
every attached xterm answers a DA/CPR/OSC query, and counting those would hand the session to
whoever answered last). Three rules come with it:
- A viewer that cannot adapt is a ceiling. Every renderer view renders the size it is told
(
pty:size: letterbox a smaller grid, clip a larger one, as a tmux client does). A pty wider than the phone's screen would wrap into garbage there, or — rendered at the pty's size — be clipped to its left ~45 columns, so a relay sink isboundingunlesspty.attachcarriedresizedFrames: true, and the chosen size is clamped componentwise to every bounding claim. The iOS app keeps it that way on purpose: it readsOP.Resizedonly to explain the empty band ("Sized to another screen") and to offer "Fit this screen", which re-claims the size with a rows+1 → rows wiggle (an unchanged claim is not activity). Because the phone clears that hint every time it sends a size, the host ANSWERS every sink report, unchanged or not — the sink'ssinkShownis forgotten on each report. - The pty's real size flows back to every viewer.
SessionHostPty.onSize→PtyManagerapplyBackendSize→pty:sizeto each view whose xterm is not already at it, andOP.Resized(payload =OP.Resize's, 2× uint16 LE) to the relay sink. A session-hostSessiononly VOTES inapplySize; its views are corrected from the backend's answer, which the client sends after every vote, changed or not. - The host's
geometrypush is negotiated at hello, never assumed.hellocarriesfeatures: ['geometry']; the host answers with the subset it speaks and pushesgeometryframes (and addsgeometryto attach replies) ONLY on connections that asked. This is not caution: an older client treats every push frame that is notdataas an EXIT, so a geometry frame sent to it retires a live session on the first resize (session-host/geometry-host.test.tspins it against the real bundled host). Against a host without the feature the client reports its own applied size, which is exact while it is the host's only connection. Across connections (two apps on one host) the HOST still takes the componentwise minimum.
The same name is also a generation boundary. Data and exit events contain a session name but no
generation id, so an exiting HostSession remains registered until its queued output, final exit
broadcast and disposal complete. A same-name attach waits on that retirement promise before it can
spawn a replacement. The old socket may therefore see its old exit before the new attach response,
but the replacement can never receive an indistinguishable delayed exit from its predecessor. The
whole wait/inspect/create decision is serialized per session name; otherwise two concurrent attach
requests can both wake from the same retirement promise, both observe the empty slot, and spawn two
PTYs before either continuation publishes its choice. Grace-exit cancellation is part of that
atomic claim and runs after the wait, so it also cancels any new empty-host timer retirement just
scheduled before the replacement was created.
Reconnect (a dropped client connection is not a dead session)
Sessions live in the host process, not in the client. If the Electron-main-side connection drops
(a transient IPC hiccup — not the host dying), SessionHostClient begins bounded automatic
reconnect attempts while any desired subscriber remains; an idle viewer does not stay frozen until
some later keypress. Establishing the socket includes an awaited restoration barrier. It replays
every still-live attachment with the local effective geometry and aggregate paused flag before
the request that triggered the reconnect is allowed onto the wire. The host applies that pause
before snapshot or live subscriber activation, so output cannot leak through the reattach window.
Any returned screen is delivered through the ordinary onData path as a full-buffer replacement:
CSI 3J clears scrollback, CSI 2J clears the viewport, home resets the cursor, and the serialized
screen restores the authoritative cells and DEC modes. Omitting CSI 3J merely clears the visible
page and duplicates xterm scrollback after every reconnect. Reusing the ordinary data channel keeps
this recovery local to the session-host client instead of adding a separate renderer resync IPC.
Restoration is never fire-and-forget. A delayed replay attach cannot overtake hasSession, write,
or a confirmed killSession and resurrect the deleted name afterward. If a desired resume, detach,
or replay acknowledgement is transport-ambiguous, the client destroys that socket so the host's
close handler releases all connection-owned tickets, then reconnects and replays only the still-live
desired state. A final unsubscribe racing an in-flight attach schedules a compensating detach after
the attach settles, preventing a ghost subscription.
The hello hand-off owns named connect/data/error/close listeners. It removes only those
listeners, installs the production frame listener, and then resolves the connection promise. Never
restore broad removeAllListeners('data') cleanup here: the original ordering installed the
production listener and immediately deleted it, so all real responses disappeared while the socket
still looked connected.
An initial attach registers its local subscriber before sending because startup output may race
the response. If the request rejects, it rolls back only that subscriber and its own remembered
options; a concurrent co-attach remains intact. Empty capture and already-absent kill are confirmed
host responses, while transport rejection remains unknown and propagates. That distinction keeps a
failed snapshot dirty for retry and prevents deletion from claiming an unconfirmed persistent
process is gone.
The same truth boundary reaches the renderer. pty.destroy is an acknowledged request on both the
Electron preload bridge and the Server Edition WebSocket bridge. Canvas, sidebar, project, and
agent-control deletion paths remove local nodes and recovery state only after the backing kill is
confirmed; validation, rate-limit, and transport failures keep the node present and retryable.
A provisional attach is not a session
An attach is provisional until the host has authenticated the connection and returned the
correlated successful response. PtyManager does not index that shim, report it as persistent, or
expose it to subscribers before SessionHostPty.ready resolves.
If the attach is rejected, times out, or the transport fails:
- the provisional shim is destroyed and never enters the persistent-session index;
- queued bytes and a late exit from that rejected shim are ignored;
- every caller coalesced behind the same in-flight create receives the real attach failure;
- failed subscriber registrations are rolled back, so reconnect cannot replay a ghost attach;
- capture or kill transport uncertainty remains an error rather than being read as absence; and
- no plain shell or different profile is spawned as a substitute.
This is deliberately fail-closed. A non-persistent fallback carrying the same node identity would look healthy while losing the one property this backend promises, and could run a local command in the wrong shell or directory.
The hello hand-off has an equally strict ownership boundary. The handshake installs named
connect/data/error/close listeners, accepts only the response carrying its captured hello
request id, removes only those listeners, and then installs the production frame listener before
resolving the connection promise. Never restore broad removeAllListeners('data') cleanup here:
the original order installed the production listener and immediately deleted it, so the first
attach response and every later frame disappeared while the socket still looked connected.
An initial attach registers its local subscriber before sending because startup output may race
the response. If the request rejects, it rolls back only that subscriber and its own remembered
attach options; a concurrent co-attach's state is left intact. Capture and kill preserve the same
failure distinction across reconnects: an empty capture and an idempotently absent kill are both
confirmed {ok:true} host responses, while a transport/request rejection remains unknown and is
propagated. That propagation is what lets the periodic snapshot keep its dirty bit for a retry and
what prevents a delete from claiming a persistent process is gone when the host never confirmed it.
The hello hand-off has an equally strict ownership boundary. The handshake installs named
connect/data/error/close listeners, accepts only the response carrying its captured hello
request id, removes only those listeners, and then installs the production frame listener before
resolving the connection promise. Never restore broad removeAllListeners('data') cleanup here:
the original order installed the production listener and immediately deleted it, so the first
attach response and every later frame disappeared while the socket still looked connected.
An initial attach registers its local subscriber before sending because startup output may race
the response. If the request rejects, it rolls back only that subscriber and its own remembered
attach options; a concurrent co-attach's state is left intact. Capture and kill preserve the same
failure distinction across reconnects: an empty capture and an idempotently absent kill are both
confirmed {ok:true} host responses, while a transport/request rejection remains unknown and is
propagated. That propagation is what lets the periodic snapshot keep its dirty bit for a retry and
what prevents a delete from claiming a persistent process is gone when the host never confirmed it.
Staged host runtime (issue #829, step 3)
A host launched as a hard link of nodeterm.exe inside the install directory maps the installed
executable, its DLLs and resources.pak, so the installer cannot replace them while it runs. On
macOS/Linux the sessions live in tmux, a separate binary, and survive an update; the staged runtime
gives Windows the same property.
What happens. In a packaged Windows build, before the app spawns a host it stages
(src/core/session-host-runtime.ts) a private copy of the runtime into
%LOCALAPPDATA%\nodeterm\session-host\<app version>-<fingerprint>\
nodeterm-sessionhost-v2.exe (nodeterm.exe, renamed)
*.dll, icudtl.dat, resources.pak, snapshot_blob.bin, v8_context_snapshot.bin, locales\
resources\session-host\host.cjs + node_modules\node-pty\…
nodeterm-runtime.json (marker: file list, sizes, SHA-256)
and launches the host from there. The fingerprint hashes every source file's path, size and mtime,
so a reinstall of the same version with different bytes gets its own directory. app.asar is not
copied (the host never reads it).
The file set is not measured. It was written on Linux and is the conservative set an
ELECTRON_RUN_AS_NODE process can plausibly touch: icudtl.dat is required (Node's ICU data);
resources.pak was measured open by a running host in #829; the DLLs cover load-time and delayed
imports; locales\ covers resource-bundle initialisation. The per-machine proof is the smoke run
below. Device checklist item 1 measures the real set so it can be pruned.
Never a half-staged directory. Files are copied into .staging-<uuid> beside the target, each
copy is re-read and compared by SHA-256 to what was read from the install directory, and the copy is
smoke-run once: nodeterm-sessionhost-v2.exe -e … with ELECTRON_RUN_AS_NODE=1 must load,
require its own node-pty and exit 42. Only then is the marker written, and the directory is
published by one renameAtomic. A directory without a valid marker (or whose files no longer have
their recorded sizes) is moved aside and restaged, never launched. Two app processes staging the
same version at once both succeed: the second rename loses and adopts the first one's directory.
A new image name. Uninstallers already in the field match nodeterm.exe and
nodeterm-session-host.exe machine-wide by name; the staged host runs as
nodeterm-sessionhost-v2.exe so none of them mistakes it for something that blocks them.
Fail-safe. Every staging failure (no %LOCALAPPDATA%, a missing required file, disk full, a
failed hash, a smoke run that does not answer 42 within 60 s — STATUS_DLL_NOT_FOUND, an AppLocker or
WDAC policy blocking executables under the profile) falls back to the legacy launch: the hard link
in the install directory, then nodeterm.exe itself. A staged host that dies within 10 s with an
exit code other than the host's own 0/1 also falls back, and staging is not offered again for
the rest of the app run. The legacy host still blocks the installer, so the preflight below still
protects the install. The first launch of a new version waits at most 45 s for staging (copy,
hashing, smoke run; usually a few seconds, longer behind an antivirus scan); past that the host is
launched the legacy way and the finished copy serves the next launch. Staging progress and failures
are appended to <userData>\session-host.log with an [app] tag.
Old copies. After staging, copies other than the current one are collected — fail-closed: only
when a Win32_Process query SUCCEEDS, no nodeterm-sessionhost-v2.exe process has an unreadable
path, nothing runs from under that directory, the directory is older than 10 minutes, and renaming
it aside succeeds (Windows refuses while an image inside is mapped). A failed query deletes nothing.
A host started by an older version therefore keeps its copy for as long as it runs; once it exits
(30 s after its last session), the next app launch removes that copy. Disk use: about 250 MB per
version, normally one or two versions.
Versions talk to each other. There is one host per user-data directory, whichever runtime
started it. A newer app connects to a host started by an older staged runtime through the existing
negotiation: the state file's protocol version (v1 or v2 accepted) and the hello feature list
(SESSION_HOST_FEATURES, e.g. geometry). New sessions go to that host as long as it is
compatible; it exits by itself once it empties, and the next host is launched from the current
version's copy. The rule for every future change: the host protocol is additive-only — a new
command or push frame is negotiated at hello, never assumed. An operation an older host cannot
perform is refused with SessionHostProtocolCompatibilityError, which tells the user why. A host
whose protocol version the app does not accept at all is left running and the connect fails with
that reason — an app never kills a host to replace it.
Not covered. A dev checkout (electron-vite dev) and an asar-resolved bundle keep the legacy
launch. Server Edition and macOS/Linux are unaffected (tmux).
Windows updates and uninstalls
A host launched the legacy way (a hard link inside the install directory, or nodeterm.exe itself)
maps the installed Electron executable and its DLLs. Its separate hard-link name makes it
identifiable; it does not make the install directory safe to replace. Closing the app alone
deliberately leaves the host and its sessions running (#829). A host running from its staged
runtime (above) maps nothing in the install directory and does not block an update or an
uninstall: the preflight matches it neither by name nor by path, and the old version's uninstaller
does not know its name. Updating from a version that predates the staged runtime still meets that
version's legacy host once.
The uninstaller leaves %LOCALAPPDATA%\nodeterm\session-host in place, because a staged host may
still be running from it and the uninstaller never stops a host. docs/uninstall.md says how to
remove it afterwards.
The NSIS install/uninstall preflight now refuses to proceed while the app or host is running from
any installation, or a process runs under the installation path prefix. It replaces electron-builder's
automatic process termination, including
its silent/--updated path. Cancel leaves sessions alone. Retry performs a fresh, read-only process
query. A failed query (including an inaccessible nodeterm process with no executable path) blocks
instead of guessing. Silent installation returns a nonzero exit code, without a dialog or kill.
The query uses Windows PowerShell with a child-process-only execution policy; no persistent policy
or trust setting is changed. Group Policy restrictions still cause a safe refusal.
This is deliberately conservative: an old uninstaller may use a machine-wide name match or a path prefix without a directory boundary. Another installation (even a sibling directory whose name begins with this installation's name) can therefore block an update. The new preflight must cover those legacy targets before invoking the old executable; it never stops them on your behalf.
The in-app way (nodeterm with the shutdown host feature): open the command palette
(Ctrl+K) → Prepare for update…, or the button on the update card. When the running host is the
staged copy, the dialog leads with Quit nodeterm (sessions keep running) — quit, including from
the system tray, then run the installer; Stop all sessions instead… is the secondary path. A
host whose location cannot be determined is treated as blocking. Otherwise it:
- lists every session the host holds — every project, closed ones too — and waits while any agent is working or waiting for your answer (each listed with a Go button; Check again when it is done);
- asks each idle agent whose terminal is open on the canvas to exit normally (
/exit,/quit; Gemini's bare/quit, never--delete) so its conversation is saved, and reports any that did not; - shows what will still stop — shells and anything running in them (unsaved work there is lost), agents it could not exit — and asks you to confirm (Cancel is the default);
- sends the host its
shutdowncommand: the host ends every session with its ordinary kill path, replies, removes its state files and exits. nodeterm confirms the process is gone, then quits (optionally opening the download page).
Canvas nodes are kept; on the next launch every terminal cold-starts and agents resume with
--resume where their CLI and saved history allow. If the host cannot end a session it says which
and keeps running — nothing is quit. A host started by an older nodeterm does not have the
command; the dialog then shows the manual steps below. nodeterm never kills the host process
itself. The installer's own refusal is unchanged.
To update by hand (older host, or the in-app flow did not finish), while keeping your saved canvas:
- Cancel the installer and reopen nodeterm if you already quit it. Save work in every local terminal and agent, including closed/other projects and sessions accessed from a phone. Let active tasks finish, then use each program's normal exit command and exit its shell. Leave the canvas nodes in place. Do not use Sessions → End session or delete nodes to prepare for an update: those actions remove nodes, rather than just stopping their processes.
- Quit nodeterm normally so workspace changes are saved and it cannot start replacement sessions. Wait at least 30 seconds after the last shell exits for the empty host to shut down naturally. Quitting the app alone does not empty the host; a host with sessions will remain running.
- If the host remains, keep the installer cancelled. In Windows Task Manager's Details view,
verify the user and executable path of
nodeterm-session-host.exefor this installation. After saving work and accepting that every terminal/agent process owned by that host will stop, end only that verified host. This is a manual process shutdown, not a graceful agent exit, so complete step 1 first. Do not use a machine-wide name-based kill. If the host uses the fallback namenodeterm.exe, verify its identity/path rather than guessing which process to end. Another Windows user's host requires that user's decision. - Run the installer from Downloads, outside the installation directory, or Retry its preflight. Other nodeterm installations/users must prepare their own sessions too if they block the check. Do not reopen the app or start sessions while installation is in progress.
Stopping the host after quitting leaves saved node metadata (positions, groups, agent/session
identities) and existing closed-session history in place; it does not call the node-deletion path
or add deletion entries to closedSessions. Reopen nodeterm after installation to use those nodes.
This is cold recovery, not preservation of live processes: shell jobs and unsaved terminal state
are lost. An agent can resume only when its harness supports resume, nodeterm has saved a valid
conversation id, and the matching account's conversation history is still available. A saved node
alone does not guarantee resume, restore an in-flight task, or recover unsaved work.
New installers run this check before invoking the previous version's uninstaller. Already shipped
installers/uninstallers cannot be patched retroactively; use the same preparation steps for them.
This is a safe refusal and manual recovery path, not live host migration. A staged host
(0.4.1 and later, running from %LOCALAPPDATA%\nodeterm\session-host) maps none of the installed
files, so it does not block the installer and its sessions survive the update — quitting nodeterm
(from the tray too) is enough; device-verified across 0.4.1 → 0.4.2 → 0.4.3 in #829, all sessions
reattached warm. Only a legacy hard-link host inside the installation must be stopped first. A
process could still start after the preflight; it is not an installation-wide launch lock.
Unattended runs (silent, or the app's own --updated handoff) wait up to about 30 seconds for
nodeterm to finish exiting before refusing; "could not verify" (exit 20) still refuses at once. If
an --updated install still finds nodeterm running, it writes
%LOCALAPPDATA%\nodeterm\update-failed.json, restarts the installed version, and quits; the app
logs the failure on its next start.
Server Edition has no NSIS updater and is unchanged. Mobile/relay clients must expect a disconnect when the user deliberately ends desktop sessions; they cannot authorize an update shutdown. Real Windows per-user/all-users upgrades, old uninstallers, PowerShell policy variations, and phone reconnection still require device verification (fixtures do not prove file-lock behavior).
Lifetime
Mirrors tmux's server lifetime rule as closely as a different OS allows:
- Spawned detached, unref'd,
stdio: 'ignore',windowsHide: true(session-host-launcher.ts) — survives the spawning app process exiting entirely. - In a packaged Windows build the binary is the staged runtime's
nodeterm-sessionhost-v2.exeoutside the install directory (see "Staged host runtime"), so a host also outlives an update of the app; the legacy hard link is the fallback. - In a packaged app,
process.execPathis the Electron binary itself (there is no separatenodeexecutable to shell out to), so the child is spawned withELECTRON_RUN_AS_NODE=1, which tells Electron to run as a plain Node process with no Chromium/BrowserWindow machinery. Harmless on a real Node binary too (dev mode): unrecognized, ignored. - A client disconnecting detaches only — the underlying
node-ptyprocess, and theHostSessionholding it, are completely untouched. This is the entire point. - The app quitting detaches every client (the OS closes the sockets; the host's own
'close'handler removes that socket from every session's subscriber set and returns its pause ticket) and leaves the host running.PtyManager.killAll()was NOT touched — it already never kills tmux sessions, and it correctly does nothing to session-host sessions either (no code path in it reaches this backend at all). - The host exits when its last session is killed (
killSession, or a session's own pty exiting naturally with nothing else left), plus a 30-second grace window (GRACE_EXIT_MSinhost.ts) so an app restart that briefly closes every node does not tear down a host about to be handed a fresh session moments later. A host that never receives a single realattachalso eventually exits via the same grace timer, armed at boot. - Startup race (two app instances launched at once, or two windows racing a lazy first
connect): both processes may spawn a host. Exactly one may create the state file exclusively
(
fs.openSync(statePath, 'wx')); the loser polls that file (bounded, ~1.5s) waiting for the winner to finish writing{pid, endpoint, tokenPath, …}and answer a realhello, then exits quietly. A state file that resolves to nothing alive within that window is treated as stale (a previous host crashed mid-startup) and reclaimed. The same "connect first, only spawn if that fails" shape is whatSessionHostClient.doConnect()does from the app side, so a host from a previous app run is found and reused rather than duplicated. The winning state publication uses a PID+counter temp path and a bounded retrying atomic rename (session-host/state-file.ts, kept local so the standalone bundle does not importsrc/core). A fixed<state>.tmplets a stale-lock reclaim collide with another publisher, and a bare rename loses startup when a Windows scanner briefly holds the destination open. Binding the pipe/socket is not the success boundary: token write and atomic state publication must both finish. If either fails, the host closes its listener, destroys any socket from that pre-publication window, removes its owned token/state/endpoint, and exits nonzero. This catch is explicit because the daemon'suncaughtExceptionhook is diagnostic and suppresses Node's default fatal exit; letting publication throw into it creates an undiscoverable orphan host. OnlyENOENTmeans an ownership file is absent. Unreadable, directory, malformed, and empty-token observations fail closed without reclaiming or launching a competing host. The client also requires the state file's exact protocol version before hello; because the host outlives app upgrades, silently connecting a version-2 client to a version-1 host would lose atomic pause and geometry restoration.
The spawned program follows the same resolver as a direct local PTY. With no explicit program and
an empty settings.defaultShell, Windows selects PowerShell 7, then built-in Windows PowerShell,
then COMSPEC/cmd.exe; the host must never substitute POSIX-only bash there.
Auth — bearer token, never on argv
crypto.randomBytes(32) generated at host start, written to <userData>/session-host.token with
mode 0600, read by every client before its first request and sent in a hello frame. Every
other request is refused (unauthorized, socket closed) until hello succeeds.
This repository has a measured security incident from putting a bearer token on a command
line (docs/node-identity.md — a hook bearer landed in a long-lived tmux client's
/proc/<pid>/cmdline at mode 444, readable by anyone on the box). The session host repeats none
of that shape: the token is never an argv element anywhere (the host is launched with only
<scriptPath> <userDataDir> — nothing sensitive), never an environment variable a ps/Task
Manager listing could expose, and never logged (host.ts's own diagnostic log never includes it).
Honest limitation on the transport itself: the endpoint is a Windows named pipe / POSIX unix socket. Node's default pipe/socket creation does not carry an explicit, verified per-user ACL in this implementation — the bearer-token check is the load-bearing access control, not the transport's own permissions, exactly as the task's instructions require ("Refuse any connection whose hello token does not match, and close it" is implemented; a separately audited pipe DACL is not). A local unprivileged process that can guess/observe the token could still connect; guessing a 256-bit random hex token is not feasible, and observing it requires filesystem access to a 0600-mode file this app's own user account owns — the same trust boundary every other secret this app already keeps at rest (accounts, hook tokens) relies on.
Memory bound
Each HostSession holds one @xterm/headless Terminal whose scrollback is
xtermScrollback(settings.tmuxScrollback) — floored at 1,000 and capped at 10,000 lines
(src/shared/scrollback.ts), the same clamp as the renderer's own xterm. Core sends the clamped
value, and the host clamps again at the attach request boundary (clampEmulatorScrollback) so an
older client still sending the raw 50,000 is bounded too; the clamp runs before both the
replacement-replay fingerprint and construction, so a replay of the same request still matches.
The main-process NativeWindowsPane mirror (non-persisted win32 panes) uses the same clamp.
Why not reuse tmux's history-limit (default 50,000): the costs are not the same order. tmux
stores only the cells a line actually uses, in C. xterm's BufferLine is a Uint32Array(cols × 3)
— 12 B per cell for every buffered line, whatever it holds — so a 120-column session that fills
50,000 lines holds ~72 MB of ArrayBuffer (measured ~91 MB with heap overhead; ~139 MB at 200 cols)
inside the one shared host process, against ~14–18 MB at 10,000. And lines past the renderer's
10,000 were never reachable: on this backend the renderer's xterm is the only surface a user
scrolls, yet every warm attach serialized the full history, shipped it over the pipe and IPC, and
the receiving xterm discarded 80% of it (measured: 50k lines → 5.4 MB string built synchronously in
~0.7 s, stalling every session's output; 10k → 1.1 MB in ~0.13 s). Capping the emulator bounds that
attach seed, the co-attach resync and capture's full: true by construction — no protocol field
was needed.
Not reclaimed in place: a session that an OLDER host created at 50,000 keeps that buffer until it
ends — installing a new app does not upgrade a running host (see below), and an old host cannot be
told to shrink. Lowering the setting likewise applies to new sessions only. Beyond the emulator,
the remaining per-session cost is SerializeAddon's transient string at the moment serialize()
runs (attach, join, periodic snapshot, capture request) — never held continuously.
Device check owed (not blocking): host RSS with 10–20 busy normal-screen sessions, before and after.
A DETACHED session's cost is bounded by the same session budget tmux sessions are
(core/session-budget.ts): past the grace window, under memory pressure or past the detached-count
cap, the reaper ends it through the host's generation-checked kill — see "Observability" above.
Observability (sessionDetails): reaper, session-memory panel, dev-server ports
The three surfaces that ask tmux about its sessions — the session reaper (list-windows for
session_attached + window_activity), the session-memory panel and dev-server ports
(list-panes for pane_pid) — ask the host instead, through ONE additive hello feature,
sessionDetails. A connection that negotiated it gets, beside the unchanged names, a row per
LIVE generation: {name, pid, subscribers, lastOutputMs, createdMs, generation}
(ListSessionsResult.sessions). An older client never asks and reads {names} byte-for-byte; an
older host never answers, and the client reports sessions: null — named but undescribed.
lastOutputMsis the honest idleness clock (tmux'swindow_activity, not itssession_activity): stamped on every ptydatacallback, moved by nothing that only LOOKS — attach, detach, capture (session-details-host.test.tspins both directions against the real bundled host).subscribersneeds noshadowedsubtraction: the host has no control-mode shadows (a backgroundsendKeysneeds no subscription), so every subscriber is a viewer. The reaper backend (PtyManager.sessionHostReaperBackend) instead ADDS one for a node this process holds a live session for — a host reconnect briefly reports zero subscribers for a terminal on screen.- The read never launches a host (
listSessionsDetailed), and a failed read isnull— never an empty listing. Absent state is "no host"; PUBLISHED state is not proof of a live one (a host killed from Task Manager, a reboot), so a cold client connects withensureConnected({launch: false})and nothing answering is a failed read — the ordinaryrequest()path would otherwise start a fresh host from every poll. The reaper then plans nothing, the memory panel says "could not measure", dev ports sayunreachable. - A reap kills exactly the generation the listing observed (
killSession'sexpectedGeneration), never by name alone, and nothing else: no scrollback deletion, no tombstone. The client refuses such a kill for a name it is attached to, PtyManager re-asks "do we watch this node?" at kill time, and a successful observed-generation kill never clears a live local attachment (the host answers success for an already-gone generation, which may mean a same-name successor is the one attached). A reaped node cold-restores (fresh: true), the same contract as a tmux reap. The reaper's budget, triggers and kill-time re-verify aresession-budget.ts's, unchanged; the memory reading on Windows isos.freemem(), which there is the OS's available physical memory. - Memory panel: each row's pid is rolled up over the Windows process table
(
Get-CimInstance Win32_Process,WorkingSetSize, onepowershell.exe -NoProfileper panel open — never polled; always the absolute%SystemRoot%\System32\WindowsPowerShell\v1.0path,powershellExe(), because Windows resolves a bare name against the cwd first). Sessions an older host cannot describe areunmeasured, with their own sentence. No host running is "no sessions", not a failure. - The host's own cost (
SessionMemoryReport.host,hostOverheadincore/session-memory.ts): rows roll up from each pane's SHELL, and ConPTY's conhost/OpenConsole is the host's child (the shell's sibling), so neither it nor the host process itself — every session's headless emulator, node-pty's per-session conout worker thread — was in any row. The listing now carries the host pid from the state file (SessionHostListing.hostPid; every host version writes it, so no protocol change), and the panel shows one non-killable line,nodeterm session host (N consoles), added to the total only under themeasuredgate. Both figures are MEASURED working sets, labelled as such; nothing is estimated. Every non-shell child is included, so while the host's pane-probe PowerShell worker (below) is warm — up to 60 s after a probe — its working set is part of the line too; it is genuinely the host's cost, but expect the line to drop when it idles out. Unknown host pid, a pid missing from the table, or an undescribed session (whose shell would be booked as host overhead) ⇒ no line, never0 B. An idle host with no session is still measured. - Dev-server ports: one PowerShell call per scan —
Win32_ProcessplusGet-NetTCPConnection(owning pid is a kernel field, nothing a process can rename itself into), falling back tonetstat -ano(listeners recognised by a foreign port of 0, because the state column is localized). A non-zero exit isunreachable; with no nt- session nothing is spawned.
Pane probes: one long-lived PowerShell per process
paneCommand (restart/Eco exit poll, agent liveness, launch readiness) and the console-owner probe
(readWindowsConsoleOwner — messaging, Eco's owner read, terminateOwnerV1) used to start a fresh
powershell.exe per call; the owner probe also re-ran Add-Type (csc + a temp assembly on PS 5.1)
every time. Both now go through session-host/windows-probe-worker.ts: one lazy child per process
(the host's, or main's for a direct Windows PTY) that compiles the type ONCE and answers JSON-line
requests FIFO. Rules a refactor must keep:
- Fallback, not replacement.
unavailable(could not start, timed out, died, garbage) falls back to the original one-shot script;failed(the worker ran the probe and it failed) is a real answer and is not retried. Two consecutive transport failures bench the worker for 5 min — never a respawn loop. Deadlines: 6 s for the first request after a spawn (startup + compile), 1.5 s warm. Idle exit after 60 s; stdin closing ends the loop, so it dies with its parent. - The worker holds its own stdio first (
OpenStandardInput/Outputbefore any probe), because the probeFreeConsole/AttachConsoles. Unverified on a device — checklist item P1 below. - Table reads are coalesced in flight, never cached by time (
createProcessTableReader). The exit poll accepts a changed reading only on two CONSECUTIVE polls; a cached snapshot answering both would confirm a momentary child of a still-running CLI from ONE observation and type the resume line into a live agent. - Every one-shot path is the absolute
%SystemRoot%PowerShell (powershellExe()), never a bare name. - A slow read still gets its samples. The exit phase owes a pane that keeps answering at least
RESTART_MIN_EXIT_SAMPLES(4) readings, each withmax(window left, timeoutMs/2), so a cold ~1.5 s read cannot turn a CLI that quit at 8 s into a falseexit-timeout(inert on tmux).
node-pty's conout worker thread (documented, not changed)
node-pty 1.1.0 starts one worker_threads Worker (a full V8 isolate) per ConPTY
(lib/windowsConoutConnection.js), measured on plain Node at ~11–12 MB RSS each idle (10 workers
+118 MB, 30 workers +349 MB); under ELECTRON_RUN_AS_NODE it is probably a little more. It is
node-pty's design for keeping conout reads off the main thread (a ClosePseudoConsole must never
block on an undrained pipe), and we pin and patch exactly 1.1.0, so we do not remove it. It is now
VISIBLE — it is inside the session-host line of the memory panel — and the lever on our side is
session count (offscreen release, Eco, the reaper for detached sessions). Sharing one conout worker
via scripts/patch-node-pty.mjs is worth doing only if a device shows ≥ ~8 MB per session: item P4.
Honest limitations
- If the session-host process dies, or the machine reboots, its sessions die with it. This is
a strictly weaker guarantee than a real tmux server, which is a mature, independently-shipped C
daemon this project does not maintain. The existing cold-restore path (persisted scrollback
snapshot + agent
--resume) already exists for exactly the "machine rebooted" case and applies here unchanged:spawnNew()correctly reportsfresh: truewhen a fresh host has no record of a previously-running session, which is what triggers the renderer's cold-start replay (attachReplay→'cold-snapshot') and the agent CLI's--resume. The periodic scrollback snapshot (snapshotScrollback) runs for session-host-backed sessions on the same 15-second timer as the tmux path, using the same on-disk format (scrollback-store.tsis entirely backend-agnostic — no changes needed there at all). - A WSL profile does not turn its distribution's tmux into the Windows backend. nodeterm
launches that distribution's default shell through
wsl.exe, and the Windows session host owns the resulting process. A genuinely Windows-reachable tmux found by the existing resolver still follows the tmux path; atmuxinstalled only inside WSL is not on the native Windows PATH. paneCommand's answer can be imprecise when a session has multiple concurrent child processes (an agent CLI plus MCP servers) — seeprocess-tree.ts's doc comment. Its callers (in-place agent restart, wake, trigger delivery, RunBar, session rename) only need "is a shell back in charge of this pane yet", so the walk answers a SHELL name only when every live process in the tree is a shell; otherwise it answers a non-shell. This matters sinceisShellCommandrecognisespwsh.exe/cmd.exe/bash.exe: a shell that is merely a leaf under a running agent (claude's Bash/PowerShell tool, an MCP server launched viacmd /c npx) must not read as "the CLI let go". A future caller with finer-grained needs should not assume more precision than this.- The node-pty actuator is global, so ownership is ledgered rather than guessed. Within one app
process,
pty-manager.tskeeps a per-viewer/ownerpausedByledger. The standalone host then keeps a second set keyed by authenticated socket: the first socket to pause actuates node-pty, an unrelated socket's resume is a no-op, and only the last owner leaving/resuming actuates resume.detachand transportclosereturn that socket's ticket. This cannot give two connections independent output streams (node-pty has one read side), but it preserves the necessary slowest-viewer semantics and, critically, a crashed viewer can no longer freeze the 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.
paneCwdonly 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.- No equivalent of
paneOwner/bracketPasteRequested/ a standalonepaneCursorquery — see the protocol table's "Not implemented" note. Nothing in this app currently calls these for a session-host-backed node (they are gated behindthis.tmuxPathbeing set), so nothing is silently broken; a future feature that wants one of these on Windows needs a new host verb. - The phone relay has no tmux to drive on this backend. Over SSH-less (relay-only) pairing the
phone used to (a) type a POSIX launch line into a fresh pane and (b) scroll by writing SGR wheel
bytes for tmux's copy-mode. Neither holds here: pwsh / cmd reject
2>/dev/null,env -u,VAR=x cmd, and a wheel nobody asked for lands in the prompt as text. So the phone sendspty.attach { launch }and the HOST launches (core/relay-launch.ts: cwd/account ride the spawn options, the line is built for the pane's real parser and typed once;launched:trueis promised only after a preflight build succeeded, andpaneShelltells the phone whether a typed POSIX line is safe in that pane — an SSH-project node of a Windows desktop isposix), the attach reply saysscroll:'local'with a full-buffer snapshot, andpty.scrollwrites a wheel only whenpaneModesV1reports the app asked for the mouse. Keyed Inbox answers (agent.key), read-acks (inbox.ack), the folder browser (fs.browse) and plain capture (pty.capture) are relay verbs for the same reason. All additive;host.infolists them for feature detection. - ConPTY helper teardown can emit
Error: AttachConsole failedfromnode-pty/lib/conpty_console_list_agent.js. The protocol test determines kill success from the host response and follow-up session state rather than stderr text. Whether this cosmetic dependency message appears in the packaged app remains part of the pending artifact run.
Automated verification
Direct ConPTY agent messages (separate from the persistent host)
The desktop can also hold a non-persistent native PTY, indexed by canvas node id but
without Session.persistKey. Checking only persisted sessions incorrectly returned targetGone
for such a running OpenCode. hasLiveSession now uses the common runtime lookup.
core/native-windows-pane.ts implements message delivery for those direct PTYs. It uses a
headless terminal for observed bracketed-paste mode and capture, and reads native executable
identity through console membership and an unambiguous shell-child chain. Process birth times
and a generation id detect replacement/PID reuse. It deliberately does not choose an arbitrary
deepest descendant, interpret prompt text as an executable, or accept a detached console.
This Windows ownership evidence is not POSIX foreground-group semantics; ambiguous console
trees refuse. An interpreter is identified by its script: the probe keeps only the first
positional argument (CommandLineToArgvW, inside PowerShell) and scriptCommandName resolves it
to the command its npm package publishes in bin, else to the script basename. Measured on
Windows 11 (2026-09-14) against a live Codex pane opened from the canvas: the PR-era probe read
node and the installed app refused send with targetNotAgentPane (observed: node), while the
new probe read codex (agent) from the same console. A fake npm package in a separate console
confirmed the prompt argument never appears in the probe output. The
interpreter is the leaf; its children (a native codex.exe, MCP servers) do not count. Existing project consent, verified idle hooks,
delivery locks, post-write verification and receipt tracking remain in force.
The persistent host has a separate, additive messaging extension (messageOwnerV1,
messagePasteReadyV1, messageEnvelopeV1). session-host/message-pane.ts observes the OS console
under the host's session generation and reads the host's existing emulator after its output
barrier. Before sending, it repeats the identity probe, checks paste mode again, and confirms
that the same session object is still registered after every await. It then writes one sanitized
multiline bracketed paste, watches its own emulator until the envelope footer renders, and sends
Enter as a second write, only while the same generation is still registered
(core/settled-submit.ts, shared with the Server Edition). With the Enter inside the paste write,
Codex 0.154 left the envelope unsent in its composer and the delivery reported stalled. Main still owns the project/consent/hook/binary
and receipt gates. The direct adapter is never used for host-backed sessions.
A host-backed session stays addressable after the desktop releases its client (park expiry,
offscreen release). targetLive comes from PtyManager.sessionExists, and the three messaging
probes route by sessionHostOwns, which reads the release record when no Session is left and
otherwise applies sendText's rule (no local tmux means the host owns persistence).
Stopping the agent (terminateOwnerV1, model switch / "Restart on subscription"). Windows has
no foreground process group, so PtyManager.terminateForeground cannot SIGTERM one. On a
session-host pane it sends the owner it just proved with messageOwnerV1 (the agent-identity gate
is MANDATORY here — the legacy "not a shell" guard is not provable on Windows); the host re-reads
the owner, requires sameNativeProcess (pane generation, root pid, the single pid, OS birth time,
executable), refuses the console root and any shell, and only then runs taskkill /T /F on that
pid (session-host/terminate-owner.ts). The shell survives for the recycle that follows. A direct
ConPTY pane runs the same helper in core against NativeWindowsPane.owner(). An older host answers
unknown command; the client maps that to 'unsupported' and the canvas says the host predates
the verb instead of "busy". Unlike SIGTERM, /F gives the agent no chance to flush — the CLI's
transcript is appended per message, so --resume still finds the conversation (device item).
The extension is independently versioned so the existing terminal protocol v1/v2 is unchanged.
Old live hosts reject the new command names, and the client returns null/false without falling
back to write, sendKeys, or a local tmux. Installing a new app does not upgrade an already
running host. It must retire after its existing sessions have ended, at a user-coordinated time;
the next host starts from the new bundle. Never terminate a user's live host as an upgrade step.
There is no hot migration of an existing ConPTY generation to another host.
scripts/smoke-session-host-messaging.ts exercises a separate real Windows host over its named
pipe, using a native fake reader (no model/API call): OS identity, probe latency within the 2 s
budget, exact multiline framing, stale-generation refusal, and retirement of the isolated fixture.
This proves the transport extension, not message/reply delivery between actual OpenCode agents.
Installed-device acceptance (2026-09-13, local build 0.3.5-windows-messaging.2): after each
resumed OpenCode posted a fresh verified status, the coordinator's native messages reached both
architect and coder; their NT2-ARQ-OK / NT2-CODER-OK replies arrived as native message
envelopes in the coordinator transcript. Board-log traces confirmed delivery in both directions,
including queued replies delivered after the coordinator became idle. These resumed sessions
were direct Windows PTYs (their shell processes were children of the desktop main process);
the old persistent host was no longer running. This acceptance therefore proves the installed
message workflow on that backend, while the persistent extension remains covered by the separate
real-host fixture above, not by a claim that these OpenCodes ran inside it.
Desktop message dispatch also waits for pending canvas publication before asking main to authorize
the pair. Without it, a newly opened node can appear in list and context links but be absent
from main's persisted project snapshot, whose scope resolver labels it cross-project. A file
conflict blocks that publication; it is never silently answered as Keep mine. Server control
already persists its creations; mobile is not a sender of these agent messages.
scripts/smoke-windows-agent-messaging.ts tests a real isolated ConPTY with a native reader:
console identity, one multiline bracketed paste, and refusal after disposal. It makes no LLM
call. The installed-app message/reply check with actual OpenCode agents is a separate acceptance.
scripts/sim-agent-messaging-windows.ts runs the coordinator ↔ architect ↔ coder scenario end to
end against an isolated real host, with the real mirror, decider, deliverFromControl, queue and
receipt watch; only the agent CLIs (paste-aware fake composers) and the hook transport are
simulated. Measured 2026-09-15: three rounds of send/reply pass, including busy targets queued
and flushed on idle, and a verified SessionStart + idle_prompt committing a verified idle
without a turn. Two findings it pins: after an app restart an idle agent whose CLI emits no hook
stays targetStatusStale on every retry (whether real Claude emits one there is not measured);
and against a reader that drains input every 150 ms, the sendKeys plan (paste, then an
immediate Enter write) had its Enter swallowed into the paste while the settled envelope
submitted.
OpenCode transcript export on Windows is not part of this change: it runs the resolved npm shim
through directExecutableInvocation (opencodeExportAt, #655).
The focused suites exercise behaviour rather than scan implementation source:
- the Windows profile resolver covers detection precedence, standard Git Bash locations, custom
absolute paths containing spaces,
%COMSPEC%, unavailable executables, malformed ids, WSL UTF-16/NUL output, distribution names containing spaces, and cwd-conversion failures; - resolver/spawn tests assert that
node-ptyand session-host creation receive only the trusted launch plan, and that explicit unavailable profiles perform no fallback spawn; pty-session-host.test.tsexercises successful creation plus provisional/rejected attach teardown, coalesced callers, late events, and the persistent result;session-host-client.test.tsuses real local sockets to exercise the hello transition, correlated responses, failed-subscriber rollback, reconnect replay, and transport uncertainty; and- workspace/node-exec tests prove
terminalProfileIdnever enters shared/exported/inbound state and that the local overlay survives reload.
The guards were mutation-checked by temporarily accepting a hostile profile, allowing a missing WSL distribution to fall back, and removing machine-local stripping; each corresponding focused test must turn red. The former source-text shell regression test is intentionally gone.
The original session-host implementation was also verified by hand against a real ConPTY session. The ordering, connection-owned pause ledger, no-tmux relay probe/capture, platform shell selection, and atomic state publication are now additionally behaviour-tested with adversarial scheduling and injected sharing violations. That source/runtime evidence does not replace the packaged check.
Packaged verification still owed
Staged host runtime (#829 step 3) — device checklist
Written and unit-tested on Linux; nothing below has run on Windows yet.
- Measure the file set. On a packaged build, run Process Monitor filtered to
nodeterm-sessionhost-v2.exeduring host start and an attach; record every file opened under the staged directory. PruneRUNTIME_*insession-host-runtime.tsto that set (expectlocales\and most DLLs to be unnecessary) and re-run the smoke check. - Smoke run passes. Fresh install of the new build, open a terminal:
session-host.logshows[app] staged runtime: published <key>, and Task Manager → Details showsnodeterm-sessionhost-v2.exewith a path under%LOCALAPPDATA%\nodeterm\session-host. - Update 0.3.x → new build with live sessions. On a release with the legacy host, the first
update still meets the legacy host (expected: prepare as before). Then, with the new build's
staged host holding live shells/agents, install the NEXT build with the app closed: the installer
must not prompt, must complete, and after reopening every session re-attaches warm (log:
attach (warm), same host pid as before the update). - Same, with the app open during the install: the preflight prompts for the app only; after closing it the install completes and sessions stay warm.
- Old uninstaller during update. Confirm the previous version's uninstaller (both a pre-#868 stock one and a #868 one) completes with the staged host running.
- Compatibility. With a staged host from build N running, launch build N+1: new terminals go to the old host; after the last session closes and 30 s pass, the next terminal starts a host from N+1's copy and N's directory is removed on the following launch.
- GC fail-closed. With a staged host of an old version running, launch the new app: that old directory is kept. With PowerShell blocked by policy: nothing is removed.
- Defender / AV. First staging with real-time protection on: time it (log timestamps), check for quarantine or SmartScreen prompts, and that a scan holding the new exe does not fail the publish rename. Repeat with a third-party AV and with AppLocker/WDAC denying executables in the profile (expected: smoke run fails, legacy launch, installer still protects the install).
- Disk usage. Size of one staged version directory; confirm only the current (plus running) versions remain after a few updates.
- Uninstall with a staged host running: completes, host and sessions keep running, the staged folder remains; after the host exits the folder can be deleted.
- Two users / all-users install. Each user stages their own copy; one user's host does not block another user's update.
Session-host overhead and Windows probes — device checklist
P1. Probe worker stdio. With the worker warm, run 100 agent messages and an Eco cycle: every
probe answers, no csc.exe/powershell.exe sawtooth in Process Explorer, and
FreeConsole/AttachConsole inside the persistent process never breaks its own stdin/stdout.
P2. Probe latency. Time a cold and a warm paneCommand and owner probe on PS 5.1. Target: warm
under ~300 ms, well inside the 2 s pane-probe budget; cold inside the 6 s first-request deadline.
P3. conhost parentage. Get-CimInstance Win32_Process shows conhost.exe / OpenConsole.exe with
ParentProcessId = the session host's pid (so the panel's line counts it), for inbox ConPTY.
P4. Per-session host cost. Session-host working set + private bytes at 0 / 10 / 30 idle cmd
sessions, and again with useConptyDll. Record the per-session delta here; patch a shared
conout worker only if the worker share is ≥ ~8 MB per session.
P5. Eco on Windows, with pwsh and with cmd as the default shell: idle → /exit → SLEEPING →
wake → claude --resume <id> typed once; the session-memory panel shows the tree drop to the
shell alone. Repeat with a native claude.exe and an npm claude.cmd; a node with an MCP child
(node → cmd /c → node) is not misread as a shell; a blocked node is never exited.
ConPTY selection (bundled conpty.dll) — device checklist
Written and unit-tested on Linux; nothing below has run on Windows yet. Run each on Windows 10 22H2 (19045) and on Windows 11, packaged build:
C1. Which ConPTY ran. Task Manager → Details while a terminal is open: an OpenConsole.exe
whose path is under the install (main process) or %LOCALAPPDATA%\nodeterm\session-host\…
(session host), and no inbox conhost.exe for that terminal.
C2. Fullscreen Claude wheel scroll, in a canvas node. Claude Code with /tui fullscreen, a long
conversation: mouse wheel and trackpad scroll the conversation; earlier turns are reachable.
C3. The same in the kanban card modal (its co-attached viewer), including right after opening
the modal without pressing a key.
C4. vim / htop mouse. Click to place the cursor in vim with :set mouse=a; click a process in
htop (or another mouse-aware TUI); wheel scrolls inside them.
C5. Plain shell scrollback still works. In pwsh and cmd, run something that prints a few
hundred lines: the wheel scrolls xterm's own history as before, and Shift-drag selection copies.
C6. Warm reattach after an app restart. Quit and relaunch with a fullscreen Claude and a vim
open: both reattach warm (attach (warm) in session-host.log) and the wheel still works
without a keystroke (mouse modes restored from the host's serialized screen).
C7. Teardown leaves no OpenConsole.exe. Close a node with ×, End session, an Eco exit cycle,
and quitting the session host for an update: after each, no orphan OpenConsole.exe remains in
Task Manager, and conpty.kill still reports positive proof (no could not safely close line).
C8. Fallback. Delete build\Release\conpty\conpty.dll from a packaged install's session-host
copy: terminals still open (inbox ConPTY), they just lose C2.
C9. P4 with useConptyDll. The per-session session-host cost of P4 above, measured again with
the bundled ConPTY — OpenConsole.exe replaces conhost.exe, and the memory panel's host line
must still count it (P3's parentage check, for OpenConsole.exe).
Earlier items
The real Windows x64 installer must still be exercised through the required cheap headless route: create every available profile, verify input/output/resize/Unicode/copy/cwd and labels, relaunch around a long-running process, switch a node through the destructive profile warning, and record the picker, profile terminal, unavailable state, and post-relaunch reattachment. Until that built artifact evidence exists, this document makes no claim that the full packaged verification has completed.
paneOwner, bracketPasteRequested, the standalone paneCursor query, and independently audited
Windows named-pipe DACL hardening remain outside this profile pass as described under
"Honest limitations".
What was deliberately not done
- The original implementation was verified by hand against a real ConPTY session. The ordering,
connection-owned pause ledger, no-tmux relay probe/capture, platform shell selection and atomic
state publication are now additionally behavior-tested with adversarial scheduling and injected
sharing violations. A packaged installer launch on a separate Windows device is still owed (see
docs/windows-support.md); these tests do not pretend to replace that device check. paneOwner,bracketPasteRequested, and a standalonepaneCursorquery were not ported — see "Honest limitations".- Windows named-pipe DACL hardening beyond Node's own defaults was not attempted — the bearer token is the enforced boundary, documented as such rather than silently assumed to be perfect.
- The relay host's
createDetached/attachDetachedpaths were left to fall through tospawnSession()'s new branch automatically (they call it directly with no prior async pre-check), so they work, but were not separately hand-verified end-to-end through the relay feature itself in this pass — only the primary create/join/reconnect/capture/kill paths were.
Non-message delivery result (#780)
New callers use additive sendKeysV2, returning result.delivery: true for completed
requested writes, false before input, or pasted-not-submitted when paste landed but the
settle/mode/generation checks withheld Enter, or a transmitted request lost its reply.
The latter case is uncertain: neither paste nor submission is claimed confirmed. The last result is terminal for automatic
delivery: inspect the terminal, do not resend or blindly press Enter. Canvas write, trigger
run history, and one-way UI writers surface it. An older host refuses this command and keeps
its sessions; there is no fallback to sendKeys, raw input, or automatic restart. Legacy
clients retain their existing sendKeys wire contract. No real Windows TUI measurement is
claimed by the fake-PTY regression fixtures.