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: session-host overhead, Windows probe worker, heap-cap and reaper notes
reviewfde194c55c40
diff --git a/CLAUDE.md b/CLAUDE.mdindex c06ca6534..75ff0e161 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -5900,6 +5900,14 @@ about which machine they describe. Reading + parsing is `core/session-memory.ts`fence back out — and do not replace the classifier with a blunt "any error ⇒ ok:false" either: ona host with no tmux server at all EVERY socket fails, and there "there are no sessions" is thehonest answer.+- **On Windows the session host's own cost is a separate, measured line** (`SessionMemoryReport.host`,+ `hostOverhead`): the host process plus its non-shell children (ConPTY's conhost/OpenConsole is the+ host's child, the shell's sibling, so no row reaches it). Never folded into a session row, never a+ fake `0` — an unknown host pid or an undescribed session (whose shell would be misbooked) means no+ line. Windows pane probes run through ONE long-lived PowerShell per process+ (`session-host/windows-probe-worker.ts`, one-shot fallback), and the table read is coalesced in+ flight but **never time-cached**: the exit poll's two-consecutive-readings rule must see two real+ observations. Details + device checklist: docs/windows-session-host.md.- **`readMemInfo` has exactly one home** (`core/session-memory.ts`); `session-budget.ts` imports andre-exports it. The reaper's watermark and the pill must never disagree about how much RAM is free,and a second copy is exactly the drift this file warns about elsewhere. `null` = could not read,diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 4794b1458..9d8d4ed3e 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -71,6 +71,12 @@ its terminals and refuses the extension; never restart it automatically or fallMessage dispatch publishes pending canvas edits before main resolves scope, without overwritingan unresolved file conflict. See `docs/windows-session-host.md`.+**Windows pane probes:** never start a `powershell.exe` per probe. Pane-command and console-owner+reads go through the per-process probe worker (`session-host/windows-probe-worker.ts`), which falls+back to the one-shot script (absolute `powershellExe()` path) only when it cannot answer. Coalesce+concurrent table reads, but do not add a time-based cache: the restart exit poll needs two real+consecutive observations before it trusts a changed pane.+**Windows agent launches:** a new agent launch site that types a prompt-bearing line must gothrough the launch writer (`createLaunchWriter`) so a Windows-native pane can execute the node's`data.launchIntent` instead (`pty:execute-launch`). If you add a launch input the core planner doesdiff --git a/docs/session-memory.md b/docs/session-memory.mdindex 23dce9b8e..d1d613810 100644--- a/docs/session-memory.md+++ b/docs/session-memory.md@@ -59,6 +59,27 @@ for v1: a low ceiling OOM-kills a long-context session, which is worse than the**Do not re-derive these numbers.** They are here so the next person does not spend an afternoon on`/proc` arithmetic to reach the same conclusion.+**Power users: capping a node-based agent's heap.** nodeterm still ships no cap and must not grow a+`NODE_OPTIONS` default. A user who wants one can set `NODE_OPTIONS=--max-old-space-size=2048` in a+**custom agent's env** (Settings → Agents); project env cannot, because `NODE_OPTIONS` is a reserved+spawn key (a code-execution guard). Three caveats belong with that advice: a session that outgrows+the cap is OOM-killed (the pane and `--resume` recover the conversation, not the turn); it only+affects npm-installed **node** CLIs (`claude.cmd`, gemini) — the native `claude.exe` is a Bun+binary and codex is Rust, so there it does nothing (`where claude` says which one a Windows user+runs); and it is a per-machine choice, never a project one.++**Attached sessions are never reaped, by design.** The reaper (`session-budget.ts`) only ends+DETACHED sessions; anything mounted on a canvas is watched and untouchable, on tmux and on the+Windows session host alike. The levers for live sessions are offscreen release (which detaches the+viewer, so the grace window / count cap can apply), Eco, Pause, and the panel's `×`. Heavy users can+shorten the grace with `NODETERM_SESSION_GRACE_HOURS` (fractional values are honoured; see below).++**Windows: the session host's own cost is shown, not hidden.** On Windows the panel adds a+non-killable `nodeterm session host (N consoles)` line — the host process (headless emulators,+node-pty's per-session conout worker thread) plus its conhost/OpenConsole children, which no+session row can reach. It is a measured working set, added to the total only when measured. See+docs/windows-session-host.md ("Observability", "Pane probes").+### A fractional `NODETERM_SESSION_*` value must not disarm the guardFound while running the live reaper experiment with `NODETERM_SESSION_GRACE_HOURS=1`.diff --git a/docs/windows-session-host.md b/docs/windows-session-host.mdindex 9d48f81a7..7893d13f0 100644--- a/docs/windows-session-host.md+++ b/docs/windows-session-host.md@@ -728,11 +728,58 @@ older host never answers, and the client reports `sessions: null` — named butopen — never polled; always the absolute `%SystemRoot%\System32\WindowsPowerShell\v1.0` path,`powershellExe()`, because Windows resolves a bare name against the cwd first). Sessions an older host cannot describe are `unmeasured`, with their ownsentence. No host running is "no sessions", not a failure.+- **The host's own cost** (`SessionMemoryReport.host`, `hostOverhead` in `core/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 the `measured` gate. Both figures are MEASURED working sets, labelled as+ such; nothing is estimated. Unknown host pid, a pid missing from the table, or an undescribed+ session (whose shell would be booked as host overhead) ⇒ no line, never `0 B`. An idle host with no+ session is still measured.- **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 statecolumn is localized). A non-zero exit is `unreachable`; 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/Output` before any probe), because+ the probe `FreeConsole`/`AttachConsole`s. 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 with `max(window left, timeoutMs/2)`, so a cold+ ~1.5 s read cannot turn a CLI that quit at 8 s into a false `exit-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@@ -956,6 +1003,23 @@ Written and unit-tested on Linux; nothing below has run on Windows yet.11. **Two users / all-users install.** Each user stages their own copy; one user's host does notblock 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.+### Earlier itemsThe real Windows x64 installer must still be exercised through the required cheap headless route: