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.

fix(pty): held-elsewhere follow-ups from review

review8bfe6793f541
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 this
machine's node factories, but an SSH project's `project.json` lives on the host and other writers
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 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 (the
diff --git a/src/core/pty-require-remote-join.test.ts b/src/core/pty-require-remote-join.test.ts
index 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 port
diff --git a/src/core/pty-watch-join.test.ts b/src/core/pty-watch-join.test.ts
index 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.ts
index 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 {