Skip to content

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

docs: a remote project's node runs under its project's session, never this core

review8520d40fde05
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 inside
that 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 but
the 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 to
the SAME remote's live session (a second view over the same endpoint) still attaches, and so does
a 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)). An
offline node reports itself to `SshReconnector`, so the canvas heals itself; `retryNow` (banner
Reconnect / 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 mea
node shows its column as a **half-pill flush on the node's TOP edge** — see the pill sentence
below. A card's ↗ / double-click opens the **card modal** (`components/kanban/CardModal.tsx`, body
portal 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 an
optional TRAILING arg through preload/ws-bridge/LocalTransport, absent = bit-for-bit legacy, and
a client's per-connection socket pause survives a single view's departure). The modal viewer
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 168deee18..41121b017 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -648,6 +648,25 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
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`/`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 every
existing iPhone carries (`src/main/pairing-core.ts`). Link to a store only through