Skip to content

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

docs(windows): session-host observability — reaper, memory panel, dev ports

review504af4dbabbd
diff --git a/CLAUDE.md b/CLAUDE.md
index 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** — *nodeterm
mobile* attaches to tmux sessions over the transport protocol and has no per-session host-memory
concept; 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 works
end to end on Linux: a real tmux session (private socket, sandboxed TMUX_TMPDIR) running a real
listener 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's
debugging endpoint or an MCP helper asks for "any port" and lands there; a dev server a person
means 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.md
index 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 backe
process); it was a deliberate choice per the task brief ("bound the memory... document the cost
you 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