Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs(windows): session-host observability — reaper, memory panel, dev ports
review504af4dbabbd
diff --git a/CLAUDE.md b/CLAUDE.mdindex 640506558..bd1e1ee1d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -5949,6 +5949,17 @@ about which machine they describe. Reading + parsing is `core/session-memory.ts`any value inside it. **Mobile**: **N/A for v1** — *nodetermmobile* attaches to tmux sessions over the transport protocol and has no per-session host-memoryconcept; adding one means extending that protocol (follow-up in the iOS repo).+- **Windows (no tmux) — the session host is a third leg, not a special case.** Its sessions reach+ the reaper (`SessionReaperOpts.sessionHost`, consulted only when `tmuxBin()` is null), this panel+ (`collectSessionHostMemory`, CIM process table) and dev-server ports (`collectWin32DevPorts`, one+ PowerShell call) through ONE additive hello feature, `sessionDetails` (pid, subscribers, output+ clock, generation per session — docs/windows-session-host.md "Observability"). The rules above+ carry over unchanged: a failed host read is `ok:false` / no candidates / `unreachable`, never "no+ sessions"; no host running IS "no sessions"; a session an older host names but cannot describe is+ `unmeasured` (`unmeasuredBackend: 'session-host'`, its own sentence), never dropped; a reap kills+ exactly the observed generation. Both legs merge (`mergeLocalLegs`): a leg that answered is never+ overridden by one that failed. The tmux path is untouched wherever the session host is not the+ backend (`PtyManager.sessionHostListing()` answers `undefined`).**Offscreen release makes the macOS reaper bug far more visible, and the two shipped days apart.**A node released while offscreen detaches its PTY client — so it becomes a DETACHED tmux session and@@ -6087,6 +6098,13 @@ project's existing ControlMaster, so the URL the tool itself printed just worksend to end on Linux: a real tmux session (private socket, sandboxed TMUX_TMPDIR) running a reallistener two processes below its pane, read back through real `ps` + `ss`(`dev-ports.realsh.test.ts`).+- **Windows: the session host's panes + one PowerShell call** (`collectWin32DevPorts`). No `/bin/sh`+ and no tmux there, so the panes are the host's `sessionDetails` pids and the process table ++ listeners come from `Win32_Process` + `Get-NetTCPConnection` (the owning pid is a kernel field —+ no name to forge), else `netstat -ano` (a listener is a TCP row whose FOREIGN port is 0: the state+ column is localized). Same `assembleDevPorts`. A failed host read, an older host without pids, or a+ non-zero PowerShell exit is `unreachable`; `unsupported` only when the session host is not the+ backend; no nt- session means no PowerShell spawn at all.- **Ports in the ephemeral range (≥ 32768) are listed but not counted.** A headless browser'sdebugging endpoint or an MCP helper asks for "any port" and lands there; a dev server a personmeans to open almost never does. The chip counts only the rest and is absent when there are none;diff --git a/docs/windows-session-host.md b/docs/windows-session-host.mdindex 5abf4f1de..5fbe2d83d 100644--- a/docs/windows-session-host.md+++ b/docs/windows-session-host.md@@ -145,7 +145,7 @@ long-lived connection (no positional-FIFO fragility, unlike this app's tmux cont| `capture` | `capture-pane -p -e [-S -N]` | full, and strictly more (mode restoration — tmux's plain-text capture carries none) || `killSession` | `kill-session -t <name>` | full || `detach` | a client's own `tmux detach-client` | full |-| `listSessions` | `list-sessions -F '#{session_name}'` | 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 |**Not implemented — deliberately out of scope for this pass:**@@ -648,6 +648,45 @@ never held continuously. This is a genuinely new per-session cost the tmux backeprocess); it was a deliberate choice per the task brief ("bound the memory... document the costyou chose and why") rather than an oversight.+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.++- **`lastOutputMs` is the honest idleness clock** (tmux's `window_activity`, not its+ `session_activity`): stamped on every pty `data` callback, moved by nothing that only LOOKS —+ attach, detach, capture (`session-details-host.test.ts` pins both directions against the real+ bundled host).+- **`subscribers` needs no `shadowed` subtraction**: the host has no control-mode shadows (a+ background `sendKeys` needs 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`, the `inspectForUpdate` rule), and a+ failed read is `null` — never an empty listing. The reaper then plans nothing, the memory panel+ says "could not measure", dev ports say `unreachable`.+- **A reap kills exactly the generation the listing observed** (`killSession`'s+ `expectedGeneration`), never by name alone, and nothing else: no scrollback deletion, no+ tombstone. A reaped node cold-restores (`fresh: true`), the same contract as a tmux reap. The+ reaper's budget, triggers and kill-time re-verify are `session-budget.ts`'s, unchanged; the+ memory reading on Windows is `os.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`, one `powershell.exe -NoProfile` per panel+ open — never polled). Sessions an older host cannot describe are `unmeasured`, with their own+ sentence. No host running is "no sessions", not a failure.+- **Dev-server ports**: one PowerShell call per scan — `Win32_Process` plus+ `Get-NetTCPConnection` (owning pid is a kernel field, nothing a process can rename itself into),+ falling back to `netstat -ano` (listeners recognised by a foreign port of 0, because the state+ column is localized). A non-zero exit is `unreachable`; with no nt- session nothing is spawned.+## Honest limitations- **If the session-host process dies, or the machine reboots, its sessions die with it.** This is