Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
docs: a remote project's node runs under its project's session, never this core
review8520d40fde05
diff --git a/CLAUDE.md b/CLAUDE.mdindex 17a54264e..9443659d0 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -565,6 +565,34 @@ project's nodes only.** The contract:rethrown: it runs in a passive effect and `<Canvas />` has no error boundary.`flowStoreOwner.test.tsx` replays the switches through real React Flow, the timer firing insidethat window and the folder-open continuation included.+- **A remote project's node never starts on this core, whatever it is mounted under** (bug F: a+ team tab's terminals were created as LOCAL tmux sessions here). The node itself cannot say so: a+ project shared from SSH with a team is ADOPTED by the host (`localizeAdoptedNode` drops+ `sshRemoteTmux`/`ssh`/`sshFs`), so its nodes reach the tab as plain terminals. Do NOT re-stamp+ `sshRemoteTmux` onto them — the host's core would then refuse its own sessions (`requireRemote`+ with no master of its own: `held-elsewhere` for a live one, a refused spawn otherwise). Three+ layers besides the keying above:+ (1) `sessionForProject` resolves a REMOTE project (`remote` in the store, or bound while remote in+ this run) with no live binding to the OFFLINE relay session (`OFFLINE_RELAY_SESSION_ID`,+ `session/offline-relay-session.ts`: `source 'relay'`, `status 'offline'`, every core call+ rejects), never the local one. Lifecycle code asking "which session is bound to this tab?" (dispose+ it, reconnect it) asks `boundSessionForProject`, which never answers the sentinel.+ (2) A surface that mounts a project's node OUTSIDE Canvas's node subtree runs under that project's+ session. Both kanban boards render under App's LOCAL provider, so each mounts its card modal+ through `ProjectSessionScope` (`session/owning-project.ts`: `sessionForProject(<card's project>)`,+ keyed by session id, plus `OwningProjectContext`). Before it, opening a team tab's terminal card+ created the host's node id on this desktop every time. Everything under the modal that asks+ `useSession()` — terminal, ⌘M chat, file links — now talks to the core the node runs on. The+ session is resolved at render, so a reconnect while a modal is open takes effect at the board's+ next render.+ (3) TerminalNode and ModalTerminal ask `spawnBelongsElsewhere(project, session.source)` (the+ project from `OwningProjectContext`) before any SSH resolve or create: a remote project under a+ non-relay session starts nothing and writes a gray "belongs to a remote project that is not+ connected here" line. ModalTerminal mirrors TerminalNode's `dialsSsh` (a relay card's SSH-project+ node is joined by the HOST with `requireRemote`; this machine dials, refuses and reports nothing+ for it), and a non-dialing node's `ownerProjectId` is the owning project, else the active one.+ `components/kanban/cardModalSession.test.tsx` renders both boards' modals under real sessions;+ `session/offline-relay-session.test.ts` replays the switches.- Switching away unmounts the old project's `TerminalNode`s → their tmux clients detach butthe sessions keep running; switching back reattaches. tmux session names are per-node-id(globally unique), so projects never collide.@@ -889,7 +917,9 @@ Lifecycle, by intent:create whose held session is local or on another host (host, user, or port differs) — a join tothe SAME remote's live session (a second view over the same endpoint) still attaches, and so doesa create that names no `sshRemote` onto a held remote session (its master momentarily down, or a- relay tab's create on the host, which carries none). The held session is never killed. An+ relay tab's create on the host, which carries none). The held session is never killed. A relay /+ team tab's node, which may carry no `sshRemoteTmux` at all, is kept off this core by the session+ it runs under plus a renderer-side `spawnBelongsElsewhere` refusal (Projects (tabs)). Anoffline node reports itself to `SshReconnector`, so the canvas heals itself; `retryNow` (bannerReconnect / node Reconnect) skips the backoff and clears the refuse window.**Whether a node is remote comes from its PROJECT, never from its own fields** (issue #1186,@@ -8544,8 +8574,10 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord meanode shows its column as a **half-pill flush on the node's TOP edge** — see the pill sentencebelow. A card's ↗ / double-click opens the **card modal** (`components/kanban/CardModal.tsx`, bodyportal on the dialog-stack, scrim z 55, scrim/Esc close — Esc in CAPTURE phase, and an Esc- during a header rename only cancels the edit). Terminal cards get a LIVE second view of the- tmux session (`ModalTerminal.tsx`): the pty subscriber ledger is keyed by the composite+ during a header rename only cancels the edit). The modal runs under the CARD project's session+ (`ProjectSessionScope` — the boards themselves sit under App's local provider; see "A remote+ project's node never starts on this core" under Projects). Terminal cards get a LIVE second+ view of the tmux session (`ModalTerminal.tsx`): the pty subscriber ledger is keyed by the composite`(ClientId, viewerId ?? PRIMARY)` (`core/pty-manager.ts` — **viewer identity**; viewerId is anoptional TRAILING arg through preload/ws-bridge/LocalTransport, absent = bit-for-bit legacy, anda client's per-connection socket pause survives a single view's departure). The modal viewerdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 168deee18..41121b017 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -648,6 +648,25 @@ anything else. Board-level fields survive every transform — `pullLinks` is oneterminal goes through those, not through the node's fields alone. CLAUDE.md, "A remote node isNEVER 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`/`ssh` from 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's `SessionProvider` on `activeProjectId`. 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?" asks `boundSessionForProject`.+ - 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 provides+ `OwningProjectContext`: wrap it in `ProjectSessionScope` (`session/owning-project.ts`). A new+ terminal-creating path also asks `spawnBelongsElsewhere` before its first create.+ - Core `join` refuses (`held-elsewhere`) a `requireRemote` create onto a held session that is+ local or on another host. Never join by node id alone.+ Do not "fix" this by re-stamping `sshRemoteTmux` onto those nodes: the host would then refuse its+ own sessions. CLAUDE.md, "Projects (tabs)".+- **Phone keys and store links are platform-neutral.** New paired keys are stamped`nodeterm-mobile-<id>`, but revoke must keep matching the legacy `nodeterm-ios-<id>` stamp everyexisting iPhone carries (`src/main/pairing-core.ts`). Link to a store only through