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: correct the PR's CLAUDE.md, CONTRIBUTING.md and session-memory claims
review0945fb815d1d
diff --git a/CLAUDE.md b/CLAUDE.mdindex 227978303..36af8a698 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -250,17 +250,19 @@ PTY output flows main → renderer over per-session channels (`pty:data:<sessioninput flows renderer → main over `pty:write`. node-pty is kept **external** in the bundle(`externalizeDepsPlugin` in `electron.vite.config.ts`) because it's a native module.-**Process death and hangs are telemetry, never triggers** (audit roadmap #6, tmux-2 / obs-5).-Until then the only handler was `render-process-gone`, and it logged nothing, so a GPU-process-crash or a renderer hang left no trace. Now app `child-process-gone` (`{type, reason, exitCode,-name}`, per-type session count; `clean-exit` at info, every other reason at warn), the main window's-`unresponsive` → `responsive` pair (one line per hang, duration measured from Electron's own hang-timeout so it is a lower bound) and `render-process-gone` each write a `[process]` line to the-debug log ring (`main/process-health-log.ts`, wired in `index.ts`). `child-process-gone` is-registered before `ready` because the GPU process can die during boot. None of them reloads,-relaunches or kills anything: Chromium respawns the GPU process itself, and repeated GPU deaths-can trip its per-domain 3D-API block "until restart" (the audit's tmux-4), so provoking more of-them degrades the session. In the renderer, `webgl-budget.ts` counts EXTERNAL WebGL losses by+**Process death and hangs are telemetry, never NEW triggers.** Until then the only handler was+`render-process-gone`, and it logged nothing, so a GPU-process crash or a renderer hang left no+trace. Now app `child-process-gone` (`{type, reason, exitCode, name}`, per-type session count;+`clean-exit` at info, every other reason at warn), the main window's `unresponsive` / `responsive`+pair (two lines per hang: one when it is declared, one when it ends with the duration, measured+from Electron's own hang timeout so it is a lower bound) and `render-process-gone` each write+`[process]` lines to the debug log ring (`main/process-health-log.ts`, wired in `index.ts`).+`child-process-gone` is registered before `ready` because the GPU process can die during boot.+The logging adds no action: `render-process-gone` keeps the crash reload it already had+(`createCrashReloadPolicy`, and it now also closes an open hang), while `child-process-gone` and a+hang reload, relaunch or kill nothing. Chromium respawns the GPU process itself, and repeated GPU+deaths can trip its per-domain 3D-API block "until restart", so provoking more of them degrades+the session. In the renderer, `webgl-budget.ts` counts EXTERNAL WebGL losses bykind through `handle.contextLost(kind)` — `lost` (the addon's `onContextLoss`: still lost afterits 3s window) and `restored` (a GPU reset the browser recovered, which `TerminalNode` rebuilds ona fresh addon) — and writes one `[webgl]` warn per loss carrying the session totals, which main's@@ -624,8 +626,8 @@ config for an SSH project's remote tmux.**Every synchronous tmux call on main is bounded (`TMUX_BOOT_CMD_TIMEOUT_MS`, 2 s, via`PtyManager.runTmuxSync`).** `ensureTmux`'s `source-file` runs before the first window exists, and`ensureUpdateEnvKeys`' `show-options` / `set-option` run on a spawn; unbounded, a server that accepts-the connection and never answers held main for the wedge's whole lifetime (audit main-5: 4.05 s in-the repro, i.e. forever against a server that never recovers). The bound kills only our short-lived+the connection and never answers held main for the wedge's whole lifetime (4.05 s in a repro, i.e.+forever against a server that never recovers). The bound kills only our short-livedclient (SIGKILL, so one that ignores SIGTERM cannot keep `execFileSync` waiting), never the server.A timeout is `console.warn`ed and fails open (tmux stays resolved; the spawn goes ahead); "no serveryet" stays silent, as it always was. A timeout also ends the rest of that call's tmux work — the@@ -2407,13 +2409,13 @@ raw-HTML tokens as escaped TEXT (a program's `<stdin>` is not markup; parsed asstripped it) and trims capture-pane's trailing padding. The escape is on the `html` token, never aglobal pre-escape of `<`, which would double-escape code spans/fences.-**The TS/JS worker is reaped, not idled** (`renderer/editor/tsWorkerReaper.ts`, audit #18). Monaco-0.57 stops the css/html/json workers after 2 min idle but never the TypeScript one (separate TS and JS-managers can pin two compiler isolates, order of 70-100 MB each). monaco-setup stops it with a no-op-`setCompilerOptions` on `monaco.typescript.*Defaults` (`onDidChange` → `_stopWorker`; the next request-restarts it lazily) 2 min after the last TS/JS model is disposed or changes language.-`noSemanticValidation` does not stop it. This only works if every node **disposes its models on-unmount**: one leaked `.ts` model pins the worker for the session.+**The TS/JS worker is reaped, not idled** (`renderer/editor/tsWorkerReaper.ts`). Monaco 0.57 stops+the css/html/json workers after 2 min idle but never the TypeScript one (separate TS and JS+managers can pin two compiler isolates; their size has not been measured here). monaco-setup stops+it with a no-op `setCompilerOptions` on `monaco.typescript.*Defaults` (`onDidChange` →+`_stopWorker`; the next request restarts it lazily) 2 min after the last TS/JS model is disposed or+changes language. This only works if every node **disposes its models on unmount**: one leaked+`.ts` model pins the worker for the session.**The rendered-Markdown font is a setting** (`markdownFontFamily` / `markdownFontSize`, Settings →Appearance; `@shared/markdown-font`). App.tsx publishes it as `--md-font-family` / `--md-font-size`@@ -6541,16 +6543,16 @@ about which machine they describe. Reading + parsing is `core/session-memory.ts`and a second copy is exactly the drift this file warns about elsewhere. `null` = could not read,never zero.- **The pill's swap figure and kernel-pressure tint live in `MemInfo.display`, and nothing but the- pill reads it** (audit roadmap #14). darwin: `sysctl vm.swapusage` and+ pill reads it.** darwin: `sysctl vm.swapusage` and`kern.memorystatus_vm_pressure_level` (1/2/4 → normal/warn/critical), both in ONE`/usr/sbin/sysctl` run inside `darwinMemInfo`, each field optional on its own; Linux: copied from the same `/proc/meminfo` text. **Never fill- `swapTotalMb`/`swapFreeMb` on darwin** — `hostUnderMemoryPressure` reads them, and a Mac keeps- its swap ~85% used while healthy (the audited one: 7.7 of 9 GB, level flapping 1↔2), so the- reaper's swap term would fire all day. The level only RAISES the used-% tint, never lowers it;+ `swapTotalMb`/`swapFreeMb` on darwin** — `hostUnderMemoryPressure` reads them, and a Mac can keep+ most of its swap in use for hours (the measured one: 7.7 of 9 GB, its kernel level moving between+ normal and warn), so the reaper's swap term would fire all day. The level only RAISES the used-% tint, never lowers it;a failed read omits its field (no "0 GB swap"). Not an input to the reaper, the pressure monitoror any lever — that is a separate, measured change.- **"nodeterm itself" is a separate group, never a session row and never in the header total**- (`SessionMemoryReport.app`, audit roadmap #4). The GPU helper's footprint was 1557-1845 MB while+ (`SessionMemoryReport.app`). The GPU helper's footprint was 1557-1845 MB while`ps` rss said 96-153 MB, and no surface attributed it. The desktop shell injects`appProcesses` from `app.getAppMetrics()` for **pid, type and `cumulativeCPUUsage` only**: onmacOS `memory.workingSetSize` is resident size (blind to IOSurfaces, like rss) and@@ -6558,7 +6560,9 @@ about which machine they describe. Reading + parsing is `core/session-memory.ts`on darwin (`ProcEntry.footprint`; a pid `top` missed is "not measured", never its rss), VmRSS onLinux, working set on Windows. No second `top` (~0.5 s each). CPU is lifetime CPU TIME, not arate: `percentCPUUsage` answers 0 on its first call. Local scope only; absent = not available- (Server Edition, SSH, relay); `ok:false` = tried and could not, rendered as such.+ (Server Edition, SSH, relay); `ok:false` = tried and could not, rendered as such. Measured on+ macOS only: the Linux (VmRSS) and Windows (working set) legs have unit tests but have not been+ checked against a real machine.- **The local reader reads `/proc/<pid>/status`, never `statm`.** `status` carries `PPid` and `VmRSS`in one file, already in kB; `statm` reports RSS in **pages**, forcing a page-size assumption — ahard-coded 4096 under-reports **4×** on a 16 KiB-page arm64 kernel and **16×** on the 64 KiB-page@@ -7530,17 +7534,17 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord meatab takes `onMarkdownToggle` from the local preload). macOS Chrome reserves ⌘M for minimize,so the default chord only reaches a Mac browser tab after a remap (docs/SERVER.md).- **A status-reading command builds its answer PER KEYPRESS, never from a subscription.**- `node.nextNeedingYou` (ships unbound, mirrored in ⌘K as "Go to next agent needing you"; audit- roadmap #19 — one chord instead of 3-5 sidebar clicks) builds `needsYouQueue`- (`lib/nextNeedingYou.ts`) from `useProjects`/`useAgentStatus` `getState()` on each press:- the status-mode sidebar's "Need attention" rows (`buildStatusList` over the non-closed- projects), re-sorted OLDEST wait first, minus rows `nodeTravel` reports `blocked`. Canvas must- never subscribe to `statusById` for it (every flip would re-render the canvas). Travel is- `travelToNodeRef` (keeps the hosted-team reopen guard), the cycle cursor is a ref (memory- only), the node the user is already in is skipped when another waits, and an empty queue is- CLAIMED with an info notice — xterm has already withheld the chord, so declining would only- make a deliberately bound chord silent. Its handler entry is pinned by- `keybindings-handler-parity.test.ts`.+ `node.nextNeedingYou` (ships unbound, mirrored in ⌘K as "Go to next agent needing you") builds+ `needsYouQueue` (`lib/nextNeedingYou.ts`) from `useProjects`/`useAgentStatus` `getState()` on+ each press: the status-mode sidebar's "Need attention" rows (`buildStatusList` over the+ non-closed projects), re-sorted OLDEST wait first, minus rows `nodeTravel` reports `blocked`.+ Canvas must never subscribe to the status store's `byId` for it (every flip would re-render the+ canvas). Travel is `travelToNodeRef` (keeps the hosted-team reopen guard), the cycle cursor is a+ ref (memory only), the node the user is already in is skipped when another waits, and an empty+ queue is CLAIMED with an info notice — xterm has already withheld the chord, so declining would+ only make a deliberately bound chord silent. After a restart the notice counts agents whose+ restored `lastSeen` last said waiting/blocked (`waitingBeforeRestart`). Its handler entry is+ pinned by `keybindings-handler-parity.test.ts`, which checks only the ids in its `checkedIds`.- **ShortcutsPanel is DERIVED from the registry, never a hand-written list.**`buildShortcutSections` iterates `COMMAND_DEFINITIONS` — one section per `CommandGroup` inregistry source order, the label from `def.title`, and EVERY one of the command's EFFECTIVE@@ -9130,8 +9134,9 @@ that unmount erase the live view's claim.**The board gate does not stop xterm; `terminal/board-render-pause.ts` does.** CSS reaches the glows,not the terminals: xterm pauses only on its own GEOMETRIC IntersectionObserver, and a node under-the board still intersects. MEASURED (audit GT-6, dev, 12 streaming terminals): board open 36.5 %-GPU vs 0.0 % over silent terminals, and `visibility: hidden` on the canvas 35.5 % — no help. Each+the board still intersects. MEASURED BEFORE the pause (dev, 12 streaming terminals): board open+36.5 % GPU vs 0.0 % over silent terminals, and `visibility: hidden` on the canvas 35.5 % — no help.+The number WITH the pause has not been measured. EachTerminalNode wraps its RenderService's `_handleIntersectionChange` so xterm is told "notintersecting" while `boardOpen` (Omni included) is up and the node is not the focus-mode node (thefocus surface, z 40, sits above the board, z 25); uncovering replays the real entry through xterm's@@ -9139,7 +9144,7 @@ own resume and then `fullRepaint`. Parsing never stops, so nothing is lost. Twothe board into `reportVisible` / the WebGL budget's visibility (that verdict drives hibernation andthe offscreen teardown — the board would put the very sessions it shows to sleep), and any other"is the board up" predicate must OR in `isGlobalKanbanOpen()` (`boardCoversCanvas` missed the Omni-board until GT-6, the same omission 12564a20 fixed for focus restore).+board until this change, the same omission 12564a20 fixed for focus restore).**Specificity is the quiet failure mode in all of this, and it has already happened twice.** Thethree glows carry their own `animation:` shorthand, which RESETS `animation-play-state` — so@@ -9172,20 +9177,23 @@ infinite): an unread node stays unread until someone looks, and a wait can lastcanvas those three kept the frame loop open indefinitely. MEASURED (46-node SSH canvas, 14 unreadnodes, 8 waiting ropes, FOCUSED window, dev build): idle renderer+GPU **~120% → ~25%**, and pausingevery remaining animation no longer moves it. Pausing any ONE family alone saved far less (85–104%),-which is the first-animation step above again. Only the attention glow (and its minimap beat) stays-infinite — needs-you is the one state that must keep pulling the eye — and the idle gate covers the-unfocused case. The driven-browser rope still flows (it lasts only while an agent drives the page).+which is the first-animation step above again. Only the attention glow (and its minimap beat) and+React Flow's animated edges (working subagent and loop edges, the driven-browser rope — see the+`dashdraw` paragraph below) stay infinite — needs-you is the one state that must keep pulling the+eye, and an edge animates only while its work runs — and the idle and covered gates pause all of+them when nobody is looking. The driven-browser rope still flows (it lasts only while an agent+drives the page).`styles.animation-gate.test.ts` pins the bounded shorthands, the resting values and the keyframeendpoints.**React Flow's `dashdraw` is gated in `styles.css`, not by xyflow.** Every `animated` edge (workingsubagent and loop edges, the driven-browser rope) and an animated connection line run xyflow's own`dashdraw 0.5s linear infinite`, from a vendor sheet that never reads `--nt-anim-state` — so until-this rule it escaped BOTH the idle and the covered gate, and "the idle gate covers the unfocused-case" above was false for edges. MEASURED (dev build, one synthetic edge with React Flow's real-classes, idle gate set, 3 alternating 30 s rounds): Liquid Glass 79 % GPU + 36 % renderer and-+340 MB GPU footprint; dark 31.5 % + 29 %; with the play-state rule, the 0.5 % / 3.3 % no-edge-baseline. The rule repeats xyflow's selectors verbatim (same specificity, wins on order after the+this rule it escaped BOTH the idle and the covered gate. MEASURED (dev build, one synthetic edge with+React Flow's real classes, idle gate set, 3 alternating 30 s rounds): Liquid Glass 79 % GPU + 36 %+renderer and +340 MB GPU footprint; dark 31.5 % + 29 %. With the play-state rule injected over CDP+(not the shipped stylesheet) the edge fell to the no-edge baseline of that run, 0.5 % / 3.3 %; the+shipped build has not been measured. The rule repeats xyflow's selectors verbatim (same specificity, wins on order after the`@import`), and `styles.animation-gate.test.ts` scans the vendor sheet for infinite animations, so anxyflow upgrade that adds one fails there. A FOCUSED window still pays the full per-edge cost while anedge works; a cheaper working-edge style is an open design call (the driven rope keeps flowing).@@ -9295,7 +9303,7 @@ unix-socket forward and dev-server `-L` forward over it. POSIX keeps OpenSSH unt- **ssh2 is loaded on first use, never at module scope** (`ssh2()` in `native-mux.ts`; every othershipped import of it is `import type`). native-runtime → native-mux is on main's module-scopegraph, which runs before Chromium's `ready`; a top-level import cost every launch 14–25 ms warm- (~680 ms in one cold-cache sample) on machines that never open an SSH project (audit startup-6).+ (~680 ms in one cold-cache sample) on machines that never open an SSH project.Pinned by `native-mux.lazy.test.ts` (import does not evaluate ssh2) and`src/main/lazy-deps.source.test.ts` (no shipped value import).- **Tests run on every OS** against ssh2's own in-process `Server` (loopback, no sshd); the@@ -9397,8 +9405,8 @@ unix-socket forward and dev-server `-L` forward over it. POSIX keeps OpenSSH unt- **A paused phone stream is resumed by a drain sweep, never by "the next chunk"**(`main/remote/host-service.ts`, FLOW_SWEEP_MS). `sendFrame` refuses — and drops — a frame once therelay socket holds >8 MB, and the host pauses the pty; a paused node-pty emits no `onData`, so the- old resume-on-next-successful-send never fired and the phone's terminal froze until it detached- (audit net-1). A 250 ms sweep, armed only while a stream is paused and cleared in+ old resume-on-next-successful-send never fired and the phone's terminal froze until it detached.+ A 250 ms sweep, armed only while a stream is paused and cleared in`dropStream`/`closeAll`, waits for `bufferedAmount() <= 256 KB`, then capture → `OP.Snapshot*` →`setFlow(resume)`, in that order (the dropped frame desynced the phone; resuming first lets liveoutput race the repaint). The repaint is NOT the attach snapshot's bytes: the phone feeds a@@ -9410,9 +9418,10 @@ unix-socket forward and dev-server `-L` forward over it. POSIX keeps OpenSSH untreconnecting relay reads 0 buffered but refuses every send, so no backoff = a tmux capture pertick). Output still queued after the pause is dropped, not streamed. An emptycapture resumes WITHOUT a repaint — unlike `ui-sink-registry`'s keep-desynced rule, staying here- means staying frozen. Same design as `core/ui-sink-registry.ts`; do not reintroduce a chunk-driven+ means staying frozen. The same drain-sweep pattern as `core/ui-sink-registry.ts` (whose self-paced+ sinks are never dropped at all); do not reintroduce a chunk-drivenresume. `~/.nodeterm/relay.json` is written only when its content changes or the file is missing- (`relay-advertise.ts`): the ~90 s listener cycle used to rewrite it identically (~960/day, net-5).+ (`relay-advertise.ts`): the ~90 s listener cycle used to rewrite it identically (~960/day).- **The phone's Chat screen verbs** (`chat.page` / `chat.status` / `chat.send` / `agent.answer`,`host-service.ts` `handleChat` → `main/remote/host-chat.ts`, spec + exact error strings in`docs/mobile-chat-view.md` §3.2). Four rules a refactor must not undo: (1) **the phone sends only a@@ -10232,8 +10241,8 @@ update vX" item); on `update-downloaded` an OS notification also fires when theunfocused. Exposed via `window.nodeTerminal.updates` (`UpdateApi`). macOS *silent* self-installrequires a signed+notarized build; unsigned builds still surface the card for a manual download.Rules a refactor must not undo (pure + tested: `shared/update-gate.ts`, `renderer/lib/updateCardState.ts`):-- **electron-updater is never imported at module scope** (audit startup-6: 32–47 ms warm before- `ready`, on every launch). `initUpdater` loads it through `UpdaterDeps.loadUpdater` (default: a+- **electron-updater is never imported at module scope** (it cost 32–47 ms warm before `ready`, on+ every launch). `initUpdater` loads it through `UpdaterDeps.loadUpdater` (default: aplain `require`) only where it is used — at init for a build with a feed, on a restart click indev, never for `no-channel` — and only AFTER the `appGetVersion` / `appGetStagedUpdate` /`appRestartToUpdate` handlers are registered, which stay eager on every build (the rendererdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9ce07b533..7a2c13800 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -632,8 +632,9 @@ anything else. Board-level fields survive every transform — `pullLinks` is one- **Relay backpressure is undone by a drain sweep, never by the next chunk of output.** A pausedpty produces no next chunk, so a resume that waits for one never comes: that froze the phone'sterminal for good after a single >8 MB burst. `host-service.ts` arms a 250 ms sweep while a stream- is paused, then repaints with a snapshot before it resumes; `core/ui-sink-registry.ts` does the same- for every other sink. A new paused path needs the same trigger. CLAUDE.md, "Remote access".+ is paused, then repaints with a snapshot before it resumes — the same drain-sweep pattern as+ `core/ui-sink-registry.ts` (whose self-paced sinks never drop). A new paused path needs the same+ trigger. CLAUDE.md, "Remote access".- **An SSH project's node runs on the project's host — ask the project, not the node.** Nodefields like `sshRemoteTmux` arrive through a shared `project.json` that the host's own desktop and@@ -972,7 +973,7 @@ real-tmux test (`account-env.realtmux.test.ts` is the pattern).**A synchronous tmux call on main always has a timeout.** Use `PtyManager.runTmuxSync` (2 s,`TMUX_BOOT_CMD_TIMEOUT_MS`), never a bare `execFileSync` on the tmux socket: one runs before thefirst window exists, and a wedged server held an unbounded call for as long as it stayed wedged-(4.05 s in the audit repro, main-5). Warn on a timeout and fail open; keep "no server yet" silent.+(4.05 s in a repro). Warn on a timeout and fail open; keep "no server yet" silent.A call that runs on every spawn also needs a cooldown after a timeout(`TMUX_UPDATE_ENV_COOLDOWN_MS`), or each spawn waits out the same wedge again.@@ -1000,12 +1001,9 @@ make it show up; a command with no effective binding is omitted rather than listreplaced hand-listed 24 ids against a 45-command registry and had drifted four live chords behind— if you find yourself typing a command id into that file, that is the bug reappearing.-**A command that reads agent status reads it per keypress, never by subscription.** Canvas must not-subscribe to `useAgentStatus`'s `byId` (every working/waiting flip would re-render the whole-canvas): `node.nextNeedingYou` builds its queue on demand (`lib/nextNeedingYou.ts`, over-`buildStatusList`) from `getState()` and travels with `travelToNode`, keeping its cycle cursor in a-ref. A new ships-unbound command also needs a `'<id>':` handler entry that-`keybindings-handler-parity.test.ts` can see — the handlers map is `Partial`, so nothing else will.+**`keybindings-handler-parity.test.ts` checks only the ids in its `checkedIds`.** Add a new+ships-unbound command there, or nothing catches a missing `'<id>':` handler entry in Canvas.tsx+(the handlers map is `Partial`).**Comments explain WHY, and name the failure they prevent.** The codebase is deliberately dense withreasoning. A comment that restates the code is noise; one that says "do not simplify this back,@@ -1386,7 +1384,7 @@ bite most often:compiler isolate) is only stopped once no TS/JS model is left (`renderer/editor/tsWorkerReaper.ts`).**`ssh2` and `electron-updater` load on first use, never at main's module scope**, which runs-before Chromium's `ready` (together ~50–70 ms warm on every launch, audit startup-6). Use `import+before Chromium's `ready` (together ~50–70 ms warm on every launch). Use `importtype` for their types; values come from `ssh2()` in `native-mux.ts` and `initUpdater`'s`loadUpdater`. `src/main/lazy-deps.source.test.ts` goes red on a value import. A `require()` isnot reached by `vi.mock`, so a test injects its double (see the updater tests).@@ -1405,13 +1403,9 @@ on a file it has no loader for). No CI job builds the server bundle, but`src/server/server-build.test.ts` builds it in both views and goes red. The server runs from a`node_modules` tree, so an external is resolved at runtime.-**Session memory's display-only figures stay display-only.** The RAM pill's swap and kernel-pressure-tint live in `MemInfo.display`, which the reaper and the pressure monitor never read; never fill-`swapTotalMb`/`swapFreeMb` on darwin (a healthy Mac keeps swap ~85% used, so the reaper's swap term-would fire all day). The panel's "nodeterm itself" group takes pids/types/CPU time from-`app.getAppMetrics()` but memory from the sweep's own table (`top` footprint on macOS) — never-`workingSetSize`, which on macOS misses the GPU helper's IOSurfaces (≈1.6 GB footprint vs ≈120 MB-rss). It is local-only and never part of the session total. CLAUDE.md, Session memory.+**Never fill `swapTotalMb`/`swapFreeMb` on darwin.** The reaper's swap term reads them, and a Mac+can keep most of its swap in use for hours, so it would fire all day; the RAM pill's swap figure+lives in `MemInfo.display`, which nothing else reads. CLAUDE.md, Session memory.## Testingdiff --git a/docs/session-memory.md b/docs/session-memory.mdindex c7eb135dd..e338baeb2 100644--- a/docs/session-memory.md+++ b/docs/session-memory.md@@ -263,7 +263,7 @@ against a real machine, not that fixture's specific numbers.### Swap and kernel pressure in the pill (display only)-Added from the 2026-10-19 performance audit (roadmap #14). The pill said 86% "warn" while 8.5 GB+Added 2026-10-19, from a performance measurement on a Mac. The pill said 86% "warn" while 8.5 GBwere swapped and the kernel sat at pressure level 2, and nothing on screen said either.- **Where.** `MemInfo.display` — `swapUsedMb`, `swapTotalMb`, `pressureLevel`. darwin reads@@ -276,7 +276,7 @@ were swapped and the kernel sat at pressure level 2, and nothing on screen saidcopies its swap from the `/proc/meminfo` text already parsed. Linux has no kernel level; PSI isnot mapped to one because no threshold has been measured.- **Why a sub-object.** `hostUnderMemoryPressure` reads `swapTotalMb`/`swapFreeMb`. Filling those on- darwin would turn a healthy Mac (16% swap free on the audited one) into permanent "pressure" for the+ darwin would turn a Mac that keeps most of its swap in use (16% free on the measured one) into permanent "pressure" for thereaper. The pill reads only `display`; nothing else does.- **The tint.** `max(used-% threshold, kernel level)`: the level can raise the colour, never lower it.- **No fake zero.** No `display` → no swap text. A measured 0 used is stated in the title only.@@ -284,7 +284,7 @@ were swapped and the kernel sat at pressure level 2, and nothing on screen said### "nodeterm itself" in the panel-Roadmap #4 of the same audit. The GPU helper's real footprint was 1557-1845 MB (window swap chain,+From the same measurement. The GPU helper's real footprint was 1557-1845 MB (window swap chain,raster tiles, terminal WebGL buffers, driver memory) while `ps` rss said 96-153 MB; the pill countedit in the host total, but the panel never attributed it.@@ -302,7 +302,8 @@ it in the host total, but the panel never attributed it.- **CPU** is lifetime CPU time per group, not a percentage (`percentCPUUsage` returns 0 on itsfirst call, and the sweep takes one sample).- **Owed.** Panel GPU figure within 5% of `footprint <gpu pid>` and not equal to `ps rss`, on a- real build.+ real build. The Linux (VmRSS) and Windows (working set) legs are unit-tested only; neither has+ been checked on a real machine.## 6. The SSH leg