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
fix(pty): held-elsewhere follow-ups from review
review8bfe6793f541
diff --git a/CLAUDE.md b/CLAUDE.mdindex e1e73e2ee..0bdcfd315 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -862,11 +862,11 @@ Lifecycle, by intent:(`PtyCreateResult.unavailable`) so a master that dies inside the round-trip can't sneak through.The spawn refusal is in `spawnNew`, and `join` refuses (`'held-elsewhere'`) a `requireRemote`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, a relay tab's create on the host) still attaches,- and so does a create whose master is momentarily down (no `sshRemote`) onto a held remote session.- The held session is never killed. 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.+ 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+ 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,`@shared/ssh-project-nodes`). `requireRemote`/`sshRemoteTmux` used to be stamped only by thismachine's node factories, but an SSH project's `project.json` lives on the host and other writersdiff --git a/src/core/pty-manager.ts b/src/core/pty-manager.tsindex c6b84c768..a075ed67e 100644--- a/src/core/pty-manager.ts+++ b/src/core/pty-manager.ts@@ -908,6 +908,11 @@ interface Session {/** True when this node had an `accountId` but its config dir was gone at spawn, so we fell back* to the system account. `create()` surfaces it to the renderer (warning chip). */accountFallback?: boolean+ /** Set once `join` has warned that this session holds a remote-only node's id somewhere other+ * than that node's host (`held-elsewhere`). A watcher retries its join every 2/4/8/15 s for as+ * long as the link lives, and every retry is refused the same way, so the warning is logged once+ * for the life of this held session; a later session under the same id warns again. */+ heldElsewhereWarned?: boolean/*** This session is backed by the session-host process (docs/windows-session-host.md), not a* local tmux — selected only when no local tmux was found (primarily Windows). `session.proc`@@ -2687,9 +2692,12 @@ export class PtyManager {(!existing.sshRemote ||(options.sshRemote && !sameSshEndpoint(options.sshRemote.conn, existing.sshRemote.conn)))) {- console.warn(- `[pty] ${sessionName(persistKey)} is held ${existing.sshRemote ? 'on another host' : 'on this machine'} but node ${persistKey} must run on its remote host; not joined, and the held session was left untouched`- )+ if (!existing.heldElsewhereWarned) {+ existing.heldElsewhereWarned = true+ console.warn(+ `[pty] ${sessionName(persistKey)} is held ${existing.sshRemote ? 'on another host' : 'on this machine'} but node ${persistKey} must run on its remote host; not joined, and the held session was left untouched`+ )+ }return Promise.resolve({ sessionId: '', fresh: false, unavailable: 'held-elsewhere' })}// The joining VIEW's composite key: a second client, OR the SAME client's second view (thediff --git a/src/core/pty-require-remote-join.test.ts b/src/core/pty-require-remote-join.test.tsindex 7adabbe4d..21861c11f 100644--- a/src/core/pty-require-remote-join.test.ts+++ b/src/core/pty-require-remote-join.test.ts@@ -165,6 +165,18 @@ describe('requireRemote create vs a live session of the same node id', () => {expect(spawned[0].killed).toBe(false)})+ it('warns once for the held session, however often the refused join is retried', async () => {+ // A live-link watcher retries its join every 2/4/8/15 s for as long as the link lives, and each+ // retry is refused the same way: one warning for the held session, not one per retry.+ const local = await localHeld()+ const retry = () => create(MODAL_OR_SECOND_VIEW, { agentId: 'claude', requireRemote: true })+ const results = [await retry(), await retry(), await retry()]++ expect(results.map((r) => r.unavailable)).toEqual(['held-elsewhere', 'held-elsewhere', 'held-elsewhere'])+ expect(warnedAbout()).toHaveLength(1)+ expect(subscribersOf(local.sessionId)).toBe(1)+ })+it('a create WITHOUT requireRemote still joins the local session (local nodes unchanged)', async () => {const local = await localHeld()const res = await create(MODAL_OR_SECOND_VIEW, { agentId: 'claude', cwd: '/home/e2e/proj-alpha' })@@ -225,6 +237,32 @@ describe('requireRemote create vs a live session of the same node id', () => {expect(subscribersOf(first.sessionId)).toBe(1)})+ it('joins when one side names no user and the other an empty one', async () => {+ // `user` is typed as a string but arrives from hand-editable JSON, so a create can carry none+ // at all while the held session spells it ''. Both mean "ssh's default user": same endpoint.+ // (The other way round cannot be held: a spawn refuses a user that is not a string.)+ const first = await create(RENDERER, {+ agentId: 'claude',+ requireRemote: true,+ sshRemote: remoteFor({ host: HOST.host, user: '' })+ })+ expect(first.unavailable).toBeUndefined()+ expect(spawned).toHaveLength(1)+ expect(spawned[0].file).toBe('/usr/bin/ssh')++ const res = await create(MODAL_OR_SECOND_VIEW, {+ agentId: 'claude',+ requireRemote: true,+ sshRemote: remoteFor({ host: HOST.host, user: undefined as unknown as string, port: 22 })+ })++ expect(res.unavailable).toBeUndefined()+ expect(res.sessionId).toBe(first.sessionId)+ expect(spawned).toHaveLength(1)+ expect(subscribersOf(first.sessionId)).toBe(2)+ expect(warnedAbout()).toHaveLength(0)+ })+it('joins on the same host, user and port (an unset port is 22)', async () => {const first = await remoteHeld()// A second view reaches the same endpoint over its own ControlMaster path, with the portdiff --git a/src/core/pty-watch-join.test.ts b/src/core/pty-watch-join.test.tsindex 0fa3dfe1a..b16199640 100644--- a/src/core/pty-watch-join.test.ts+++ b/src/core/pty-watch-join.test.ts@@ -270,9 +270,28 @@ describe('joinAsWatcher', () => {it('reads the window size only to SPAWN a client — never to join a held session', async () => {const m = await tmuxManager(['nt-n1'], { window: { cols: 132, rows: 43 } })const read = (m as unknown as { readWindowSize: ReturnType<typeof vi.fn> }).readWindowSize- const a = await create(OWNER, { cols: 120, rows: 40 })+ // The held session is a REMOTE node's (an SSH project's), the case R64/M4 is about: a+ // `requireRemote` watcher may join it, where a held LOCAL session would be refused+ // (`held-elsewhere`) and the size rule below would never run. No host is asked anything: the+ // freshness read answers "absent" so the owner's (mocked) ssh client spawns.+ const internals = m as unknown as {+ remoteSessionVerdict: () => Promise<string>+ captureForResync: (s: string) => Promise<string>+ paneCursor: (s: string) => Promise<unknown>+ }+ vi.spyOn(internals, 'remoteSessionVerdict').mockResolvedValue('absent')+ vi.spyOn(internals, 'captureForResync').mockResolvedValue('')+ vi.spyOn(internals, 'paneCursor').mockResolvedValue(undefined)+ const sshRemote = { controlPath: '/tmp/nt-test-cm-watch-size', conn: { host: 'h', user: 'u' }, remoteCwd: '/srv/app' }+ const a = await create(OWNER, { cols: 120, rows: 40, requireRemote: true, sshRemote })+ expect(a.unavailable).toBeUndefined()+ expect(spawned[0].file).toBe('/usr/bin/ssh')await m.joinAsWatcher(WATCHER, WATCH) // a live Session is held and the caller gave a size- await m.joinAsWatcher(WATCHER + 1, { persistKey: 'n1', viewerId: 'watch-s2', requireRemote: true }) // no size+ // No size, and no master (it is down): joins the held remote session.+ const w = await m.joinAsWatcher(WATCHER + 1, { persistKey: 'n1', viewerId: 'watch-s2', requireRemote: true })+ expect(w.unavailable).toBeUndefined()+ expect(w.sessionId).toBe(a.sessionId)+ expect(spawned).toHaveLength(1)expect(read).not.toHaveBeenCalled()// The view is shown the held session's own size (nothing to correct, so nothing more is sent).expect(fake.sent.filter((x) => x.channel === IPC.ptySize(a.sessionId) && x.to === WATCHER + 1)).toEqual([])diff --git a/src/core/watch-link/pty-seam.ts b/src/core/watch-link/pty-seam.tsindex 76640bfab..be298b86a 100644--- a/src/core/watch-link/pty-seam.ts+++ b/src/core/watch-link/pty-seam.ts@@ -94,7 +94,8 @@ function sshConnOf(v: unknown): SshConnection | null {* whether or not that master is up (the renderer's own rule for the node's spawn);* - anything else (a local node, a standalone ssh terminal whose `ssh` runs in LOCAL tmux): local.* Records that throw answer `requireRemote` with no master: a join that cannot be placed never reaches- * the local socket (it joins a session this process already holds, or waits).+ * the local socket. It joins only a REMOTE session this process already holds; a held LOCAL one is+ * refused (`held-elsewhere`, see PtyManager `join`), and otherwise it waits.*/export function watchRemoteFor(nodeId: string, r: WatchRemoteRecords): WatchRemote {try {