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.
Contributing to nodeterm
Thanks for looking. This file is the short door: enough to get running, plus the house rules that
actually get a pull request sent back. The long version — every subsystem and the reasoning behind
its invariants — lives in CLAUDE.md at the repo root, which is also loaded automatically if you
work with an AI coding agent.
nodeterm is licensed BUSL-1.1 (converts to MIT after four years — see LICENSE). Contributions
are accepted under that license. Its Additional Use Grant does not cover production use of a build
whose license or usage-limit checks were removed or bypassed; changing that code in a PR here is
ordinary work.
Getting set up
You need Node.js 20+ (22 for the Server Edition) on Linux or macOS 12 Monterey or newer — the macOS floor is Electron's and esbuild's, and the README's Build from source section says what fails on an older Mac.
npm install # also patches + rebuilds node-pty against Electron's ABI (postinstall)
npm run dev # dev mode with renderer HMR
npm run typecheck # tsc for both the node and web projects — the fastest correctness gate
npm test # vitest, unit + integration
On Windows, run bootstrap-windows.bat instead of npm install. It verifies the Visual Studio
C++ workload and its separately installed Spectre-mitigated libraries before compiling node-pty.
It also shields MSVC addon builds from the clang/lld ThinLTO settings inherited from Node 26; a
plain npm install under a stock Node 26 with node-gyp 12 otherwise fails with LNK1117.
npm run server:dev boots the Server Edition (browser UI) if you are working on that surface.
If src/main/node-pty-patch.test.ts is red, your node_modules is unpatched — not your code.
Run npm run rebuild. node-pty 1.1.0 leaks a pty device per spawn on macOS
(node-pty#950) and, on Windows, leaves a
conhost alive per killed session (its exit thread deletes the ConPTY baton without closing the
HPCON); we patch both sources before electron-rebuild compiles them, and that test guards the
patches surviving upgrades.
The same goes for src/core/speech/smart-whisper-patch.test.ts: scripts/patch-smart-whisper.mjs
adds an AVX2 build of whisper.cpp beside the baseline on Linux x64 (issue #1267, ~10× faster
dictation), and npm run rebuild applies it.
After the rebuild, scripts/stage-conpty-dll.mjs copies node-pty's bundled conpty.dll +
OpenConsole.exe back beside build/Release/conpty.node on Windows (the rebuild deletes them);
without them Windows terminals fall back to the inbox ConPTY, where a fullscreen TUI cannot scroll.
Where code goes
The repo is split by Electron process boundary and the split is enforced, not advisory:
| Directory | What lives there |
|---|---|
src/core/ |
Electron-free service core. Talks to its shell only through CorePlatform. |
src/main/ |
The Electron shell around src/core — windows, IPC, dialogs. |
src/server/ |
The Server Edition shell (browser UI over WS-RPC). |
src/preload/ |
The only bridge: contextBridge exposing window.nodeTerminal. |
src/renderer/ |
React UI. Reaches main only through window.nodeTerminal. |
src/shared/ |
Types and IPC channel names imported by all sides. |
src/core/no-electron.test.ts and src/server/no-electron.test.ts fail if src/core or
src/server import electron or ../main/*.
Put new service logic in src/core behind CorePlatform, not inline in src/main. That is the
seam the Server Edition boots from; logic left in src/main silently does not exist there, and the
boundary tests cannot tell you a feature is missing. This keeps happening to the same subsystem:
the ⌘M transcript read and then the context meter's context:ensure both shipped desktop-only, and
in both cases the browser cast the message into the void and the feature just looked empty. If your
handler needs something only Electron has (an SSH ControlMaster, a native dialog), make that an
injected dep whose absence is a documented degrade — see registerTranscriptIpc /
registerContextEnsureIpc — rather than a reason to keep the whole handler in src/main.
Windows agent messaging: direct ConPTY terminals are looked up by the runtime node index,
not the persistence key. NativeWindowsPane checks console membership, the unambiguous native
process chain and process birth times, and frames paste only after the terminal requested it.
Do not replace that read with a stored agentId or the restart heuristic's deepest descendant.
An interpreter such as node is named by its script's package bin entry, never as node, so
npm-installed CLIs such as Codex are recognized. A session released by park expiry or offscreen
release is still messageable: existence and routing ask the backend, not the attached client.
Both Windows owner reads (session host and direct ConPTY) go through a PowerShell probe that takes
seconds when cold, so they get their own WINDOWS_PANE_PROBE_TIMEOUT_MS through
PtyManager.paneProbeTimeoutMs, derived from the probe's own deadlines
(session-host/windows-probe-budget.ts) — change a probe deadline there, not a literal; ssh and
tmux keep the 2 s bound. A shell that wires agent messaging must forward that optional dep.
Never put the submitting Enter in the same write as a message paste: core/settled-submit.ts
pastes, waits for the envelope to render, then submits separately, on every backend.
The persistent session-host transport has its own versioned messaging extension: the host checks
its session generation, OS process identity and emulator before writing. An older live host keeps
its terminals and refuses the extension; never restart it automatically or fall back to sendKeys.
Message dispatch publishes pending canvas edits before main resolves scope, without overwriting
an 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 go
through 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 does
not model, exclude it in heldLaunchIntentFor, or the Windows pane launches without it.
Held launches are claimed by the core, not by a tab. Every viewer of a project runs the
canvas launch loop against its own copy of the nodes, so a per-tab check cannot stop two Server
Edition tabs from typing the same launch (#1173). A launch path must claim through
commitLaunchAttempt with its claim (workspace.claimLaunch) and treat the elsewhere
outcome as "another viewer is typing it": no input, no state change, no failure.
Claude usage identity is scoped to the same config directory as its credentials. Read organization metadata even when credentials already include an email, and degrade to the email-only row when metadata cannot be read. Managed usage must never fall back to an unscoped system Keychain token: that would label one account's limits with another account's organization.
Context-link maps authorize reads. Publish changes to edges, linked metadata, and background projects independently of canvas geometry updates; a debounce reset by every node render can starve publication indefinitely. Only merge projects owned by the same core, and use the rendered canvas's project epoch during tab switches. Core must revoke removed links before asynchronous transcript discovery or debug-file writes finish; an older write must never restore that access. Coalesce renderer updates before building the workspace map, without resetting the scheduled task. Intermediate publications retain resolved transcript paths only for unchanged identities; changing a session/account/location/hook path or removing the target invalidates that cache immediately.
Windows updates (unsigned beta): release-win builds dist:win:release (nodeTermUpdates=manual)
and uploads latest.yml, so the app shows a passive "new version — Download" card; it never
downloads or installs, and main refuses restart-to-update for any non-self-installing build.
Keep local dist:win on disabled, and never upload Windows *.blockmaps until signing lands.
Updater UX: an update-check button must call checkForUpdatesNow() (state/pendingUpdate.ts) —
the card treats every other check as automatic and silent. Never flip quitting flags before
the install can start (macOS waits for Squirrel.Mac); see CLAUDE.md "Packaging & auto-update".
Windows installer safety (#829): build/installer.nsh overrides NSIS's process-killing check.
A running app or session host blocks install/uninstall, and a failed process query blocks too.
Never restore automatic host termination: quitting the app preserves those live sessions.
Update preparation must keep saved canvas nodes: exit programs normally, quit, then have the user
verify and stop any remaining host. Never recommend End session (it deletes nodes). Cold agent
resume depends on supported, saved conversation history; it does not preserve running tasks.
See docs/windows-session-host.md for the user-controlled preparation/recovery steps and limits.
Prepare for update (#829 step 2, Windows only): ⌘K / the update card run
components/PrepareUpdateDialog.tsx over the pure lib/updatePrep.ts plan. It refuses while any
session's agent is working or waiting on the user (renderer store OR core mirror — unmounted nodes
have no renderer state), asks idle mounted agents to /exit through registerAgentUpdateExit,
confirms what still stops (Cancel focused), then sends the host's shutdown command and quits only
once the host process is confirmed gone. shutdown is a negotiated hello feature: never send it to
a host that did not advertise it, and never add a taskkill/name-kill fallback — an older host gets
the manual steps. The flow never deletes a node. Server Edition: degraded stub (unsupported).
A host classified staged (runs from its %LOCALAPPDATA% copy) only needs a quit, so the dialog
leads with "Quit nodeterm (sessions keep running)"; unknown must never be treated as staged.
The NSIS preflight waits (bounded, exit 10 only) in silent/--updated runs and never kills.
Staged host runtime (#829 step 3): a packaged Windows build launches the host from a private
copy, %LOCALAPPDATA%\nodeterm\session-host\<version>-<fingerprint>\nodeterm-sessionhost-v2.exe
(src/core/session-host-runtime.ts), so it maps no installed file and no longer blocks updates.
Rules: a copy is launched only after it was published by one rename of a hash-verified,
smoke-tested temp dir (marker written last); the image name must stay unlike nodeterm.exe /
nodeterm-session-host.exe (old uninstallers match those by name machine-wide); every staging
failure falls back to the legacy in-install-dir launch, which the preflight still blocks on; old
copies are deleted only after a SUCCESSFUL process query shows nothing runs from them and the
directory can be renamed aside. The host protocol stays additive-only — an older host is kept and
used, an incompatible one is left running and reported, never killed.
Three surfaces
A feature is not done until you have decided how it behaves on each — even if the decision is "not applicable here":
- Desktop (Electron)
- Server Edition (Linux, browser)
- Mobile companion — nodeterm mobile, two private repos:
nodeterm-ios(SwiftUI) andeneskirca/nodeterm-android(Kotlin, in development). You cannot open a PR against either, so this is normally a follow-up note rather than same-PR work: say in your PR what the mobile side would need, and mention @eneskirca so it gets picked up there. "Not applicable" is a fine answer — just make it a stated one. Never assume the phone is an iPhone in desktop copy or defaults.
Anything reachable from window.nodeTerminal needs a real implementation in
src/renderer/bridge/, or a deliberate, documented degrade. The satisfies NodeTerminalApi gate
forces you to declare every member, but a no-op stub compiles fine while doing nothing.
The canvas and the kanban board are two views of the same nodes. When you add something to a
canvas node — a header action, a badge, a menu item — ask whether the board's card and card modal
need it too, and wire it in the same change. The global (Omni) board shows all open projects as
stacked swimlanes; it is off by default (settings.omniKanbanEnabled), has a dedicated remappable
shortcut (view.globalKanbanToggle), and can be made the default for Cmd+Shift+B via
settings.omniKanbanAsDefault — see CLAUDE.md for the full invariants.
Node actions live in one builder. A row that acts on a canvas node — a menu item, a switch, a
picker — goes in renderer/lib/nodeActionItems.tsx, never inline in Canvas.tsx. The canvas node
menu, the sessions-sidebar row menu and both kanban card menus (through
components/kanban/cardMenu.tsx) build from it. Decide in the same change whether a card offers
the new row: a card takes only BOARD_NODE_ACTION_IDS, and a row that acts on canvas position goes
in BOARD_SPATIAL_ROW_IDS instead. The card modal's ⋯ menu takes BOARD_MODAL_ACTION_IDS through
its sessionActions prop, closes the modal before the action runs, and is absent when the card has
no session row. Remember the board acts on nodes of projects that are NOT on the
canvas (the Omni board): write through Canvas's nodeWritesFor(projectId) (built on
createNodeWriteRouter, lib/nodeWriteRouter.ts), never a live-canvas callback, and report a failure with a nodeterm:toast.
lib/nodeActionItems.guard.test.ts fails on a second copy of the rows.
A board card's source is a registry entry, not a branch you add at a call site
(renderer/lib/kanbanSources.ts). Declare the source once — filter label, placement
(assignment = the board's own persisted assignments, provider = the provider owns the column),
in-column lane order, whether it is configured for a board, whether it is readOnly (the
board never writes it: no drag, no move control) — and give it its one leaf (a card component and
the list path feeding it). Columns take lanes and name no source; the drag path branches on
placement. If you find yourself writing === 'github' outside the registry, the registry is
missing a field.
A board feature has to say which of three tiers it lives in: a board fact is shared content
in project.kanban (.nodeterm/project.json) — optional, sanitized in sanitizeKanban
(core/workspace-files.ts, which every load and save seam runs) and harmless to an older build;
a display preference is per-user localStorage (state/kanbanDisplay.ts); a filter on live
agent state is component state and is never persisted. An unanchored card move lands at the TOP
of its column; only a positional drop asks for the bottom (AT_COLUMN_END). Card order is a
rank string, and every write — renderer or core — goes through placeAssignment
(@shared/kanban-order), which also keeps the assignments ARRAY in rank order for builds that
ignore rank; never splice the array by hand. A saved view's query is built only by viewQuery,
so the live-state chips can never be saved into one. Board keys are
registry commands in the board scope — the only scope allowed a bare letter, because it never
fires while typing or in a terminal.
Anything that starts an agent by itself (board dispatch is the first) takes its consent from
machine-local settings and its trigger from a gesture the person made in this app — never from a
label, a column or a file that can arrive from GitHub or a git pull — and its consent binds what
it consented to (board dispatch binds repository + column title + label, not a bare column id).
Board dispatch's one trigger is KanbanView.moveIssueByUser → onIssueMoved → decideDispatch,
and a run starts only through dispatchStart, from that decision or from the queue drain after
recheckQueued; lib/board-dispatch.guard.test.ts fails if a new caller of any link in that
chain appears, or if anything but dispatchOnUserMove creates a queued entry.
A card chip that reads agent state subscribes to a primitive signature of the nodes it shows
(teamProgressSig, issueRunChipSig), never to the whole agentStatus.byId map — that map changes
on every hook event of every node. A field of agentStatus that is persisted across a restart is restored
as a record of the past, never as live state: lastSeen orders and ages sidebar rows but never
becomes state or Eco's idle clock (lastEventAt). Before a card shows a fact, check that its place on the board
does not already say it (lib/cardRedundancy.ts); the card modal keeps every fact the card drops.
project.ropes / bridges are hostile input like the board: they are admitted through
sanitizeLinks on every load and save seam, and a reader still tolerates anything. A wait rope
(--after, the verify panel) is minted with waitRopeId (ctrl-after-<dep>-<node>), never with the
opener's ctrl-<source>-<node> shape: rope ORDER does not survive the canvas pruning ropes to
deleted nodes, so the id is the only thing that tells a wait from an opener. A node opened by a
control verb also RECORDS its opener (data.openedBy); readers that ask "who opened this"
(stationsByOpener, the station-failure notice) prefer that record and still require the opener's
rope to exist. In the renderer that rule is ONE function, openerByTarget (lib/teamProgress.ts):
team progress and Tidy canvas both read it, and so must anything new that asks "who opened this
node" — and pass the rope id through, or every wait reads as an opener.
Before adding a GitHub read, check what the existing poll already fetches. Pull request cards
needed no new request at all: /repos/{repo}/issues returns pull requests, and the client used to
discard them. /repos/{repo}/pulls looks like the obvious endpoint and is the expensive one — it
ignores since, so it can reuse none of the incremental machinery, and its items are ~3.5× the
bytes. CLAUDE.md's kanban section has the measurements and the eviction rule that keeps the issue
lane unaffected.
Three rules for any new GitHub call (CLAUDE.md's kanban section, "Sync foundation", has the why):
- Never decide what a failure means yourself. Pass it through
classifyGitHubFailure(core/github/failure.ts). Onlyunauthorizedmay ever read as "signed out"; a rate limit, an outage or a dropped connection must say so instead, or the user re-authenticates an account that is fine. - Go through the request coordinator and a client built by the host. That is what feeds every
response's rate budget to the coordinator, pauses background work below the floor and caps waits.
A request that bypasses it is invisible to the budget. Prefer a conditional request
(
If-None-Match) for anything you poll: a 304 is free. - A write whose meaning comes from the project file needs
context.mappingApproved. The column mapping is git-shared; approval covers it, and reads do not need it. - Only a completed scan moves the incremental cursor.
lastSuccessfulRefreshAtis the next scan'ssince; a write that folds one issue into the snapshot must leave it alone, or other people's changes from before the write wait for the daily full pass. - GraphQL spends a different budget. GitHub meters
graphqlapart fromcore; ask the coordinator with the resource (throttle(identity, now, 'graphql')) and let a primary limit carry itsresource, or a spent GraphQL budget stalls REST issue sync. A GraphQL field the token may not read comes backnullplus a FORBIDDEN error — decode that as "hidden", never as its empty value (a null check rollup alone means "no checks").
Do not add a field inside ProjectKanban.meta[] entries: every card-meta setter (assignees, due,
priority, labels, the phone's label verb) rebuilds the entry from a fixed list and silently drops
anything else. Board-level fields survive every transform — pullLinks is one.
House rules
Check
src/sharedbefore writing a two-line helper. A JSON-object guard (isRecord), an error's message (errorText),sleep, the root-space parent walk (rootPositionWith) and the credential-store temp sweep (sweepForeignTempFilesincore/fs-atomic.ts) each existed in five to twenty-one hand-typed copies until #1252's follow-up, and the parent walk's copies had already drifted apart on corrupt canvases. A local helper that shares a name but behaves differently (zellij'serrorText, windows-conpty's array-accepting guard) is not a copy; leave it alone.Typing into a pane by node id goes through
PtyManager.sendPaneKeys, and an SSH-project node is never read or typed into on the local tmux socket. An unmounted remote node resolves throughremoteNodeOwneror is refused (not-connected);paneCommand/paneOwnerresolve unmounted nodes only with the explicit{ resolveUnmounted: true }option. See Bulk pause inCLAUDE.md.A node id never reaches tmux as a bare
-t. UseexactPaneTarget(=nt-<id>:) orexactSessionTarget(=nt-<id>) fromcore/tmux-naming.ts, and single-quote it on a remote command line (zsh expands a leading=). tmux prefix-matches a bare target on a miss, sont-x-1reaches a livent-x-12: a relay peer naming a prefix typed into, read and killed another project's terminal (security audit F1/F2).pty-exact-target.realtmux.test.tsdrives a realPtyManagerto prove it; see "Exact tmux targets" inCLAUDE.md.A relay peer's node ids, presence and shared folder are judged host-side. A scoped guest's newly introduced node unlocks only its own
newOnlyspawn, presence reaches a non-editor only for peers on its shared projects, and a project rooted at/,$HOMEor an ancestor of either is never shared (core/relay/share-root.ts). A UI that hides an option is convenience; the policy incore/relay/is the gate. See "Remote access" and "Hosted team relay" inCLAUDE.md.Branch labels describe a checkout on one core. Share existing status reads through
renderer/state/gitBranches.ts; do not cache a branch forever by project id or copy a project branch onto worktree nodes. Source, Sessions and worktree headers consume the same observations, keyed by API identity, exact cwd and (for SSH) project identity. Never probe an SSH cwd locally from a background header: only the active SSH project is git-routable. SSH headers observe Source refreshes instead.Pty input is filtered for exactly one thing: duplicate Device Attributes answers. Every viewer of a session (browser tabs, a kanban card modal, a relay peer) answers the tmux client's DA handshake, and tmux types every answer after the first into the pane.
core/da-reply-gate.ts, inPtyManager.write, lets one DA1/DA2 reply through per query seen on the output and drops the rest. Do not widen it to "anything that looks like a terminal report":ESC[1;2Ris both a CPR and Shift+F3, and a filter that eats a keystroke is worse than the bug (see CLAUDE.md → Terminal session continuity).A port is a node's only if its listener is in that node's process tree. Dev-server discovery (
core/dev-ports.ts) attributes ports by socket ownership and never connects to anything. A new consumer reads the scan, it does not add a probe. A forward (core/remote-ssh/port-forward.ts) binds127.0.0.1only, keeps the same port number or refuses with the reason — a different local port is only ever the person's explicit choice — and never forwards a port below 1024 unasked. The renderer passes a node and a port, never an address: core re-scans and decides the host-side target. Treatss/lsof/lsoutput as attacker- influenced text: a process name is chosen by the process, so parse each owner group on its own and never let a name reach a pid (see CLAUDE.md → Dev-server ports).App-originated text goes only into an empty prompt. A note nodeterm types into an agent on its own (the context-link discovery note, a sticky pushed over a note link) goes through
linkNoteRefusal+pty.sendToEmptyPrompt, never a barepty.sendText:sendTextpastes and presses Enter, so it submits whatever the user had half-typed with it (#1144) and answers an open permission dialog. Emptiness is read off the screen (readClaudeComposer), so an agent without a measured composer reader gets no note — and a skipped note is named in a notice, never silent.A GitHub issue reaches a pane only as a validated reference. Issue titles and bodies are written by strangers on public repositories, and a launch line is typed into a shell. Anything that starts or instructs an agent about an issue goes through
@shared/github-issue-ref:issueLaunchPrompt(the only composer, which re-validatesowner/repo#Nitself) for text, andnormalizeIssueRefwherever a storedissueRefis read — it comes from a git-shared file. Never interpolateissue.title/issue.bodyinto a prompt, and never add a path that posts an agent's output to GitHub on its own: posting is public, and only the user asks for it.A comment in the board log is text, never a trigger. A board comment that @mentions a session is delivered to that agent (
deliverBoardCommentFromUi, through the ordinary agent-messaging gates) only from the comment composer's send, with the text the user just typed, in the desktop app's own window. The log is a shared file — a git pull, another instance, a relay peer or a team-presence guest can put a mention token into it — so nothing that loads, reloads or renders it may reach a delivery.board-comment-trigger.guard.test.tsfails on a second call site, and the IPC is a raw main-window-onlyipcMainhandler (never on the peer-dispatchable platform table).Hook decision JSON is built in core, never in the renderer or the script. To answer a held Claude permission request with more than
allow/deny(a plan's follow-on mode, a question's answers), send aPermissionAnswerthroughanswerPermission;core/agents/permission-decision.tsvalidates it against the pending request file on the agent's host and writes the JSON. The managed hook prints a JSON answer only after a strict prefix/size/one-line check, so a new decision shape must passisBoundedAnswerContentor it is silently ignored. Answer content never goes on an argv. Seedocs/hook-reply-approvals.md.NODETERM_NODE_IDis inherited, so a hook event's node id is not proof it is that node's session. A detachedclaude -pstarted from a node, or Claude's own daemon hosting a fork, posts hooks under the node's id (and its token). Claude events passcore/agents/claude-pane-origin.tsin the hook server before ANY listener: the managed script reports$CLAUDE_PID's foreground flag and tty, and only the pane's foreground claude speaks for the node. Do not add a listener that runs before that gate, and do not "fix" a stuck node by loosening it: missing facts already fail open. Both shells callwireClaudePaneOrigin(pinned byhook-verified-parity.test.ts).Never call the user's machine a Mac in user-visible copy. Use
thisMachine()/thisMachineCap()/machineNoun()fromsrc/renderer/lib/machineName.ts— "this Mac" on macOS, "this PC" on Windows, "this computer" elsewhere and in any Server Edition browser tab (where the machine being described is the SERVER, whose OS the viewer cannot know). Issue #563: ~30 strings said "this Mac", including "This Mac is not authorized on this license" and "a teammate on a seat can run commands on this Mac" — the one sentence a user has to trust before handing out shell access.machineName.guard.test.tsscans non-comment lines and will fail your PR; copy that really is macOS-specific (the ptmx-limit banner, the notch step) is exempt by name with its reason. Comments are not scanned.Bottom canvas pills must leave room for the measured dock.
CanvasPillsbounds their row and moves it above the dock when the side budget is too small. Only usage summary text may truncate; keep refresh outside that overflow and keep the row free of stacking contexts so popovers can still clear the sidebar/board.scripts/usage-layout.test.tsverifies real Chrome layout and hit targets (setCHROME_BINwhen Chrome is not at the Linux default path).An overlay you lay over a live terminal steals its wheel — give it
pointer-events: none. Wheel routing is a per-packet hit test onclosest('.nowheel')(ours inCanvas.tsx, and React Flow's ownpanOnScrollindependently), so the element under the pointer decides, not the node..term-node__xtermcarries the class and covers the whole body, so a banner drawn ON a running terminal takes those pixels out of the terminal's wheel area and hands them to the canvas — the user scrolls and the canvas slides instead..term-node__uploadand.term-copy-pillwere alreadypointer-events: nonefor this;.term-node__stalecwdwas not (issue #767), andcanvas/terminal-wheel-boundary.test.tsnow fails on the next one. An overlay that REPLACES a dead view keeps the canvas wheel on purpose — there is nothing underneath to scroll. Same rule one layer up: do not "fix" a routing question by movingnowheeloutward, because a second consumer reads the class and no per-element opt-out can reach it. Deep version: CLAUDE.md § Terminal node lifecycle.The node colour palette is ONE list, and it is also the control boundary.
src/shared/node-colors.tsis what every picker draws and whatnodeterm color --color Cvalidates against — so a colour the UI offers and a colour the CLI accepts cannot drift apart. Its agent section is DERIVED fromAGENT_CONFIG, never re-typed: add a builtin agent and the palette grows by itself. If you are adding a surface that lets someone choose a node colour, render<NodeColorSwatches>rather than mapping the array yourself (a guard test fails on a hand-rolled swatch row) — and if the value will be drawn as TEXT or as an opaque fill under white, takeSYSTEM_NODE_COLOR_SWATCHESinstead, with the contrast reason in a comment. Deep version, including the measured numbers: CLAUDE.md § Node colors.The Antigravity hook is a gate in front of every
agytool call on the machine — treat its stdout as a decision.agyreads hook stdout as JSON and our hook, in the global~/.gemini/config/hooks.json, is subscribed toPreToolUse. Measured: silence runs the tool, but{}, any stray non-JSON byte and a non-zero exit DENY it — in nodeterm and in the user's own terminals. So: change answers only inantigravity-decision.ts(the one table); print nothing after the answer; keep the Windows command free of quotes (agy escapes them as\", which cmd.exe cannot read) and test Windows dispatch WITHOUTwindowsVerbatimArguments; keep theAutoRunrefusal. Deep version:docs/antigravity-agent.mdand CLAUDE.md § Agent support.On Windows, only claude runs POSIX. Claude Code runs hooks and tools through Git Bash; codex, gemini, grok and copilot run them in PowerShell/cmd.exe. So a hook command or a "run this shim" line for any other agent goes through the
.cmdhelpers insrc/core/agents/hooks/windows-hook-wrapper.ts/shared/agents/shim-invocation.ts, and every builder takes the RUNNING machine's platform with a POSIX default — neverprocess.platforminside a builder an SSH installer also calls. Deep version: CLAUDE.md § Hook installers.Finding
agyfor hook installation is not enough to launch it. The measured Windows installer wrote%LOCALAPPDATA%\agy\bininto aREG_SZuser PATH, so command lookup kept the percent expression literal andagywas not found even though its executable existed. Local Antigravity PTYs therefore APPEND the directory returned by the same vendor-location lookup the hook installer uses, and only when no PATH entry already names it (pathWithAgyDir) — never prepend: on macOS/Linux agy lives in a shared directory, and moving it ahead of the user's entries shadows their own tools. Keep that correction scoped to Antigravity sessions and out of SSH sessions. (The separate WindowsPath→PATHkey fix-up applies to every Windows spawn.)Our hooks.json bundle is the user's to switch off.
"enabled": falseonnodeterm-statusin~/.gemini/config/hooks.jsonis agy's own switch and nodeterm's only opt-out; the installer carries it across every rewrite. hooks.json is published through the shared settings transaction (updateSettingsFile) — never a bare write, which replaced a symlinked file with a regular one.Every loosening of a security gate must be a SETTING the user can see and revoke. A "don't ask again" that lives only in a dialog is a permission granted once and never findable again. The canvas-control destructive confirm is the pattern to copy (
@shared/control-confirm): a CANCEL never grants anything, a waived action still announces itself on screen and NAMES the waiver that let it through, and which gates may be waived at all is a TABLE, not anifat each call site — so "this one can never be waived" is a tested fact rather than a line somebody forgot to write. What a dialog may grant is bounded by SCOPE, not by permanence. It offers, as radios visible from the start with "ask me again" selected, "don't ask again for agents in " (machine-local, keyed by project id, pruned likesettings.sidebarCollapsedItems) or "don't ask again in any project until nodeterm quits" (in-memory — notsettings.json, notlocalStorage, so quitting restores the gate). Hiding a reach behind a checkbox made it read as missing. The per-project answer can also be given up front from the project tab's "Agents may, without asking" menu; it writes the same machine-local map through the samewithProjectWaiver, never a second copy of the merge, and each row shows what the gate will actually do (projectWaiverState), so an app-run or global waiver is named rather than hidden behind an unchecked box. The machine-WIDE waiver stays Settings-only, because that is the one a stray click in a dialog that appeared under the user's hands must not be able to grant. Offering only the app-run one was its own failure: it is not what a user who ticks "don't ask again" means, so the real choices were "be asked forever" or "turn it off everywhere". Two rules come with the project scope: it is keyed on the project the call ACTS ON (canvas control routes by source, so that is often not the project on screen), and it is machine-local — never.nodeterm/project.json, which is git-shared, or a cloned repo could switch someone's confirms off.An agent may only reach settings through an ALLOWLIST, and every change asks. The canvas-control
settingsverb (src/shared/settings-verb.ts) reads and asks to change a short table of keys; anything off the table is refused by name, and a forbidden set (permission modes, accounts/credentials, node identity, browser control, telemetry, keybindings, confirm waivers) outranks the table — its test walks the table against the set AND a name pattern, so an entry that would let an agent grant itself a power goes red even when added on purpose.settingsis outsideCONFIRM_WAIVABLE_VERBS: a CLI that could waive its own confirm would make the confirm decorative. A capability change must land through the UI's own setter (setProjectCapability: file flag AND this machine's'kept'answer), never a hand-rolled flag write. Adding a key is one line in the table plus awhy. The Server Edition has no dialog, so it refuses every--setby name.A permission mode (or anything else) that rides
project.jsonis GIT-SHARED — never key a local gate on it alone.project.defaultPermissionModetravels to everyone who clones the repo, so binding a confirmation-skip to "the mode is bypassPermissions" would let a cloned repository silently switch off a user's destructive-action gate. The rule that came out of it: askresolvePermissionModeWithSourceWHO chose the value (project/global/default) and act only on the user's own machine-local choice — and keepdefaultdistinct fromglobal, because reading an unset setting as a deliberate choice is reading consent into silence. Anything machine-local goes insettings.json; nothing that grants a capability goes inproject.json. A machine-local DEFAULT for a project capability (agentMessagingDefault) is allowed only because it answers ABSENCE: an explicittrueinproject.jsonstill needs this machine's recorded answer, an explicitfalsestill wins, and "off" must therefore be written as a literalfalse. Read grants throughprojectCapabilityGrantedFor(project, cap, settings)— never the file bit.Nothing an agent asks for may take the user's screen. Canvas control routes by SOURCE: the request names the agent's own node, and the dispatch has to find the canvas that owns it. For years "that canvas is not on screen" was answered by switching the project tab — so a background agent's
closemoved a user who was typing in another project, applied that project's saved viewport, and took their camera and typing focus for a call they did not make. Every verb now has a decided off-screen behaviour (src/shared/control-off-screen.ts) and none of them is "travel": it is answered against the owning project's serialized nodes, or REFUSED with a reason the agent can act on. If you add a verb, give it an entry — a refusal beats a hijack, and a verb with no entry falls into the generic refusal, which is fail-closed but is nobody's decision. Two traps the old shape hid: a verb body that resolves--nodeagainst the livenodesRef.currentwhile answering for another project silently acts on whatever the human is looking at (usectlNodes()), and readingactiveProjectIdinside a verb has the same bug (usectlProject). The guard istest/acceptance/control-verb-disposition.test.ts, which walks main's verb table against the renderer's dispositions — deliberately cross-layer, because that is the only way "every verb" is checked rather than remembered.A canvas-control verb that creates something must be safe to retry. An agent whose reply was lost (its tool call timed out, the tunnel dropped) runs the same command again, and the shim's endpoint walk re-posts on its own. The hook server's
/control/route — the one place desktop main and the Server Edition both sit behind — keys a ledger on (verified caller node, request id) and replays the first reply instead of running the call twice (src/core/control-request-ledger.ts). A new verb that opens a node, a team, a worktree or a frame joinsREQUEST_ID_VERBSin the same PR; the agent-facing text renders from that set. A handler that gives up before it knows whether its effect happened answersindeterminate: true, never a plain failure that says "safe to retry" — the retry would then open a second one. Anything desktop main does with a renderer answer belongs in itsfinishAnswerstep, which the forwarder also runs on a LATE answer (the one a retry is replayed): post-processing written after theawaitinstead runs only on time. Do not move the ledger into one shell's handler: the other shell silently loses it.A new way to hand a station work must feed
src/core/station-handover.ts. Plain--afterwould otherwise release a dependent on the station'sdonefrom its PREVIOUS task. Today the hand-overs aresend/reply(through the messaging layer'sonHandover) andwrite/run(noteControlAnswerin each shell's control handler — desktop main'sfinishAnswerand the Server Edition wrapper). A new verb that types a task into another node's pane joins that set in the same PR, on BOTH shells;src/main/station-handover-wiring.test.tspins the sites that exist.A new canvas-control open path must record who opened the node. When a station stops, the agent that opened it is told (
src/core/agents/station-notice.ts) — and a rope alone cannot say who that is, because an--afternode is roped to the stations it waited on too, with the same id shape. So every open verb stampsdata.openedBywhere it draws the opener's rope (lib/stationOpener.ts; the live paths get it fromconnect, the off-canvas and cold-open writes callwithOpenedBythemselves). An open path that ropes without stamping compiles and passes, and its stations fail in silence;src/main/station-notice-wiring.test.tspins the sites that exist. The notice text is app-authored and fixed — never add anything the STATION wrote to it (its output is exactly where an injection aimed at the orchestrator would come from).A location from
.nodeterm/settings.jsonis hostile input. That file is committed to the repository, so anyone who can commit wrote it. A worktree location it produces must passsharedWorktreeLocationRefusal(src/shared/worktree-location.ts) on every create path, and everygit worktree addpasses the real-path backstop inGitService.worktreeAdd. If you add another setting that names a place on disk the app will WRITE to, give it the same two layers: a lexical rule keyed onsource: 'shared', and a check on real paths where the write happens.A node you just created is not in
nodesRefyet, and asetNodesupdater is not "now".nodesRefmirrors React state at render time, so a frame made this tick is invisible to the next line that looks it up — and an updater runs at RENDER time, after any zustand write may already have flushed a render that mirrorednodesRefback to a list without it. Compute anything that readsnodesRef(parenting, a cwd, a position) BEFOREsetNodes, and when one flow creates a frame and a node inside it, do both in one synchronous block (attachWorktreewrites the new frame intonodesReffor exactly this). Every worktree creation goes throughcreateBoundWorktree(renderer/lib/worktreeCreate.ts); do not add a fourth copy of "git worktree add, then bind".A dialog raised on someone else's behalf must know that request's lifetime. Main abandons a canvas-control request after 120 s and tells the renderer nothing, so an unanswered dialog sat there forever AND held the one-confirm-at-a-time guard, which refused every later destructive verb with "a confirmation is already pending" for the rest of the app run — the agent, told the refusal was retryable, retried into it in a loop. If you raise a dialog for a bounded request, give it the deadline (
ConfirmState.expiresAt), import the bound rather than re-typing it, have it expire slightly AFTER the requester gives up, and answer with "expired" — never "denied by user", which claims a decision the human never made. Reach for the existinguseExpiringDialoghook rather than a second effect: the worktree-removal dialog needed the identical rule a day later, and two copies is how one of them quietly misses the next fix. Give the deadline only to a dialog an AGENT raised — one the user opened themselves must never vanish under them — and remember that clearing a dialog is not always just nulling its state (that one also has to release the ref its own busy-guard reads).An error must not name a remedy nobody measured — and the remedy needs its own test. The
unproven-target-ownerrefusal told its caller "Re-open the target node so its owner is recorded, then try again", and re-opening is precisely the attach that records nothing (ownership is recorded only on a genuine fresh spawn), so a caller that obeyed got the identical refusal forever. It shipped because no test read the sentence. When you write a refusal, pin its claim against the MECHANISM it describes — assert the remedy's precondition by calling the function that decides it, so the copy goes red when the behaviour moves — and remember who reads it: telling a language model to do something only a human can do is not advice.Anything path-shaped: Windows is a delivery target. Most of this was written on macOS/Linux, so the recurring defect is code that is genuinely correct on POSIX —
split('/'),startsWith('/')as an is-absolute test, a barefs.rename. Usepath.basename/join/sep, publish files withrenameAtomic, and write at least one test with a realC:\-shaped input. Guards enforce some of this and will fail your PR. In the Server Edition and relay tabs, the browser's OS is NOT the filesystem's OS: obtain the dialect from the core that owns the files, and keep an unobserved host unknown rather than guessing. Conversely, on POSIX a backslash is legal filename text — do not treat both separators as interchangeable unless the owning filesystem is known to be Windows.No unix sockets and no symlink privilege on Windows. A
ws+unix://dial (the Codex app-server) cannot work there — read the same fact from disk instead (managed Codex identity is theauth.jsonJWT email,codexAppServerReachableis the gate). An untypedfs.symlinkthrows EPERM on a stock account: link a shared asset throughlinkSharedEntry(src/core/shared-entry-link.ts— junction for directories, hardlink then warned copy for files).Anything tmux does for us on POSIX, the session host owes on Windows. The two delivery paths are not symmetric and the missing half fails in the direction that LOOKS like success:
sendTextridestmux paste-buffer -pon POSIX, which frames the payload from the pane's real bracketed-paste state and submits with a separatesend-keys Enter; the session host answered the same call with one rawtext + '\r', so a paste-aware composer swallowed the Enter as pasted content and an injected prompt sat there unsubmitted (issue #686). Before adding a delivery, a probe or a pane query, check what the tmux leg does with it and write the host's equivalent in the same change. The host can usually answer more precisely than tmux, because its headless emulator sees the pane app's own bytes — see CLAUDE.md's "We have our own VT emulator" for the one place that reasoning is inverted.An xterm-shaped buffer never takes the raw
tmuxScrollback. tmux'shistory-limitstores only used cells; an xterm buffer (the renderer, the Windows session host's headless emulator,NativeWindowsPane) allocates every line at full width. Size them withxtermScrollbackfromsrc/shared/scrollback.ts(≤ 10k), so the host never keeps history the renderer cannot show.The app's own environment is not the panes' environment. Whatever launched nodeterm (often an agent CLI's shell) leaves markers in
process.envthat describe THAT session.buildPtyEnvstrips an explicit list (TMUX,NESTED_AGENT_ENV_STRIP); add a name there, with its measurement, rather than a prefix sweep —CLAUDE_CONFIG_DIR/CODEX_HOMEselect managed accounts and must survive.A new session-host push frame must be negotiated at
hello, never just sent. An olderSessionHostClienttreats EVERY push frame whosetypeis notdataas an exit, and a long-lived host routinely outlives the app that started it — so a frame the connection did not opt into retires a live session. Add the capability toSESSION_HOST_FEATURES, send it only to sockets that listed it (thegeometrypush of issue #914 is the worked example), and pin that against the real bundled host assession-host/geometry-host.test.tsdoes. The same goes for a richer REPLY:listSessions' per-session rows ride thesessionDetailsfeature, and a host that never negotiated it answers{names}— which a consumer must read as "named, not described", never as "detached" or "no processes".Every xterm sizes characters through
activateTerminalWidths(src/shared/terminal-width.ts). The renderer's terminals and the session host's emulator must agree with each other, with tmux and with the agent CLIs about how many cells a character takes, or a repaint by cursor position leaves stale text behind (an emoji + VS16 did exactly that). Change widths there, never in one emulator, and test them on a real@xterm/headlessterminal rather than on the provider's return values.Finding a Windows executable is not the same as being able to spawn it. A PATH lookup may correctly resolve an npm CLI to
<name>.cmd, but Node'sexecFile/spawncannot execute that shim directly. For short-lived app-owned subprocesses, pass the resolved path and argv throughdirectExecutableInvocation(src/core/exec-path.ts): it uses hiddencmd.exewith explicit escaping, verbatim arguments and delayed expansion off. Do not fix this withshell: true; prompts and other user-controlled arguments would become shell syntax..bat/.ps1, CR/LF/NUL arguments and lines above cmd's limit fail explicitly. Keep stdin direct: PowerShell's text pipeline changes Unicode and line endings under Windows PowerShell 5.1.Need a POSIX
shon Windows? Resolve Git Bash, never spawn baresh. A stock Git install puts onlyGit\cmdon PATH.resolveWindowsSh(src/core/windows-sh.ts) walks Git's real layouts, then PATH minus WSL shims; the codex hook wrapper's batch candidate list is derived from the same data, so add a layout there, once. With no shell, say "Install Git for Windows" — the project setup-script runner is the worked example (it also setsCHERE_INVOKING=1, or Git Bash's login profile leaves the project folder). And do not type a chained command line (a && b '<x>') into a terminal for the user: PowerShell 5.1 and cmd parse it differently. Type one bare command and do the rest in-process (Source Control's publish fallback,lib/publishFallback.ts).Closing the window on Windows hides it to the tray (background mode), it does not quit. The relay host, hook server and notifications must outlive the window there as they do on macOS. Any new app-initiated quit (updater-style) must set
quittingbeforeapp.quit(), or the hidden window's close handler turns the quit back into a hide. Every new raise (show/focus) needs a user action and an entry inwindow-raise.guard.test.ts.The phone reaches a Windows desktop through the relay only. Everything the iOS app sends over SSH is POSIX sh plus tmux, and Windows OpenSSH hands out
cmd.exe, so Windows pairing installs no SSH key and requires remote access instead of an SSH server (src/shared/pairing-gate.ts). Do not "fix" this by installing the key intoadministrators_authorized_keys. The phone tries SSH before the relay, so a key that works locks it onto a path that cannot work. CLAUDE.md, "Remote access", has the details.A relay attach never decides where a session runs from what the phone sends. The phone's
pty.attachgoes throughPtyManager.prepareRelayAttach, which routes an SSH project's node over its project's master or refuses it, and gives a local node the env the desktop would. Never spawn a session for a phone-named node id directly (attachDetached/createDetached): that is how an SSH node became a local shell in this machine's$HOME. CLAUDE.md, "A remote node is NEVER spawned locally".Relay backpressure is undone by a drain sweep, never by the next chunk of output. A paused pty produces no next chunk, so a resume that waits for one never comes: that froze the phone's terminal for good after a single >8 MB burst.
host-service.tsarms a 250 ms sweep while a stream is paused, then repaints with a snapshot before it resumes — the same drain-sweep pattern ascore/ui-sink-registry.ts. 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. Node fields like
sshRemoteTmuxarrive through a sharedproject.jsonthat the host's own desktop and teammates also write, so a node without them must still never become a local shell (issue #1186).fileToProjectderives the routing from the project's SSH record, the file written back to the host stays neutral, and core refuses a local spawn owned by an SSH project (PtyManager.setSshProjectCheck). A new path that turns stored nodes into live ones or spawns a terminal goes through those, not through the node's fields alone. CLAUDE.md, "A remote node is NEVER spawned locally".A relay / team tab's node runs on the host, and the SESSION it mounts under decides that — the node may carry nothing that says "remote". A project shared from SSH with a team is adopted by the host, which drops
sshRemoteTmux/sshfrom its nodes, so they reach the tab as plain terminals. Four rules keep them off this core (bug F: a team tab's terminals became local tmux sessions here):- A node's session follows the project React Flow's STORE holds (
useFlowStoreOwner); never key a node subtree'sSessionProvideronactiveProjectId. xyflow copies nodes into its store one commit late, so a key on the active id remounts the outgoing nodes under the incoming session. - An unbound remote project resolves to the OFFLINE relay session (
sessionForProject), never the local one. Code asking "which live session is bound to this tab?" asksboundSessionForProject. - A surface that mounts a terminal outside the canvas (the kanban card modal — both boards live
under App's LOCAL provider) runs under
sessionForProject(<its project>)and providesOwningProjectContext: wrap it inProjectSessionScope(session/owning-project.ts). A new terminal-creating path also asksspawnBelongsElsewhere(isRemoteProjectId(<owning project>), session.source)before its first create; askisRemoteProjectId(session.ts), nevergetProject(id)?.remote, which misses a tab the store deleted. A component under it that keys data by project (the board log, card metadata, pull requests) readsuseOwningProjectId() ?? activeProjectId, neveractiveProjectIdalone: on the Omni board the card's project is not the active one, and itsuseSession()api answers for the card's project. - Core
joinrefuses (held-elsewhere) arequireRemotecreate onto a held session that is local or on another host, but a create that names nosshRemotestill attaches to a held REMOTE session, so core alone does not stop a caller that names only a node id. A new caller that creates a remote node passesrequireRemoteplus thesshRemoteit has, and treatsheld-elsewhereas a refusal that is NOT a lost connection (no reconnect, no drop report). Do not "fix" this by re-stampingsshRemoteTmuxonto those nodes: the host would then refuse its own sessions. CLAUDE.md, "Projects (tabs)".
- A node's session follows the project React Flow's STORE holds (
Read agent status through the node's session —
useSessionStores()/agentStatusForProject— neveruseAgentStatusdirectly, in any surface that can show a team tab's node. A team tab keeps its host's status in its own session store and shares node ids with the SSH project it was handed off from, so the default store answers for the wrong project. CLAUDE.md, "A relay session owns its agent status".Phone keys and store links are platform-neutral. New paired keys are stamped
nodeterm-mobile-<id>, but revoke must keep matching the legacynodeterm-ios-<id>stamp every existing iPhone carries (src/main/pairing-core.ts). Link to a store only throughmobileStoreLinks()insrc/renderer/lib/links.ts— the Play link stays hidden behindANDROID_APP_PUBLISHEDuntil the listing exists, and a guard test refuses direct store URLs anywhere else in the renderer.Relay pins are per role, and a revoke is one call. Pin a peer only through its role's store in
src/main/remote/approved-devices.ts(phonePinsis the only one anything auto-admits from — never write a desktop peer there), and revoke only throughsrc/main/remote/peer-revoke.ts, which unpins AND closes every live session on every host. A new host that serves relay peers mustregisterPeerSessionKiller, or revoking a device leaves its shell open. CLAUDE.md, "Remote access".A relay channel that names a project needs a row in
relay-project-scope.ts. A relay guest bound to one shared project must never reach another, and the jail is keyed on channel class: anything namedgithubIssues:*,board-log:*orprojects.*is refused on a scoped session unless that table can read its projectId. Add the row in the same PR as the channel, or the verb is refused for every scoped guest (andrelay-project-scope.test.tsgoes red telling you so).A new IPC channel a relay tab can call must be classified in
src/core/relay/access-policy.ts— the guard test fails otherwise. EveryIPC.*referenced by the relay API's builder functions insrc/renderer/bridge/ws-bridge.ts(the ones the guard's ownBUILDERSlist names) and bysrc/renderer/bridge/relay-api.tsgoes inVIEWorCOMMENTwith its own argument check, or in the reviewedEDITOR_ONLYset;src/core/relay/access-policy.guard.test.tsnames every one you missed. A NEW builder function must also be added to thatBUILDERSlist, or its channels are never scanned. A hosted team's Viewers and Commenters are refused anything unlisted, so forgetting is safe but silent, and the guard is what makes someone decide. Opening a channel to viewers also means adding it to the renderer's mirror,src/shared/hosted-access.ts(the same test pins the two lists equal). An EVENT a viewer must receive needs aVIEW_EVENTSentry, and no test forces that: without one, the event simply never arrives. Deep version: CLAUDE.md § Hosted team relay....and in
src/core/relay/scoped-guest-policy.tstoo. A Team Access invite that shares ONE project is served through that allowlist: every relay-tab channel is inSCOPED(with a check that its node / path / projectId belongs to the shared project) or in the reviewedSCOPED_REFUSEDset, andscoped-guest-policy.guard.test.tsfails on one that is neither. An unlisted channel is refused to scoped guests; an event they must receive needs to be attributable to the shared project (filterScopedEvent). Anything that touches the host's settings, credentials, license or pairing belongs insrc/shared/host-control.tsinstead — refused to every relay peer.A change to canvas content that does not travel as a
canvas:mutop is lost on a hosted core — route new content edits through the op vocabulary (src/shared/canvas-content.ts). On a Server Edition hosting a team, the canvas authority writes a shared project's nodes, edges and board from the ops it hears, and overlays every save with that content, so a content change that reaches the core only inside a save is dropped from disk. A renderer write into a project that is NOT on screen goes through the projects store, whose node and edge writers run insideownWriteso the write is cast (canvas/stored-publish.ts); a new store writer of that kind must useownWritetoo. Deep version: CLAUDE.md § Hosted team relay.A request that trusts a relay host key (host-token mint, host-mode push) proves possession through
src/core/relay/relay-pop.ts, and falls back to an unproven request ONLY on a 404/405 challenge. One exception, push only: a 200 challenge followed by a 404 from/v1/push/host-auth(possible only in a backend redeploy window) also posts unproven, and caches that verdict for 10 minutes; push stops nothing, and the backend gates the post regardless. The push webhook's management calls prove the same key through their own protocol (src/core/push-webhook.ts) — do not fold one into the other. Change the relay protocol andrelay-pop-vector.jsonmust change in both repos. Deep version: CLAUDE.md § Hosted team relay.A peer's X25519 key goes through
src/core/relay/e2ee.ts, never straight intonacl.box.before.deriveSharedKeyrefuses a low-order key (raw X25519 output all zero: the shared secret would be a public constant, the SAS a fixed value) andpublicKeyFromB64refuses non-canonical base64; a new intake of a key someone will PIN (an offer, a code, a QR field, a pin store) validates withpeerPublicKeyFromB64/isUsablePeerKeyB64and gets alow-order-keys.test-support.tstest. A new surface that SHOWS the SAS showsSAS_COMPARE_HINT(src/shared/remote/sas.ts) under it, and nothing compares SAS strings across builds (a v1 peer shows the first six of the ten digits). Deep version: CLAUDE.md § Remote access.Normalize BOTH sides of a path comparison, through one function. A marker normalized where it is built and matched raw where it is used is a no-op on the machine you wrote it on and a silent defect on Windows. That is issue #558: the managed-hook marker was folded to
/while the stored command still carried\, so nodeterm stopped recognizing its own hook entries and appended a fresh copy of all nine on every launch — nine hook processes per event, nine concurrent 45 s permission waits racing one prompt. Write the normalizer once, use it on both sides, and pin it with aC:\-shaped test.Orchestration state that must survive a restart goes through
src/core/durable-state.ts. The delivery queue, station reports and the--request-idledger are mirrored to<userData>/orchestration-state/by one module: add aDurableFactSpec(kind, version, a sanitizer that DROPS what it cannot trust, a cap) rather than writing another store. Decide — and write in the fact's header — what a restart MEANS for it (a TTL that kept running, a session that may have changed), load it at boot in BOTH shells after anything it reads (the status mirror), and test it by writing through one instance and reading through a new one. Never put it in.nodeterm/project.json: it is one machine's run state. CLAUDE.md § Durable orchestration state.Never publish a file with a bare
fs.rename. UserenameAtomicorwriteFileAtomicfromsrc/core/fs-atomic.ts. On Windows a rename fails withEPERMwhenever anything has the destination open — Defender scanning the file you just wrote, the search indexer, OneDrive — so the plain version loses saves intermittently and only on other people's machines. A test scans for this and will fail your PR;docs/atomic-writes.mdexplains why the retry is safe. Every temp/part staging name must also be unique per call across processes and cleaned by its owner — including paths embedded in generated SSH commands or handed to scp, which thefsscan cannot see. Keep a remote temp's own leaf bounded: extending an already-valid maximum-length target leaf with a UUID suffix turns an atomic write into a guaranteedENAMETOOLONGfailure.Never write a remote file with
cat > <file>. It truncates the file the moment the remote shell starts, and when the ssh channel dies before the body arrivescatexits 0 — a reconnect once left a host's canvas shims at 0 bytes with every agent call "succeeding" silently. UserunRemoteAtomicWrite/remoteAtomicWrite(src/main/remote-atomic-write.ts), which checks the byte count before renaming and throws when the write did not land, and for a file that belongs to the user (settings, config.toml, AGENTS.md) useupdateRemoteTextFile, which also keeps its symlink and mode. A guard test fails on a new barecat >. A remote runner RESOLVES on a non-zero exit, so check the result or use the helper that does.A new agent-facing doc on an SSH host goes into the agent-tools plan. The canvas/context shims, their skills and our instruction-file blocks are listed once in
remote-hooks.ts(canvasControlArtifactsand its siblings); the installers AND the connect-time freshness check (RemoteHooks.refreshAgentTools) read that list, so a host is brought up to your build's bytes on the next connect. A shim, skill or block written from anywhere else is written once and never checked again — hosts then keep the old text across app updates. This is ONLY for those docs: hook scripts and hook config stay insetup()'s ordered chain, and the endpoint file and node tokens carry credentials — never put them on a freshness cadence.Never write
chmod <mode> -- <file>into a remote command. macOS (BSD) chmod stops parsing options at the mode, so the--becomes a file operand and the command fails there while passing on Linux. To test it on Linux, put aPOSIXLY_CORRECT=1wrapper around GNU chmod first on PATH.A write ack is a claim about a WRITE, never about what the remote now holds. Do not retire state that records "the server still needs to be told X" just because the write returned true. The SSH mirror's writer acks the 5 s throttle's trailing write optimistically — it returns true and schedules the run — so a connection that dies inside that window leaves an ack behind with nothing on the wire. Deleting the deletion tombstones on that ack is how 16 terminals deleted on a slow link came back, announced as sessions from a phone the reporter does not own (
clearedNodes/confirmClearedDeletions,src/core/workspace-store.ts). Retire such state on a READ that shows the remote no longer has it — which is the same rule this codebase already applies in the other direction, "a failed read is never evidence of absence". And when you cannot observe where incoming data came from, do not name a source in the UI copy: a wrong attribution sends the reader hunting for a device instead of at the file.Never write to a child's stdin without an
'error'listener on that stream. A pipe write's failure is not a throw at the call site: when the child exits before draining stdin (a CLI handed a flag it doesn't know, an unreachable ssh host), Node re-emits the EPIPE as an async'error'EVENT on the stream — a try/catch around the write is inert, and the unhandled event crashes the whole main process with an "Uncaught Exception: write EPIPE" dialog (issue #382's class). Attachchild.stdin.on('error', ...)before the first write — log viaconsole.warnso the debug ring sees it, or settle the pending call; the child's exit code stays the authority on the outcome (seetmux-control-client.tsandpty-manager.tsrunWithStdinfor the house pattern). A test (src/core/stream-epipe.guard.test.ts) scans for this and will fail your PR.Never unmount, move or re-key a browser/web node's element. An Electron
<webview>'s guest process dies on DOM detach — and a detach includes anyinsertBefore/appendChildMOVE of an attached element, which React performs whenever a kept child's relative order among kept keyed children changes. That is why webview-hosting nodes render in one stable pool region at the tail of the<ReactFlow>nodes prop (renderer/lib/webviewKeepAlive.ts— read its header before touching the merge, the node array swap in Canvas's load effect, or anything that reorders nodes), and why a background project's pages stay mounted as hidden ghosts instead of unmounting.display:noneis safe (measured: state, scroll and viewport size survive); a reorder or unmount reloads the user's page and loses their in-page state.A
<webview>page's wheel never reaches the host DOM. The guest is an out-of-process frame: measured on Electron 42, physical Ctrl/Cmd+wheel reached the page and emittedzoom-changedon the guestWebContents, while no hostwheellistener fired. Keepnowheelon the webview host (it protects React Flow routing) and install page zoom in main throughinstallWebviewZoom; removing the class or adding a renderer wheel handler cannot implement guest zoom. The shared renderer controls call the same@shared/webview-zoompolicy directly on the attached guest.Rendered markdown goes inside a listed container. A link in
renderMarkdownoutput keeps its href as written, and a relative one used to navigate the whole app window away (the canvas was gone until a reload). One delegated handler (renderer/lib/markdownLinks.ts) intercepts clicks insideRENDERED_MARKDOWN_CONTAINERS; a new surface that injects markdown HTML must use one of those classes or join the list —markdownLinks.test.tsfails otherwise.A loading indicator is
components/Spinner, never a local spinner..nt-spinneris the one ring instyles.css, and it freezes underprefers-reduced-motion; a local copy is how a spinner kept rotating for users who asked for no motion, and how two rings swapped mid-load. Putrole="status"on the row holding the text, not on a second spinner beside it.
These are the ones that come up in review most often. Each exists because its absence caused a real bug.
A project-scoped lookup cannot prove a node does not exist elsewhere. Link refusals must name the project boundary and explain that cross-project linking is unsupported; do not scan other projects just to improve a missing-endpoint diagnostic.
A memory lever that drops a terminal's PTY client asks the live-work gate first
(terminal/live-work.ts): without tmux the pty IS the shell, and the "free" release kills the
agent in it. A hidden/minimized window feeds the existing levers by making every node read
offscreen (terminal/window-backgrounded.ts) — reuse that input rather than adding a parallel
release path that would have to re-implement every gate.
A failed read is never evidence of absence. "Could not measure" and "there is nothing" are
different facts and must stay distinguishable at every layer. Collapsing them is how a panel ends up
reporting "no sessions" on a host running thirty. When something ACTS on the negative, give it three
answers rather than two — present | absent | unknown (TranscriptPresence is the shape) — and let
only the positive finding trigger the action. Ask which of the two mistakes is recoverable: cold
restore wrongly resuming a dead session id costs an error line, while wrongly dropping a live one
opens a blank conversation over work the user believed was continuing.
Degrade to nothing, never to something wrong. A probe that fails means the bare, safe command — never a substituted nearest match. A hand-editable value that is unrecognised must yield the safe default, never something more destructive than the default.
A node's OWNERSHIP is persisted state, never a live object. "Is this node remote / whose host is
it on?" must be answerable with nothing attached, because the questions that ask it — a delete, a
kill, a cleanup — arrive precisely when nothing is: after an app restart, after the offscreen
release, after the park timer, for a project that is not open. PtyManager.runEndSession read it
off the dying in-memory Session instead, so an SSH node deleted with no live client had its remote
kill-session skipped in silence and its one kill sent to the LOCAL tmux socket, where a
requireRemote node has nothing; the node left the canvas looking deleted and its nt-<id> kept
running on the host. Ask the machine-local index (workspaceStore.sshProjectIdForNode), and treat a
live handle as the complement of that answer, not its source.
A side effect you could not deliver is not a side effect you performed. The ok:false rule is
not only for reads. catch {} around a remote kill folded "tmux says there is no such session" (an
ANSWER) into "the ControlMaster is down" (a NON-answer, session still running). Classify the failure
— and when the work genuinely cannot be done now, either refuse the action with a reason or write
the debt down and settle it later (core/pending-remote-kills.ts). Silently dropping it is the one
option that is never available.
Server Edition sign-in rules are load-bearing (security audit 2026-10; see CLAUDE.md →
Server Edition sign-in). A login attempt reserves its rate-limit slot before its body is read and
verifies with the async scrypt behind a 2-slot gate — never scryptSync, which stalls every
terminal. A new auth POST lives under /auth/ so the shared same-origin check (src/server/origin.ts)
covers it. Header trust from a loopback peer needs NODETERM_TRUST_PROXY_SECRET, which is read from
the environment only and never logged.
A Server Edition agent owns only nodes it freshly opened in this server run. The
creator ledger is process-local and must never be rebuilt from .nodeterm/project.json, titles,
hook history, or a surviving tmux name: all are writable or stale. A restart therefore clears
ownership, performs no node/session adoption, and leaves durable queued launches dormant. Metadata
mutations and message delivery validate every target before writing anything; missing proof is a
named refusal. Validate Server upgrades against a disposable data directory and port. Restarting a
shared live service is
an explicit operator action, never a test or an automatic repair step.
A canvas-control verb you add in Canvas.tsx does not exist on the Server Edition. The verbs
run in the DESKTOP renderer's dispatch; the browser bridge never subscribes to onAgentControl, and
the Server Edition answers /control/* itself (src/server/control-unsupported.ts), serving only
SERVER_V1_VERBS through the headless node factory. Everything else — list, arrange, move,
resize, place included — gets the named permanent control-unsupported-on-this-edition refusal.
So "it is in the renderer, so both shells have it" is false here; either add a headless action or
leave the refusal, and pin which in control-unsupported.test.ts. A new verb's flag gate goes in
src/shared and is called from desktop main's control handler too (it never runs
parseControlRequest), and a new verb should refuse a flag it does not read by name (#539) rather
than ignore it.
A plain terminal is not a Claude node. It may carry the generic node/endpoint wiring needed for
a hand-launched agent to report hooks, but it gets no NODETERM_AGENT_ID and no
NODETERM_CANVAS_CONTROL until the serialized node explicitly names an agent.
Re-validate hand-editable values at the point of use, not by their TypeScript type. Settings
come from git-shared JSON and can end up interpolated into a shell command line. The same goes for
node ids: a string built from them (a subscription signature, a claim or cache key) writes them with
JSON.stringify, never joined with a separator — an id containing | or : otherwise forges an
entry for another node.
Test generated shell for real. If you generate a shell command, run it under an actual
/bin/sh against a fixture tree. A composed fixture will not tell you that echo ##MEM prints an
empty line because # starts a comment.
Share with team's remote commands are generated shell, and so is their test. The probe, the
installer wrapper, the team invocations and the kill-verify are built in
src/core/remote-ssh/share-team-remote.ts and run under a real /bin/sh against a fake host in its
test; a change to one of them lands with a run there. The handover kill targets exact =nt-<id>
names on the host's node-terminal socket only — never the every-socket fan-out used elsewhere —
and it runs BEFORE the server core resumes on that same socket, so one conversation never has two
processes. See CLAUDE.md "Share with team".
Remote context polling must bound bytes before SSH transports them. Bootstrap from the
file's measured end, keep offsets in raw bytes, and distinguish an idle read from failure so
the poller can back off. A transcript that does not exist yet is idle, not a failure: Claude only
creates it on the first prompt, long after SessionStart handed over its path. Bootstrap history
restores usage only, never task/result events.
core/remote-ssh/transcript-window.ts and the real-shell remote-context tests pin this contract.
A shared agent daemon is live-session infrastructure. Codex's app-server control socket is
shared by every --remote TUI in an account scope, so stopping or replacing one daemon disconnects
every attached canvas node. A managed launcher must keep the already-bound thread under a bounded
supervisor: resume only when protocol health failed or the known socket generation changed, never
loop an unrelated client error, and never replay the original prompt after reconnect. Probe a
responsive daemon before invoking lifecycle repair; stale PID bookkeeping is not permission to kill
working sessions. See docs/shared-codex-node-identity.md.
A plain Codex TUI must not join Codex's own auto-started daemon. From codex-cli 0.157.0 a
plain codex starts (or joins) ONE background app-server per CODEX_HOME that keeps the
environment of the pane that STARTED it, so every later node's hooks and tool shells run with the
first node's NODETERM_NODE_ID (measured on 0.159.2). Every nodeterm codex line therefore ends in
--no-daemon when the CLI that will run it advertised the flag — added in the two assemblers
(shared/agents/launch.ts via withCodexNoDaemon), fed by ApprovalCaps.codexNoDaemon. A new
codex launch site goes through those assemblers and threads the caps; never type a bare codex line
yourself, and AWAIT ensureCodexLaunchCaps (bounded) where the site is async — a synchronous
read loses the race when every node cold-restores after a reboot. A relay tab or SSH node must be
passed as remote: the guest's or laptop's answer never applies to another machine's codex. The
flag must never meet --remote (codex refuses the pair), which is why the managed launcher strips
it. See CLAUDE.md "Codex's auto-started shared daemon".
Credentials never ride argv — local or SSH. Not a tmux -e pair, not curl -H, not a remote
command string. /proc/<pid>/cmdline is mode 444 on a stock Linux, and a remote command line is argv
on the host too: we shipped the hook bearer that way and any other account on the machine could read
it and open a terminal running an arbitrary command. Pass secrets by 0600 file or by stdin
(curl --config -), and never add an argv fallback. See docs/node-identity.md. That includes the
examples we SHOW users to copy (the push webhook's curl pipes its header on stdin, and a test runs
it under /bin/sh to prove it): a user pastes what we print into a CI job on a shared runner.
A hook socket path is not ownership proof. Never unlink a live listener to bind a hook
socket, or overwrite an advertisement whose socket/TCP listener still answers. Local stale cleanup requires ECONNREFUSED and an unchanged socket inode; regular files,
symlinks and uncertain probes are preserved. SSH setup allocates a fresh socket and publishes an
installation-qualified endpoint only after bearer verification. A wrong bearer answers 421 before
any handler runs; only that explicit wrong-owner response (or transport failure) permits endpoint
failover. A node-identity 403 stays final. Test with disposable sockets, never a running user's tunnel.
A hook-server client sends no Origin and a loopback Host. The server refuses both before
the bearer (a browser page, DNS rebinding included, is the caller this keeps out). curl, Node's
http and fetch, and Bun's fetch all comply as they are used today; a new client that sets an
Origin, or names the server by anything but 127.0.0.1 / localhost / [::1], gets a 403.
hook-server.browser-guard.test.ts drives the real transports — add yours there.
Both raw listeners change together — src/main/index.ts and src/server/agent-status.ts. A new
field on a hook event that reaches only the desktop leaves the Server Edition quietly without the
feature, and the boundary tests can only tell you an import is wrong, never that a field is missing.
The same applies to any hook-server signature change; this repo has shipped one to a single shell
three times.
A rule enforced at one mint site is enforced nowhere. Nodes are created on two surfaces — the
canvas (createAgentNode) and the phone's projects.registerNode (appendProjectNode) — and a
constraint spelled out inline at one of them silently does not exist at the other. "Which agents
bind a managed account" lived as a ternary in the renderer while the phone leg wrote whatever the
wire sent.
Put the rule in one predicate under src/shared and have every mint site ask it, and derive the
things that follow from it (a node's color, say) from that same call rather than re-deriving the
condition per caller.
A node field the canvas sets must be asked about on the phone leg too. The same two mint sites
again: createAgentNode gave every Claude node a persisted session id (data.agentSessionId,
launched with --session-id), and nothing asked what a phone-registered node should carry — so it
carried none, and depended on a hook event reaching the desktop for its chat view, its title and
its cold restore. When you add a field to the node a factory builds, decide in the same change what
appendProjectNode / RemoteNodeInput does for it, and whether the phone needs a host fact to
produce it (MirrorSettings is where those travel — see claudeSessionIdFlag).
A feature that creates links owes an ownership rule, and it must be a property of the plan.
"Share ~/.claude/skills with this account" (issue #643) links each system skill into a managed
account's own skills/ and removes those links again when switched off — one wrong removal deletes
somebody's real skills folder. Three habits made it safe and they generalize: link the LEAVES, not
the containing directory (nodeterm writes its own canvas skill into <configDir>/skills/, so a
directory-level link would have written it into the user's system folder); decide ownership by an
anchored SHAPE (a symlink at <name> pointing at <system>/<name>) so what the on-switch creates
is exactly what the off-switch removes, and a real directory can never qualify; and compare
REALPATHS before acting, because the hand-made version of the same feature makes the two directories
one and linking into it would plant links in the folder you are about to clean up. Verify the
removal against a real filesystem with real symlinks and real content — a mocked fs agrees with
whatever the code believed. And a launch-time sweep may re-create, never delete: ownership inferred
from shape cannot tell your link from an identical one the user made by hand.
Do not take scrolling away from tmux. It owns the mouse, the scrollback and the alternate
screen. A previous design moved that into the emulator and failed structurally; CLAUDE.md explains
why in detail.
A spawn-env write does not reach a tmux session on its own. The shared tmux server takes each
new session's env from its own GLOBAL env (inherited from whichever client started the server) —
the creating client's process env only matters for names listed in update-environment (or passed
as non-secret -e pairs). Setting env.FOO in pty-manager therefore works for the plain-shell
fallback and for the one client that happens to start the server, and silently does nothing (or
worse, leaks the server-starter's value into everyone else) after that. That is how issue #419
shipped: managed-account CLAUDE_CONFIG_DIR leaked into system-account sessions. New per-session
env either joins ACCOUNT_SCOPE_UPDATE_ENV / the gateway list, or rides -e — and gets a
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 the
first window exists, and a wedged server held an unbounded call for as long as it stayed wedged
(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.
The same goes for the CWD: a tmux client never runs in the node's directory. The server keeps
the cwd of the client that started it, and from tmux 3.7 a new pane's -c is silently dropped once
that directory is deleted — every new terminal then opens in the deleted dir (issue #1131, measured
on tmux 3.7c). The local tmux client is spawned from localTmuxClientCwd() (home, else /) and the
pane's directory rides -c only. The plain-shell fallback IS the pane and keeps the project cwd.
A new keyboard chord has to survive the shells, not just the renderer. The application menu is
ours (buildAppMenu in main/index.ts), but its command-style accelerators — ⌘Q, ⌘M, ⌘W, ⌘0, ⌘⇧B,
⌘, — are still handled above the page, so your keydown branch simply never runs: steal the chord
back in main/keydown-intercept.ts's before-input-event allowlist and forward it, like the three
already there. Two legs stand the menu down instead of stealing — the terminal-first policy and an
armed shortcut recorder (menuStandsDown → menuItemIdsToSuspend, since a disabled item suppresses
its accelerator) — and Reload (⌘R / ⌘⇧R) is the named exception that always stays with the app,
because it is the crash-recovery lever. Browsers own a different set. And any chord that reaches the canvas needs the two refusals every canvas shortcut
here has: not while the kanban board covers it, not while the user is typing.
A new chord needs no edit to the shortcuts panel — and must not get one. ShortcutsPanel
derives its whole inventory from COMMAND_DEFINITIONS (section per CommandGroup, label from
def.title, chord from the EFFECTIVE binding), so adding a registry command is all it takes to
make it show up; a command with no effective binding is omitted rather than listed chord-less.
ShortcutsPanel.test.tsx is the watchdog and reds if a command fails to surface. The panel it
replaced 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.
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 with reasoning. A comment that restates the code is noise; one that says "do not simplify this back, here is what broke" is the point.
A generated sh client reads its node token through the one resolver. Every POSIX-sh client we
emit (the managed hook script, nodeterm.sh, context.sh) presents this node's per-node identity by
calling nt_read_node_token from core/agents/node-token-sh.ts — never by re-typing
head -n 1 "$NODETERM_NODE_TOKEN_DIR/$NODETERM_NODE_ID". That copy was issue #384: a session is
pinned for life to the endpoint FILE path it got at tmux creation, so a client that trusts only what
that file advertises presents nothing forever when the file is old or unreadable — and because the
hook script alone could heal itself, the same node proved itself through one client and was refused
through another for the life of the session.
Local generated sh clients recover shared-Codex identity before their env gate. A Codex tool
shell is forked by the account-scoped app-server, so it has CODEX_THREAD_ID but not the pane's
NODETERM_*. Managed hooks, local nodeterm.sh, and local context.sh must prepend
codexThreadIdentityResolverSh(codexThreadIdentityRoot()) before checking NODETERM_NODE_ID or
NODETERM_CANVAS_CONTROL. Keep the SSH shim constants machine-neutral: baking the desktop/server
record path into a remote host is both wrong and a local-layout leak. A guard test enforces that
(remote-shim-neutrality.guard.test.ts), because the leak is silent — the remote shim keeps
working, and nothing goes red.
A Codex hook is identified by its payload, not its env. Hooks the shared app-server runs are
the daemon's children: they carry the daemon's env (often a stale pane's NODETERM_NODE_ID) and no
CODEX_THREAD_ID. The codex hook script reads the payload's leading session_id before the prelude
and lets that thread's record outrank an inherited id; only a pane marked NODETERM_CODEX_PLAIN=1
(the launcher's in-process exits) keeps its own. Do not move the codex payload read back below the
prelude (codex-shared-daemon-hook.test.ts runs the real script against the real hook server).
That prelude may not decide anything a pane already decided. It exports the agent id and the
canvas-control grant the ownership RECORD carries, never constants. They used to be hardcoded
(codex, granted) and both are buildPtyEnv's answers: a custom agent inheriting the codex harness
is custom:<uuid>, and the grant comes from canControlCanvas. If you add a field the prelude
exports, put it inside the record's HMAC and have the desktop re-derive anything that grants a
capability — never accept the client's word for that. Withhold rather than assume: a tool shell
missing a verb its pane has is a bug report, a tool shell holding one its pane was denied is a
security question.
A shell that forwards data into these records cannot be type-checked into correctness. A
handler that destructures the request without the new field, and a call that omits an optional
trailing argument, are both well-typed — so the feature ships inert with a green suite. Pin the
wiring at source level (codex-identity-record-wiring.test.ts, hook-verified-parity.test.ts).
A stream error is not a throw you can catch. When a write to process.stdout/stderr fails —
EPIPE down a closed pipe, EIO after macOS revokes a closed terminal's tty — node reports it by
emitting 'error' on the stream a tick later, and the default for an unhandled 'error' event is
to kill the process. The stack it carries was captured at the write, so the crash reads as if it
happened synchronously at your console.log, and wrapping that call in try/catch changes nothing
(measured on node 22). If you write to a stream that can go away, attach an 'error' listener and
latch the writer off — installLogSink (src/core/log-sink.ts) is the worked example. Issue #382.
A dead or hung process is logged, never acted on. child-process-gone, window
unresponsive/responsive and external WebGL context losses each write one tagged line to the
debug log ring (main/process-health-log.ts, [webgl] in terminal/webgl-budget.ts) and nothing
else. Chromium respawns its own GPU process; a reload or relaunch on top of that turns a GPU reset
into a lost session. If you add a loss path, report it through handle.contextLost(kind) so the
external counts stay apart from our own loseWebglContexts releases.
A retry budget must measure the thing it is waiting for, and running out must be VISIBLE. The
armed-launch loop (canvas-control --after, and the cold open a --project node gets) delivered its
held command on a flat 5 × 400 ms budget started when the canvas held the node — so on a cold
project switch it was spent loading the canvas, mounting the node and spawning tmux, and the launch
was abandoned before the session it was for existed. Two rules came out of issue #569: wait on a
real signal (isSessionReady, published by the node when its shell settles) rather than on a
stopwatch aimed at the wrong start, and never let "we gave up" live only in a console.warn — the
node shows it (state/launchDelivery.ts → the QUEUED badge's ⚠ + tooltip) and the canvas-control
reply carries it (queued / queuedIds), because a user who cannot see the failure and an
orchestrator that is told "opened" both act on a session that is not there. If you add a bounded
retry anywhere, ask what the clock actually starts on and where its exhaustion becomes visible.
A held launch is an exec field, and a gate nobody can read stays CLOSED. pendingLaunch is a
command typed into a shell when its wait ends, so it is MACHINE-LOCAL like shell
(src/shared/node-exec.ts): it rides workspace.json's localExec, never the git-shared
.nodeterm/project.json, and a peer's or relay guest's value is dropped on canvas:mut. A write
your renderer authors into a background project goes through applyOwnNodeMutation, never the
peer path applyNodeMutation (which strips the launch and cannot clear one). Where a value is read
(workspace.json is still hand-editable), normalizePendingLaunch
(src/shared/pending-launch-shape.ts) runs at both serializer seams: an after that is not a list
used to throw inside the canvas's dependency-signature selector. Its rule, and the rule for any new
gate you add (the --after-success wait is the latest): a value it cannot read turns the
hold manualOnly or never-satisfied, never "no gate" — dropping it would start the node early, and
a dependent that has launched cannot un-launch. A new gate field also goes in that module's KNOWN
set, and launchesToFire must treat a missing context for it as closed. If both shells evaluate the
gate (the Server Edition's headless factory releases its own held launches), put the evaluation in
src/shared beside the shape, as @shared/station-outcome does, so the desktop and the server
cannot disagree about when a dependent starts. And never let a gate read its "satisfied" from a
file: a success a git commit can claim releases every dependent waiting on it — the station's
report lives in a transient core store, and its board-log line is display only.
Never move the user's view on a background agent's say-so. Canvas-control requests route by
SOURCE, and React Flow holds only the ACTIVE project's nodes — so the dispatch used to travel to the
caller's project before answering. For an OPEN that was a screen hijack: the user is looking at
project B, an agent in project A runs open-claude, the tab switches and A's saved viewport is
applied, so the camera appears to jump and zoom. The rule now has three tiers, all membership lists
in renderer/lib/controlRouting.ts: STORE_ANSWERED_VERBS ("no canvas is needed at either end" —
list, send, reply, sticky, open-project, settings), canColdOpen ("a canvas IS needed, but the
serialized one will do" — open-terminal, open-claude, open-agent, which write into the owning
project's stored nodes with their launch armed and report queued: true) and answersOffCanvas
("…and there is nothing to defer" — show-image, show-video, show-web, open-browser, whose
node has no session behind it and is finished the moment it is written, so it reports offCanvas: true and never queued). Everything that acts on nodes which already exist still travels, because
it reads live state the serialized copy does not carry — browser included, which navigates a
mounted <webview> guest, unlike open-browser, which only places the node.
Three things to carry over when you put a verb in one of the two off-screen tiers. The acting
project is the SOURCE's: ctlProject decides the ssh flag, the browser session key and the media
allowlist route, and reading activeProjectId there answers a background agent with whatever the
human is looking at. Nothing may reach the live canvas: setNodes / setControlEdges /
markDirty address the ACTIVE project, so the write goes through applyNodeMutation +
appendCanvasLinks + writeDisk. And tell the human — the reply goes to the agent, so without
a strip nothing anywhere reports that a node landed in another project; it is sticky, because it
describes work the user was not watching. When you add a verb, decide which tier it is in — and if
you change what a verb DOES, update buildCanvasSkillBody / buildCanvasControlInstructions in the
same PR, with a test that goes red on the stale claim (src/main/canvas-control-core.test.ts).
Pointing a project at a folder is a WRITE — probe before you bind. A project's canvas is
written to <cwd>/.nodeterm/project.json, so the moment a project gains a cwd the next autosave
owns that file. "Open folder…" always probed and adopted; "Set folder…" (tab ⌄) used to bind
unconditionally, which overwrote a canvas a teammate had committed to that repo — their nodes gone,
no backup, nothing on screen. Both entrances now share the rule (renderer/lib/setProjectFolder.ts):
an occupied or unreadable project file refuses the bind and says why. The store's "never
blind-write" guard will not save you — it only refuses an EMPTY canvas over a populated file.
Every workspace entry is a REF — content in a file, machine-local state on the entry. There are
three kinds and they now share one shape: a folder ref (<cwd>/.nodeterm/project.json, git-shared),
an SSH ref (the same file on the host, with an offline cache), and a cwd-less canvas
(userData/inline-projects/<id>.json, with the entry's project field kept as a cache for one
release so an older build still reads it). Two habits follow. Content goes in the file; anything
this machine would legitimately disagree with another machine about — project id, viewport, default
account, breadcrumbs, closed-session history, per-node shell and held pendingLaunch — goes on the index entry
(IndexEntryV3), or a git worktree add / a second instance hands one machine's state to another.
And workspace.json is one file with last-writer-wins semantics, so it may not be the only home
of any content: that is precisely what let a second app instance erase a cwd-less canvas. Between
two instances the arbiter is the file's rev — a lower rev never overwrites a higher one — and
there is no merge; if you add a fourth kind, give it a file and say which rev wins. The fourth is the
folder-data-ref (issue #1145: a folder project whose canvas lives in app data): its file is the
inline one, writeDataFile's rule decides between instances, and the rev continues across a move
between the folder and app data. Anything that reads or writes <cwd>/.nodeterm/ must ask
folderFileCwd(e) (or the side-file accessors), never e.cwd alone — a project can have a cwd and
nothing in its folder. Such a project's side files keyed by node id (whiteboards) go under its own
app-data root, never into a folder every project shares: two folders holding one committed canvas
share node ids. And lastWritten is a record, not evidence that a file is on disk: a file
can leave a folder behind the store's back (git rm, a checkout), so nothing may be deleted
because the store remembers writing its replacement. The data-file sweep asks what THIS save wrote.
A project with no folder is a real project — degrade explicitly, never silently. "New project"
creates a cwd-less canvas, so every folder-shaped feature meets one. Keep the affordance and
disable it with its reason (NEW_FILE_NO_CWD_HINT,
WORKTREE_NO_CWD_HINT, the Explorer/Source Control notes); a row that simply vanishes teaches
nothing, and a message that names the wrong cause ("not a git repository" for a project that has no
folder to be one) sends the user hunting a problem that does not exist.
Opening a project goes through gateProjectOpen (src/renderer/lib/projectLimitGate.ts); a new way to open one must call it — see docs/project-limit.md.
Agent features attach to base harness capabilities, not frontend allowlists. A custom agent can
inherit a builtin harness, so add the capability and its one shared leaf (src/shared/agents) and
let every UI ask the helper. Repeating Claude/Codex/etc. cases in menus breaks that inheritance and
eventually drifts.
Never put a raw NUL byte in a source file — write \x00. Git classifies a file containing one
as binary, so it renders as "Binary files differ" in every diff surface (the PR page, git diff,
git log -p) and git grep skips it. It still compiles and its tests still pass, so nothing fails
— the file just becomes invisible to review, which is the worst way for this to go wrong. A
separator or sentinel is a fine reason to want the byte; the escape is the same byte and keeps the
file text. src/shared/source-hygiene.test.ts enforces this across every tracked .ts/.tsx.
**Paths cross machines, so treat \ as a separator wherever you split one.** A value persisted in
.nodeterm/project.json is written by one machine and validated on another, so a guard that reads
\ as an ordinary filename character is simply wrong about the machine that will resolve it. This
has already produced a real hole: a traversal check that split on / alone saw ./a\..\..\x.png
as a single harmless segment on every platform. Split on [\\/], and prefer accepting both
dialects while storing only one (see Node icons in CLAUDE.md for the worked example).
Canvas edges are all type: 'floating', and one relation gets one edge. Never set
sourceHandle/targetHandle on an edge object — the rendered path is computed from the two nodes'
rectangles (renderer/lib/floatingEdge.ts), and a fixed side is what sent an edge to a node placed
left of its source looping across the whole canvas. And do not add a second edge family for a
relation a rope already carries: --after is a rope whose dashed "⏳ waits for" look is DERIVED
from the target's pendingLaunch (renderer/lib/edgeModel.ts), and the context bridge it also
writes stays hidden underneath it. One open-claude --after used to land three edges on one node.
src/renderer/canvas/edge-model.source.test.ts pins both halves.
A canvas layout is GEOMETRY, and its two halves live in different files. A saved layout moves
nodes and nothing else: it never creates, deletes, renames, reparents or respawns one, and never
touches a tmux session. The snapshot itself (Project.layouts) is CONTENT and rides the git-shared
.nodeterm/project.json, while this machine's camera per layout (Project.layoutViewports) is
machine-local and rides workspace.json beside viewport and breadcrumbs. Restoring applies its
camera with setViewport, per the fitView rule below. Deleting a layout and updating one to the
arrangement on screen both confirm first, because layout edits are not in the undo stack; restoring
does not, because it is. Whether a dialog claims the edit reaches other people comes from
layoutIsShared, which is true for an SSH project as well as a folder one.
Keep-alive webview ghosts must stay mounted, but must not enter minimap geometry.
They use display:none, not React Flow's hidden (which unmounts the guest). Render canvas maps
through VisibleMiniMap: it filters both drawing and bounds in a minimap-only store while sharing
the live camera. A transparent rectangle alone still distorts the map's scale.
React Flow's fitView is queued, not immediate — never use it to frame something automatically.
Calling it sets fitViewQueued and the fit runs from a later setNodes (only once every node is
measured) or the next updateNodeInternals, against whatever the node lookup holds by then; a fit
set that comes out empty parks the canvas origin in the middle of the screen. Compute the viewport
yourself and apply it with setViewport (renderer/lib/nodeFocus.ts, canvas/fit-view.ts), which
lands now and against the canvas you meant. fitAll is the one deliberate exception: an explicit
user gesture on a settled canvas.
A context menu is two levels deep, and the third level is discarded in silence.
ContextMenu renders a submenu's children with
if (child.type === 'colors' || child.type === 'submenu') return null — no error, no warning,
nothing on screen. That matters most where you cannot see it: Claude's and Codex's account
pickers are themselves submenus, so moving one of those rows into another submenu deletes the
account picker for exactly the users who have managed accounts, and looks perfect to everyone
else. If you group rows in an add menu, get the decision from isPinnedAgentEntry
(renderer/lib/addMenuSpec) rather than judging by eye — and never spell an agent id there: which
rows stay at the top is derived from the row's own shape plus ACCOUNT_CAPABLE_AGENT_IDS, so a new
agent is handled the day it is added. The cap is measured in
components/ContextMenu.submenu-depth.test.tsx; if you teach the component a third level, that
test tells you which pin to revisit.
Adding a node kind means touching the add menus once, not four times.
renderer/lib/addMenuSpec owns which kinds are addable and how they are grouped, for the canvas
pane right-click, the sessions-sidebar "+" and the Dock. ADD_ITEM_GROUP is a total Record over
the kind union, so a new kind is a compile error until you route it. The kanban column's
"+ New session" is deliberately not a consumer — it can only offer kinds that become a card — and
addMenuSpec.surfaces.test.ts pins that split so "make them all consistent" stays a decision
rather than a reflex.
A surface that takes the whole keyboard marks itself data-nt-keyboard-owner. The canvas
decides "is the user typing" from the focused element (isTypingTarget and friends), and a canvas-
or div-based editor — the whiteboard's Excalidraw — is not a text field to that check, so Space,
Delete and ⌘Z reached canvas commands over it. The attribute is honoured by every typing-aware key
site through isKeyboardOwnerTarget (lib/keyContext.ts); add new sites to it, not a class list.
Files a node owns are addressed by id, never by a path from node data. project.json is
git-shared and hand-editable, so a path in it is attacker-controlled: a whiteboard's side file is
derived by the core from (project, node id) (core/whiteboards.ts), and the id must be a string
passing isSafeNodeId. A copy refers to its original by id (whiteboardSource), not by path.
A new node kind also gets a default size the user can change. Add it to SizableNodeKind /
SIZABLE_NODE_KINDS (shared/default-node-size.ts) and BUILTIN_NODE_SIZES, and place it with
placeSized(kind, …) in its factory. A literal *_SIZE passed to placeNode compiles fine and
quietly ignores Settings → Behavior → Default node size for that kind.
A setting read at mount reads the DEFAULT, not the user's. useSettings starts on
DEFAULT_SETTINGS and hydrates from disk asynchronously, while <Canvas /> is mounted before that
lands. A useState(() => settings.foo ? ...) initializer therefore reads the shipped default and
never looks again, so an opt-in feature ships inert with a green suite and no error anywhere. Gate
on hydrated (the first-launch consent dialog and settings.rememberCanvasLock are the worked
examples). If the same effect also WRITES, latch its first run: otherwise switching the setting on
mid-session applies stored state to whatever the user is doing right then, which is a different
feature from the one they asked for.
Canvas's nodesRef / nodesProjectIdRef are the LATEST pair, not the rendered one. During a
project switch a zustand write re-renders Canvas at SyncLane before the load's DefaultLane
setNodes lands, so for a moment the ref names the incoming project while the render's nodes
are still the outgoing one's (canvas/nodesEpoch.ts). Event-time code (commits, the canvas:mut
receive path, creates) reads the refs; code that pairs the tag with the RENDERED nodes (a
render-time publish, an effect keyed on nodes) reads renderedProjectId. A peer op goes live
only when liveCanvasHolds says React Flow has that project, and its setNodes is functional
(rebaseOnLatest). nodesEpoch.test.tsx reproduces the window with real React; never wrap it in
act, which flushes both lanes together and hides it.
Maximize placement and refocusing must use the same measured usable rectangle
(measureMaximizeInsets): pinned side panels plus persistent top controls and bottom dock.
Do not hardcode chrome heights or add the outer margin twice; transient menus must not resize
terminals. Ordinary focus and zone snap keep their own policies. Test the maximized-only
focus decision through viewportForNodeFocus, the same helper Canvas calls, rather than
passing preselected insets straight to the geometry function.
Usage readouts distinguish failed reads from empty data. For Claude, show the failure when
status is error and limits are empty, including beside other providers; preserve last-known
bars when limits remain. Keep both single-account and multi-account views covered.
A context capacity needs session provenance. Claude's effective CLAUDE_CODE_MAX_CONTEXT_TOKENS
is reported by its managed hook, accepted only with verified node identity, and validated as a
positive decimal safe integer. Never read the app's global env for another session or let a
model-family guess enlarge an observed limit. Unobserved Claude windows are labelled estimates.
The renderer rehydrates through context.ensure; it does not restore Claude denominators from
storage. Other agents retain transcript-window persistence.
Only an explicit ensure replays an unchanged live snapshot; repeated hook observations must not
broadcast it again. Remote path, ControlMaster or connection changes replace the tracked generation.
Command-bearing terminal opens (issue #653): the shared hook-server route requires verified
node identity whenever open-terminal carries cmd, including an empty value or a dry run.
The strict-policy override and foreign-instance fallback cannot release this gate. Desktop plain
terminal opens keep their existing identity policy; Server Edition still requires verification
for every control verb. Legacy mobile/SSH callers must present this instance’s node token for
command-bearing opens; this does not add a human-confirm dialog or change mobile transport APIs.
Grok billing diagnostics must keep HTTP codes and safe failure categories per billing view. Never send raw error messages, URLs or response bodies to the UI; credentials remain read-only. A failed view is not proof that there is no quota, even when the other view responds.
Phone chat verbs (chat.page / chat.status / chat.send / agent.answer). Full contract in
docs/mobile-chat-view.md §3. Three rules get a PR sent back:
- The phone sends only a
nodeId. Cwd, account, agent, session id and remote routing come from this machine's records. Never add a param that lets the phone name a path, a session or a host. - The
chatdependency is optional at every hop (host-service handler,HostSessionOptions,HostBridgeDeps), so dropping it anywhere still compiles and ships the verbs as "not served".host-chat-wiring.test.tspins the chain; extend it when you add a hop. 'unconfirmed'is never a refusal. It means the desktop could not confirm whether the text was typed. Nothing may treat it as "safe to resend": the phone keeps the draft, re-reads, and lets the user decide. Only'refused'means nothing was typed.
nodeterm:// links. A link proves nothing about who sent it (any web page can build one), so
the confirm sheet is its whole authority. It is off unless the user turns on
settings.allowOpenLinks, and main checks that flag itself. Four rules get a PR sent back:
- No power flags. A link opens one node in the project's default permission mode. Never add a
param for a permission mode,
--after, a model, a count or "open without asking" (the signed-link design indocs/superpowers/specs/2026-10-13-open-link-design.mdis the only planned way to skip the sheet). - The renderer only chooses. Its answer is a candidate id main offered, "new project", and a
title. The cwd and prompt in the final open come from main (
src/main/open-link.ts), never the reply. - Enter never opens it. Only a pointer click on Open, after the 1 s arm.
- What the human sees is what runs. No hidden Unicode in a prompt or path (
hasHiddenText), no path that can reach another machine, and the permission mode shown is re-checked at landing.
User-owned agent settings
Nothing writes into an agent's global config except src/core/agent-integrations.ts (issue
#744). Hooks, skills and anything else under ~/.claude, ~/.codex, ~/.gemini, ~/.grok,
~/.copilot, opencode's config dir, ~/.agents — locally or on an SSH host — are installed only
for an agent the user ENABLED in settings.agentIntegrations, removed when they decline, and left
alone while they have not answered. Do not add a direct call to an installer; add the artifact to
the lifecycle (local) or to the RemoteHooks artifact plan (SSH), and give it a removal that
deletes only what nodeterm wrote. src/core/agent-integrations-wiring.test.ts fails on a new call
site. A file nodeterm writes at every boot is never evidence of a pre-consent install — the
grandfathering check (detectExistingIntegrations) counted the always-written userData shims and
silently enabled every agent on a fresh install's second boot (#1149). Only a non-empty
~/.nodeterm/agent-hooks/ counts, and only on an install's first boot (the fresh-install marker). Do not merge text into AGENTS.md / GEMINI.md — agents get skills (progressive disclosure)
instead; the old blocks crowded codex's 32 KiB instruction budget.
opencode has two managed plugins and they must stay two (issue #1136): the 1.x file
plugins/nodeterm-status.js exports ONLY the named function — opencode <= 1.2.10 calls every export
as a function and dies on a default object, for every command on the machine — and 2.x gets the
directory plugins/nodeterm-status-v2/, which no 1.x loads. The 2.x plugin stays silent inside the
shared serve --service server (its env belongs to another pane); see CLAUDE.md for the
measurements.
Claude/Gemini settings must go through the guarded transactions in
src/core/agents/hooks/{settings-file,remote-settings-file}.ts. Confirmed absence or a successfully read empty/whitespace file may start from {};
malformed, non-object and unreadable files must survive unchanged.
Keep unrelated settings and foreign hook handlers. Stage writes, serialize nodeterm writers,
and compare the original bytes again before publishing; never use cat … || echo '{}' or a
catch-all read fallback. Local and SSH symlinked profiles update and lock the resolved target without replacing
the link; recheck resolution before publishing. SSH uses plain readlink and cd -P (no GNU -f),
and refuses dangling/cyclic links and newline paths. A conflicting/stale lock skips installation
with a diagnostic naming the lock and safe manual recovery; do not steal it from another process. These locks
coordinate nodeterm, not external editors, so do not claim a filesystem-wide compare-and-swap.
Creating an agent node is not proof it started. Control opens retain their launch command
until delivery is acknowledged, and report queued while it is held. A successful terminal send
proves delivery only; never describe it as a healthy/running agent without agent evidence.
Every launch uses the echo-verified command writer (@shared/command-delivery), not sendText:
desktop automatic and Run now, the desktop's headless start, and the Server Edition's immediate
open and run (the last three through core/headless-launch.ts). The Server Edition's deferred
--after release (refreshArmed) is the one remaining sendText launch, pending a move that must
never create a session.
Keep unsubmitted UI intent durable through shell settle/unmount. New intent carries attempted:false;
Desktop and Server save attempted:true before input. Never-attempted warm --after launches may
proceed after shell verification; attempted/legacy-unknown intent requires Run now. Only confirmed
submission clears intent. Desktop open replies use createControlOpenBatch for queued accounting;
protect that contract and concurrent submission with behavior tests, never source-text pins.
Relay queued/restored launches and Run now are refused until a scoped durable claim API exists.
A new relay UI initialCommand may run once on a fresh PTY through the verified writer, without
workspace writes or pendingLaunch creation. Consume its transient attempt before shell settle;
never retry it on remount or serialize it as durable intent.
Never round-trip a relay workspace load into save: the load can contain only one shared project,
while save replaces the entire host index. A pre-input parked-project deferral keeps intent
never-attempted; it must not poison the writer or trigger a retry timer.
Held Desktop launches retain their attached transport even offscreen with tmux (large fan-outs cost
memory). Server deferred delivery is one-shot: a failed probe/send needs explicit recovery.
A headless start (--run-now / run, #925) follows the same contract: the claim is saved before
any spawn, and "started" means the echo-verified writer submitted the line (never that the agent is
healthy). The desktop releases its headless client, so there a start without a persistent terminal
backend fails not-persistent and hands the node back unchanged (a cold open stays an ordinary
queued node) rather than leaving a shell that the next mount would orphan. Normally that refusal
comes before any spawn; if the backend vanishes between the probe and the spawn, the plain shell it
got is refused before anything is typed, and releasing it kills it. A remote (SSH) node, and any
node of an SSH project, is refused in the renderer before the claim (remote-unsupported), which is
the primary fence. As a belt
behind it, an SSH-project node's request carries requireRemote, which desktopHeadlessRequest
keeps, so core's spawnNew refuses rather than spawning it locally. Keep both fences.
Performance
Measure before you optimize, and put the before/after in the commit. The CLAUDE.md section
Performance: measure it, then fix what the measurement names has the method (CDP against
npx electron-vite dev --remoteDebuggingPort 9333) and the rules it produced. The ones that
bite most often:
- An infinite CSS animation keeps the whole window repainting at display rate. Bound it.
- Never put
will-changeon the React Flow viewport. handleNodesChangemust not callonNodesChangewith an empty batch (it re-renders the canvas every frame through React Flow's ResizeObserver).- Work done per terminal on a project switch must be coalesced and on-screen-first.
- Don't put a
backdrop-filteron a surface whose content changes often. Chromium re-runs it every time the surface is drawn, and the damage spreads to the glass next to it. Liquid Glass terminals frost a static wallpaper copy instead (.term-node__frost,lib/glassFrost.ts): six streaming terminals went from 92% to 42% GPU. The SVG refraction filter (url(#nt-refract)) runs only left of the Readable tick, for the same reason. - macOS memory pressure comes from the kernel's level (
onKernelPressureincore/memory-pressure.ts), fired on escalations only, and at the same severity at most once perKERNEL_LEVER_GAP_MS(a level flapping normal/warn re-arms it every fall). Never re-fire it on a held level, and never route it throughhostMemReader/MemInfo: the session reaper shares that reader. - A terminal under the kanban board must not draw. CSS can't stop xterm; its render pause is
terminal/board-render-pause.ts. Every "is the board up" check includes the Omni board (isGlobalKanbanOpen()), and the board never feeds the visibility verdict that drives hibernation and the WebGL budget. - Search big in-memory text with one escaped
RegExp(q, 'iu')per query, nevertoLowerCase()per entry (transcript index: 20-52 ms + 7-15 MB garbage → 2-13 ms + 0 MB per search). - Dispose every Monaco model your node creates when it unmounts. The TS/JS worker (a whole
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). Use import type 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() is
not reached by vi.mock, so a test injects its double (see the updater tests).
SSH projects on Windows run over an in-process transport (src/core/remote-ssh/native/),
not the ssh binary. If you add an ssh call site, route it through useNativeSsh() like the
others, and if you add an ssh option to control-master.ts, teach ssh-argv.ts about it (the
parser refuses unknown options on purpose). Test from macOS/Linux with NODETERM_NATIVE_SSH=1. Resolve the ssh
program with resolveSshProgram() (never a private findExecutableSync('ssh', …)): on Windows it
may be the bare ssh sentinel, which only the native runners can serve.
A dependency with a native addon that the Server Edition reaches is --external: in
server:build. Hosts build the bundle after npm ci --ignore-scripts, so no addon is compiled
there, and esbuild fails on a .node require it cannot resolve (or, where the addon IS compiled,
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.
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.
Testing
Run the suite with a scratch HOME, and know what else points at your real config. The worker
setup (test/setup/agent-env.ts) strips CLAUDE_CONFIG_DIR, CODEX_HOME, GROK_HOME,
COPILOT_HOME, GEMINI_CLI_HOME, XDG_CONFIG_HOME and the NODETERM_* session variables, because
a suite run from inside a nodeterm agent session inherits them and code under test resolves the
LIVE agent config dir from them — a scratch HOME alone did not stop a test from rewriting the
running session's own skills and hooks (#744). A test that needs one sets it itself.
Screenshot paste has one route per gesture. On macOS, Cmd+V saves/uploads a file and pastes its path; Ctrl+V belongs to the foreground program. A node's configured agent is not proof of foreground clipboard-image support. Keep shell/SSH/Server file routing and capture suppression of accompanying text; do not synthesize Ctrl+V or try both routes without a capability and receipt protocol. The shortcuts panel documents this distinction (#712).
The titlebar's scroll viewport owns its no-drag region. Do not add app-region: no-drag
to tabs or their descendants: Electron can subtract their off-screen rectangles from the
wordmark's drag area. scripts/tabbar-drag.test.ts checks native hit testing with isolated
Electron/Xvfb on Linux; macOS traffic lights and actual window movement still need device checks.
npm test must pass, and npm run typecheck is the fastest gate.
The typecheck does not catch a closure reading a later const. If a helper defined in a
component body reads a const declared further down and the helper is CALLED during render, it
throws a TDZ ReferenceError at runtime while tsc stays green (#1090 blanked all of Settings
this way). Declare what a render-time helper closes over above the helper, and give a new
Settings section a render test with its real-world state populated — every section renders on
each Settings open, visible or not, and each is wrapped in SettingsSectionBoundary.
Beyond that, one habit is worth more than any other here:
Mutation-test your guards. Delete or invert the check you just added and confirm a test fails. A green suite is not evidence on its own — during one recent feature this caught nine tests that passed with the code they were meant to pin removed, including one mutation that survived the entire 4,500-test suite because the class it touched had no test file at all.
Watch for fixtures that cannot discriminate: if every row in your fixture happens to make the mutant's output identical to the real one, the test proves nothing while looking thorough.
Never pin behaviour by reading source text. expect(SRC).toContain('...') is the fixture that
can never discriminate: it is satisfied by code that is present and wrong. We shipped one —
src/main/menu-accelerator-intercepts.test.ts matched three strings inside the before-input-event
handler, and stayed green on a tree where a shared guard had moved out from under them and the bare
0 key was swallowed app-wide. It was, precisely, red on the fix and green on the break. If a
module is untestable because it imports electron at the top, that is the thing to fix: lift the
decision into a pure function next to it (keydown-intercept.ts, main-window.ts,
zoomShortcut.ts) and press the keys.
Where a behaviour can only be verified on hardware we do not have in CI (a Mac, a real SSH host, a GPU), say so explicitly rather than implying coverage. Several docs carry numbered device checklists for exactly this.
A test that reads a checked-in file must not care how git checked it out. .gitattributes
declares * text=auto eol=lf, so every working tree is LF — but attributes only take effect on a
re-checkout, so if you cloned before it landed, run git add --renormalize . (or re-clone) and your
tree catches up. Windows is where this bites: Git for Windows defaults to core.autocrlf=true, so
without the attributes file a fresh clone had CRLF working files and CSS.indexOf('}\n}') matched
nothing — two suites failed on a checkout with zero local changes, and one of them reported 25 theme
tokens missing that were all present. Normalize at the read
(readFileSync(f, 'utf8').replace(/\r\n/g, '\n')); src/shared/line-endings.guard.test.ts fails on
a read that slices a \n-bearing literal without it.
An SSH project spawns on the host's node-terminal socket — the same one a nodeterm running on
that host uses. That is what lets the same folder, opened locally on the server and over SSH from a
laptop, attach the same nt-<id> sessions. nodeterm-rmt is the legacy socket: never spawn on it,
but a session an older build left there is adopted in place — so a remote tmux command about ONE
session must go through sessionTmuxCmd and name the socket as SESSION_SOCKET_REF
(control-master.ts), not RMT_TMUX_SOCKET; a bare constant silently misses every adopted session
and the node respawns beside its own live agent. Never give the SSH path a socket of its own again
(src/core/remote-ssh/unified-socket.test.ts pins the equality; CLAUDE.md "One tmux socket per host").
A test never touches a live tmux server. You will most likely run npm test from inside a
nodeterm terminal, where -L node-terminal (and a legacy -L nodeterm-rmt) are the servers holding every
node you have open — one stray kill-server there ends your whole canvas, not your test. Every run
therefore gets a private TMUX_TMPDIR (test/setup/tmux-sandbox.ts), which re-points every socket
name at once. Write real-tmux suites the normal way — pick your own socket name, and use
makeTmuxTmpdir if you also want your own directory — and do not build an env object for a real
tmux without carrying TMUX_TMPDIR into it, which is the one way left to escape the sandbox.
src/core/tmux-socket-isolation.guard.test.ts holds the short allowlist of suites that name a
production socket on purpose; adding a third is a review conversation, not a checkbox.
A test never touches the real home. The hook installers write ~/.codex/config.toml (Codex's
trust in nodeterm's hooks), ~/.claude/settings.json and friends, and they use
import { homedir } from 'os', which vi.spyOn(os, 'homedir') does not reach — one test doing that
rewrote a developer's real Codex config and Codex stopped running nodeterm's hooks. Every run points
HOME/USERPROFILE at a private sandbox (test/setup/home-sandbox.ts) and clears CODEX_HOME,
CLAUDE_CONFIG_DIR and the other relocation variables (one list, HOME_OVERRIDE_ENV in
src/core/test-home.ts, which test/setup/agent-env.ts reuses). If a test needs its own home, mock the
module (vi.mock('os', …), see install-helper.fs.test.ts), never spy on it.
Session code has two local backends on POSIX: tmux and Zellij. settings.sessionBackend picks
where a NEW local terminal's session is created (default tmux); an existing session is always
reattached in the backend that holds it. If you add a PtyManager method that talks to tmux about a
node, ask isZellij(persistKey, live) first and either implement the Zellij leg in
src/core/zellij-backend.ts or answer the explicit "unknown/refused" value and add the gap to
ZELLIJ_BACKEND_GAPS (the Settings row prints that list; docs/session-backends.md must state it).
Asking the tmux socket about a Zellij node is a guess, and has-session exit 1 there reads as
"cold". The *.realzellij.test.ts suites need a binary: set NODETERM_TEST_ZELLIJ=/abs/path/zellij
or put zellij on PATH; they sandbox HOME, XDG and ZELLIJ_SOCKET_DIR, and skip otherwise.
A test's temp directory must go away when the run does. fakePlatform()'s userDataDir is made
on first read under one per-run root (test/setup/fake-platform-root.ts), and that root is removed
after the last test file finishes. It used to be one mkdtemp in the system temp dir per call, never
removed, and a development server collected ~395,000 of them until /tmp ran out of inodes and whole
runs failed with ENOSPC. If you mkdtemp in a test yourself, remove it in afterEach/afterAll
— or, for the userDataDir of a CorePlatform you build by hand, call makeFakeUserDataDir(),
which lands under the same root.
Beyond fakePlatform(), a test cleans up every temp directory it creates. The suite once left ~1,500 directories in
/tmp per full run, and on a shared box that exhausted the filesystem's inodes and broke every
other session's builds. Use testTmpDir(prefix) from src/core/test-tmp.ts (removed when the file
ends, even when a test failed), or rmSync(dir, { recursive: true, force: true }) in
afterEach/afterAll/finally; stop servers and children writing there first. Every run points
os.tmpdir() at a private sandbox (test/setup/tmp-sandbox.ts), and the run exits non-zero naming
each prefix still in it — NODETERM_TEST_KEEP_TMP=1 keeps the sandbox so you can see what wrote
there. A module-level cache of platform().userDataDir is the other way a dir comes back: a suite
that boots two cores keeps writing into the first one's removed directory.
An infinite CSS animation is a frame loop, and it runs whether or not anyone is looking. A
running animation makes the compositor produce a frame every vsync — 120/s on a ProMotion display —
and re-raster the window each time; measured on a 40-terminal canvas, ONE visible pulsing node took
idle CPU from 1.5 % to 33 %, and twenty took it to 101 %. The cost is paid once for the window, so
the step is at the FIRST animation, not the twentieth. Two consequences when you add one: give it
animation-play-state: var(--nt-anim-state); right after the shorthand so it joins the idle-window
gate (src/renderer/styles.animation-gate.test.ts fails if you forget, because one ungated
animation takes the whole win back), and prefer a static state to a pulse wherever the pulse is not
carrying information the user needs at a glance. A dependency's stylesheet counts too: React Flow's
dashdraw on animated edges is gated by a rule in styles.css that repeats xyflow's selectors, and
the same test scans @xyflow/react/dist/style.css so an upgrade that adds an infinite animation
fails there. The full measurement table and the reasoning are in CLAUDE.md § Idle energy.
The gate only helps a window nobody is looking at; a FOCUSED window pays for every loop the whole
time it runs (issue #1454: four working-subagent edges and a few dots held one at 120 frames/s). So a
status indicator pulses a few times and settles (ease-in-out 4), and keeps looping only if it must
keep pulling the eye (needs-you). And every repeating animation must stop under
@media (prefers-reduced-motion: reduce): src/renderer/styles.reduced-motion.test.ts fails on
one that is neither stopped there nor listed in its EXEMPT map with a reason.
The kanban board hides things it does not unmount. The canvas and a pinned sessions sidebar
stay mounted under the opaque board, and so do their terminals. An animation on something under
the board needs the covered override (:root[data-nt-canvas='covered'] …, pinned in
src/renderer/lib/canvasCovered.test.ts), and a status animation ON a board card must be bounded
to a few cycles, because no gate pauses what is on screen while an agent works for an hour. A
terminal under the board keeps parsing; terminal/board-render-pause.ts stops it drawing and also
holds xterm's textarea, scroll-area and selection paths, which ignore the render pause. If you add
another per-output xterm call that touches the DOM, hold it there too.
Pull requests
- Branch from
main. CI runsquality,CodeQLandDependency review; all three are required. - Explain why, not just what. If a decision has a trade-off, name it and say what you rejected.
- If you measured something, put the numbers in — they save the next person the same afternoon.
- Say what you did not verify. That is more useful than a confident summary.
- Lead with what changed and why it matters. A reviewer who reads only your first two sentences should be able to decide whether to keep reading; implementation detail comes after.
- Match the length to the change. A one line fix gets a paragraph, a change that moves a boundary gets as much room as it needs, and neither is improved by headings it does not need.
Documentation
Two files, two audiences:
CONTRIBUTING.md(this file) — what another human needs before touching the code.CLAUDE.md— the deep invariants, per subsystem, with the reasoning and the measurements.
If you change or discover something other contributors must know, update this file too. An invariant that only lives in a commit message is one refactor away from being violated by someone who never saw it.
Windows text submission waits for the composer. Use core/settled-text.ts for native PTY and
session-host sendText: adjacent paste/Enter writes can be consumed in one read. The bounded
screen check may leave text unsubmitted; propagate pasted-not-submitted all the way to the
caller and tell the user to inspect the terminal. Never treat that truthy string as success or
automatically retry the paste. True means the requested writes completed, not that a turn began.
The versioned sendKeysV2 host request refuses old hosts without fallback or restart. Collapsed
or hidden pastes may need manual Enter; device testing remains necessary.
An unanswered Claude AskUserQuestion is correlated by session and tool-use ID in the core
mirror, independently of its short-lived display stash. Ordinary hooks, subagent activity and
unrelated transcript results must not clear attention or archive its inbox card. Both shells
use recordQuestionResult for transcript rescue (including Escape/decline), and broadcast the
mirror's effective event. Keep result IDs through local and SSH tails; a boolean “some tool
finished” is insufficient. Explicit new user turns, interrupts and session boundaries reset it.
Remote Codex account safety (#736): managed SSH Codex sessions and agent-less login terminals
require a known safe account id and a safe resolved remote home before spawning. The remote env
builder supplies their private CODEX_HOME; never fall back to the system login when that scope
is unavailable. System SSH Codex retains the host environment, including during early attach
before home discovery; never inject a guessed HOME or CODEX_HOME. Custom Codex harnesses use
the same guard. Desktop supports remote account lifecycle; the Server browser still explicitly
rejects managed Codex account management.
- Media URLs live for the app run. Remote cache pruning must keep files already handed to
players; the cache cap is soft until restart. Use the existing
videonode for audio too. - Subagent reload replay is display-only and current-host-only. Never replay status/permission events or treat a replayed card as verified process ownership; subscribe before taking its snapshot.
Phone consent belongs to the verified handshake, not the browse socket. A standing phone's
SAS request survives transport closure only until its 120-second deadline; approval requires the
issued id and displayed box key together. Keep request/reply outcomes distinct (stale request,
failed pin save, missing IPC response, saved-but-disconnected). All production pin/revoke writers
must use updateApprovedDevices for the whole read/modify/write, so concurrent updates cannot
lose approvals or resurrect revoked keys. Server Edition does not host this legacy relay path.
Managed Codex login terminals are agent-less: core identifies their provider from the saved
account list. Before opening one, await useSettings.getState().flush() after adding the account.
The normal 300 ms coalesced save is too late: an unknown id can launch against the system home.
Claude subagent cards come from Claude's native SubagentStart/SubagentStop whenever a session
sends them; the Agent/Task tool pairing stays as the fallback and the task-label source. Both
shells pass every normalized event, and the <task-notification> end, through the one
ClaudeSubagentLifecycle before any consumer, and start the native tail before the child-event
gate. A consumer that keys subagents by id must honour supersedes. A native stop is not always
the final end (a background child is resumed under the same id), so Eco safety rides the parent
Stop's background_tasks inventory, not the card alone. Measure a CLI change against real
payloads (__fixtures__/claude/subagent-hook-payloads.json) before changing any of this.
Claude child PreToolUse/PostToolUse/PostToolUseFailure hooks must not drive parent state.
Child PermissionRequest and attention Notification hooks still reach needs-you and phone
approvals, including the raw approval summary and deterministic reply ticket. Keep raw summary
recording before the child transcript-association guard in both shells.
A held parent question can overlap child permissions: retain its question card and waiting state while publishing each approval ticket separately. Approval replies resolve only their own ticket; the picker stays pending until its correlated answer or explicit reset. When the parent answers first, retain concurrent approval tickets and blocked attention until their own replies; ordinary tool activity cannot settle them. Explicit turn/session resets still cancel both kinds of pending attention.
Optional hook ownership failures must never stop Desktop window creation or Server boot. Use the shared nonfatal startup path and surface its actionable diagnostic. A responding HTTP port is not nodeterm identity: verify bearer acceptance and rejection. Legacy SSH endpoint migration requires ownership proof, an unchanged-file check, and stdin-only credential transfer; a project name alone is not permission to replace another installation's advertisement.
Held approval attention must not replace subagent, recurring or background-task events, or refresh state evidence from those lifecycle hooks. A parent may ask several questions while a child ticket is outstanding: track each new picker and preserve child approval cards independently, including when their display titles match. Answering either resolves only that question or ticket.
SSH Codex metrics must stay scoped to the host and account being read. Credentials and quota HTTP requests remain on that host; only sanitized usage returns over SSH. Never route a failed remote context lookup into a local transcript reader, or reuse Claude's token formula/window estimate for Codex. The system account follows the host login environment; managed accounts use their validated private home. Usage refresh must not start or repair a shared Codex daemon.
Delayed Windows message submission must recheck the attested child process/birth AND emulator paste mode immediately before Enter, not just the surviving PTY root. A missing host reply after a transmitted text request is uncertain delivery, never a pre-paste refusal; show the no-resend warning. SessionStart idle rescue is scoped to that same nonempty session and agent identity, and a foreign idle must not broadcast fresh state proof to the renderer.
Control and linked-context fallback must keep a known node identity on the endpoint family the
session was born on. A foreign server being reachable is not evidence that it owns the canvas —
and a matching token is not proof either (on an SSH host the token dir is shared per unix
account); it is a routing rule, and the server still authorizes. Take the reference token from the
primary endpoint's own dir, never from a global directory, and match each candidate's own dir
against it — by value, or, when the reference is empty, by the directory's real path (an empty
value matches every stranger). Probe a fallback candidate (bounded) before posting to it, but never put a timeout on
the real POST: a confirm-gated verb waits for a human. Keep real owning-endpoint refusals final and
legacy hook delivery unchanged. When no owner answers, say so once, as a temporary state
(FOREIGN_ENDPOINT_HINT); never let another instance's "permanent, do not retry" stand in for a
dropped tunnel.
Browser control must measure settled geometry. A CDP wheel acknowledgement precedes
Chromium's scroll frames. Use the bounded settlement helper before reporting movement or
resolving pointer targets. Keep actions on one guest exclusive. A CDP viewport override
(--screenshot --full true) survives debugger detach and a reload: it goes through the lease,
which clears it before every detach and on the next attach — never send emulation around it, and
never reattach a released lease to clean up.