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): never join a local session for a remote-only create

review46028defeea0
diff --git a/CLAUDE.md b/CLAUDE.md
index 3e8e3bdaa..e1e73e2ee 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -860,9 +860,13 @@ Lifecycle, by intent:
sides: the renderer never calls `create` when `resolveSshRemote` came back empty
(`CoState.offline` + the node's Reconnect button), and core refuses in `spawnNew`
(`PtyCreateResult.unavailable`) so a master that dies inside the round-trip can't sneak through.
- The refusal is **only** in `spawnNew` — a co-attach JOIN to a live session for that node id is
- still correct. 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 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.
**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 f3bb53afc..c6b84c768 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -744,6 +744,16 @@ function normalizeSize(cols: number, rows: number): PtySize {
return effectiveSize([{ cols, rows }]) as PtySize // one entry in ⇒ never null out
}
+/**
+ * The same machine, as far as a `requireRemote` join is concerned: host, user (`''` when unset) and
+ * port (22 when unset). The ControlMaster path is deliberately not compared — two views of one host
+ * may hold different masters for it — and neither are identity file or extra args, which change how
+ * we log in, not where the session runs.
+ */
+function sameSshEndpoint(a: SshConnection, b: SshConnection): boolean {
+ return a.host === b.host && (a.user ?? '') === (b.user ?? '') && (a.port ?? 22) === (b.port ?? 22)
+}
+
/**
* Hand a remote spawn's gate slot back the moment its pty produces its first byte — the cheapest
* signal that the ssh channel is up and the host has answered.
@@ -2664,6 +2674,24 @@ export class PtyManager {
existing = existingId ? this.sessions.get(existingId) : undefined
}
if (!existingId || !existing) return undefined
+ // A node that lives on a remote host never joins a session that is not on THAT host. The match
+ // above is by node id alone, and a LOCAL session can carry a remote node's id (a hosted team
+ // tab's node mounted under it, a pre-`requireRemote` orphan), so joining it would put the remote
+ // node on this machine's shell — the outcome `spawnRefusal` refuses for a spawn. Refused when
+ // the held session is local, or when the create names its master and that master reaches a
+ // different endpoint. A create with no `sshRemote` (its master momentarily down) still joins a
+ // held REMOTE session: it runs on a host, and nothing says it is the wrong one. The held session
+ // is never touched — it may hold work someone typed into it (same rule as prepareRelayAttach).
+ if (
+ options.requireRemote &&
+ (!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`
+ )
+ 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
// kanban card modal). Either way it is a distinct subscriber of the one shared session/pty.
const sub = subKey(clientId, options.viewerId ?? PRIMARY_VIEWER)
@@ -2759,10 +2787,11 @@ export class PtyManager {
// node's identity, which is the one outcome a remote node must never have (see
// `PtyCreateOptions.requireRemote`). Refuse instead; the renderer waits for the master.
//
- // Deliberately on the SPAWN path (`spawnNew`, and the relay host's `prepareRelayAttach`) and
- // not in `create`: a co-attach JOIN to a live session for
- // this node id is still correct (that session already runs wherever it runs), so only the
- // branch that would have created a new local session is refused. `findSsh()` is checked for
+ // Deliberately on the SPAWN path (`spawnNew`, and the relay host's `prepareRelayAttach`). A
+ // co-attach JOIN never reaches it: `join` answers first and has its own rule
+ // (`'held-elsewhere'`) — it refuses when the held session for this node id is local or on
+ // another host, and still attaches to a live session on the requested remote (or on any remote
+ // while the create's master is down). `findSsh()` is checked for
// the same reason `spawnSession` checks it — without the executable the remote branch there
// is skipped and the local one runs.
if (options.requireRemote && !(options.sshRemote && options.persistKey && findSsh())) {
diff --git a/src/core/pty-require-remote-join.test.ts b/src/core/pty-require-remote-join.test.ts
new file mode 100644
index 000000000..7adabbe4d
--- /dev/null
+++ b/src/core/pty-require-remote-join.test.ts
@@ -0,0 +1,245 @@
+import { describe, it, expect, beforeEach, afterEach, vi, type MockInstance } from 'vitest'
+import { initPlatform, resetPlatformForTests } from './platform'
+import { fakePlatform, type FakePlatform } from './platform-fake'
+import { IPC } from '../shared/ipc'
+import type { PtyCreateOptions, PtyCreateResult } from '../shared/types'
+
+/**
+ * A `requireRemote` create must never JOIN a live session that is not on the remote it names.
+ *
+ * `join()` used to match on `persistKey` alone, so an SSH-project node (the card modal, or the
+ * canvas after "Open here anyway") attached to a live LOCAL session that happened to carry the same
+ * node id — a hosted team tab's node mounted under the local session, or a pre-`requireRemote`
+ * orphan. The refusal in `spawnNew` never ran, because nothing was spawned: the join answered
+ * first. Now the join is refused (`'held-elsewhere'`) when the held session is local, or is on a
+ * different endpoint than the create's `sshRemote`; the held session itself is never touched.
+ */
+interface FakePty {
+ file: string
+ args: string[]
+ killed: boolean
+}
+const spawned: FakePty[] = []
+
+// Pin the persistence backend (see src/core/__fixtures__/no-session-host.ts).
+vi.mock('./session-host-backend', async () =>
+ (await import('./__fixtures__/no-session-host')).noSessionHost()
+)
+
+vi.mock('node-pty', () => ({
+ spawn: (file: string, args: string[]) => {
+ const p: FakePty = { file, args: [...(args ?? [])], killed: false }
+ spawned.push(p)
+ return {
+ onData: () => {},
+ onExit: () => {},
+ write: () => {},
+ resize: () => {},
+ pause: () => {},
+ resume: () => {},
+ kill: () => {
+ p.killed = true
+ },
+ pid: 4321
+ }
+ }
+}))
+
+// A machine with pty devices to spare, always (same reason as pty-require-remote.test.ts).
+vi.mock('./pty-devices', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('./pty-devices')>()),
+ readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
+}))
+
+// A REMOTE held session needs `findSsh` to resolve (the spawn's remote branch is skipped without
+// it), and the agent-socket probe would run a real `ssh -G`. Every other lookup is the real one.
+vi.mock('./exec-path', async (importOriginal) => {
+ const real = await importOriginal<typeof import('./exec-path')>()
+ return {
+ ...real,
+ findExecutableSync: (bin: string, fallbacks?: string[]) =>
+ bin === 'ssh' ? '/usr/bin/ssh' : real.findExecutableSync(bin, fallbacks)
+ }
+})
+vi.mock('./remote-ssh/agent-probe', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('./remote-ssh/agent-probe')>()),
+ probeAgentSockToPin: async () => undefined
+}))
+
+const RENDERER = 1
+const MODAL_OR_SECOND_VIEW = 2
+const NODE = 'term-musuoygd-979507b8'
+
+type SshRemote = NonNullable<PtyCreateOptions['sshRemote']>
+
+let pathSeq = 0
+/** A fresh ControlMaster path per test: the remote spawn gate is module-wide and keyed by it. */
+const remoteFor = (conn: SshRemote['conn']): SshRemote => ({
+ controlPath: `/tmp/nt-test-cm-join-${++pathSeq}`,
+ conn,
+ remoteCwd: '~/proj-alpha'
+})
+
+describe('requireRemote create vs a live session of the same node id', () => {
+ let fake: FakePlatform
+ let manager: import('./pty-manager').PtyManager
+ let warn: MockInstance<typeof console.warn>
+
+ beforeEach(async () => {
+ spawned.length = 0
+ fake = fakePlatform()
+ initPlatform(fake)
+ const { PtyManager } = await import('./pty-manager')
+ manager = new PtyManager()
+ manager.registerIpc()
+ // The remote freshness read would run `ssh … tmux list-sessions` over the master: answered
+ // "absent" here, so a remote create spawns its (mocked) ssh client without touching a host.
+ vi.spyOn(
+ manager as unknown as { remoteSessionVerdict: () => Promise<string> },
+ 'remoteSessionVerdict'
+ ).mockResolvedValue('absent')
+ // A join that does not resize paints the joiner from a capture — over ssh for a remote session.
+ // Nothing here is about the screen, so no real ssh is ever run for it.
+ const paint = manager as unknown as {
+ captureForResync: (s: string) => Promise<string>
+ paneCursor: (s: string) => Promise<unknown>
+ }
+ vi.spyOn(paint, 'captureForResync').mockResolvedValue('')
+ vi.spyOn(paint, 'paneCursor').mockResolvedValue(undefined)
+ warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ })
+ afterEach(() => {
+ vi.restoreAllMocks()
+ resetPlatformForTests()
+ })
+
+ const create = (clientId: number, options: Partial<PtyCreateOptions>) =>
+ fake.handlers[IPC.ptyCreate](clientId, {
+ cols: 80,
+ rows: 24,
+ persistKey: NODE,
+ ...options
+ }) as Promise<PtyCreateResult>
+
+ const subscribersOf = (sessionId: string): number =>
+ (manager as unknown as { sessions: Map<string, { subscribers: Set<unknown> }> }).sessions.get(sessionId)!
+ .subscribers.size
+
+ const warnedAbout = (): unknown[][] => warn.mock.calls.filter((c) => String(c[0]).includes(NODE))
+
+ /** The hosted team tab's node mounted under the LOCAL session: no sshRemote, no requireRemote. */
+ async function localHeld(): Promise<PtyCreateResult> {
+ const local = await create(RENDERER, { agentId: 'claude', cwd: '/home/e2e/proj-alpha' })
+ expect(local.unavailable).toBeUndefined()
+ expect(spawned).toHaveLength(1)
+ expect(spawned[0].file.endsWith('ssh')).toBe(false) // the LOCAL branch, never ssh
+ return local
+ }
+
+ it('refuses to join a LOCAL session for a requireRemote create', async () => {
+ const local = await localHeld()
+ const res = await create(MODAL_OR_SECOND_VIEW, {
+ agentId: 'claude',
+ cwd: '~/proj-alpha',
+ requireRemote: true,
+ sshRemote: remoteFor({ host: 'h.example', user: 'e2e', port: 22 })
+ })
+
+ expect(res.unavailable).toBe('held-elsewhere')
+ expect(res.sessionId).toBe('')
+ expect(spawned).toHaveLength(1) // nothing spawned remotely either
+ // Refused BEFORE subscribing: the held session gained no second view, and was never killed.
+ expect(subscribersOf(local.sessionId)).toBe(1)
+ expect(spawned[0].killed).toBe(false)
+ expect(warnedAbout()).toHaveLength(1)
+ })
+
+ it('refuses the same join when the master is momentarily down (no sshRemote)', async () => {
+ const local = await localHeld()
+ const res = await create(MODAL_OR_SECOND_VIEW, { agentId: 'claude', requireRemote: true })
+
+ expect(res.unavailable).toBe('held-elsewhere')
+ expect(res.sessionId).toBe('')
+ expect(spawned).toHaveLength(1)
+ expect(subscribersOf(local.sessionId)).toBe(1)
+ expect(spawned[0].killed).toBe(false)
+ })
+
+ 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' })
+
+ expect(res.unavailable).toBeUndefined()
+ expect(res.sessionId).toBe(local.sessionId)
+ expect(spawned).toHaveLength(1)
+ expect(subscribersOf(local.sessionId)).toBe(2)
+ expect(warnedAbout()).toHaveLength(0)
+ })
+
+ describe('a held REMOTE session', () => {
+ const HOST = { host: 'h.example', user: 'e2e' } // port left to the `?? 22` default
+
+ async function remoteHeld(): Promise<PtyCreateResult> {
+ const first = await create(RENDERER, {
+ agentId: 'claude',
+ requireRemote: true,
+ sshRemote: remoteFor(HOST)
+ })
+ expect(first.unavailable).toBeUndefined()
+ expect(first.sessionId).not.toBe('')
+ expect(spawned).toHaveLength(1)
+ expect(spawned[0].file).toBe('/usr/bin/ssh') // the REMOTE branch
+ return first
+ }
+
+ it('is refused to a requireRemote create whose master names a DIFFERENT host', async () => {
+ const first = await remoteHeld()
+ const res = await create(MODAL_OR_SECOND_VIEW, {
+ agentId: 'claude',
+ requireRemote: true,
+ sshRemote: remoteFor({ ...HOST, host: 'other.example' })
+ })
+
+ expect(res.unavailable).toBe('held-elsewhere')
+ expect(res.sessionId).toBe('')
+ expect(spawned).toHaveLength(1)
+ expect(subscribersOf(first.sessionId)).toBe(1)
+ expect(spawned[0].killed).toBe(false)
+ expect(warnedAbout()).toHaveLength(1)
+ })
+
+ it('is refused when only the user or only the port differs', async () => {
+ const first = await remoteHeld()
+ const otherUser = await create(MODAL_OR_SECOND_VIEW, {
+ requireRemote: true,
+ sshRemote: remoteFor({ ...HOST, user: 'someone-else' })
+ })
+ const otherPort = await create(MODAL_OR_SECOND_VIEW, {
+ requireRemote: true,
+ sshRemote: remoteFor({ ...HOST, port: 2222 })
+ })
+
+ expect(otherUser.unavailable).toBe('held-elsewhere')
+ expect(otherPort.unavailable).toBe('held-elsewhere')
+ expect(spawned).toHaveLength(1)
+ expect(subscribersOf(first.sessionId)).toBe(1)
+ })
+
+ 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
+ // spelled out: still the same machine, so it attaches to the one live session.
+ const res = await create(MODAL_OR_SECOND_VIEW, {
+ agentId: 'claude',
+ requireRemote: true,
+ sshRemote: remoteFor({ ...HOST, 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)
+ })
+ })
+})
diff --git a/src/core/pty-require-remote.test.ts b/src/core/pty-require-remote.test.ts
index 3b7917f79..f95f47142 100644
--- a/src/core/pty-require-remote.test.ts
+++ b/src/core/pty-require-remote.test.ts
@@ -57,6 +57,22 @@ vi.mock('./pty-devices', async (importOriginal) => ({
readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))
+// The "still JOINS" case holds a REMOTE session, whose spawn needs `findSsh` to resolve (without it
+// the remote branch is skipped) and whose agent-socket probe would run a real `ssh -G`. Every other
+// executable lookup is the real one.
+vi.mock('./exec-path', async (importOriginal) => {
+ const real = await importOriginal<typeof import('./exec-path')>()
+ return {
+ ...real,
+ findExecutableSync: (bin: string, fallbacks?: string[]) =>
+ bin === 'ssh' ? '/usr/bin/ssh' : real.findExecutableSync(bin, fallbacks)
+ }
+})
+vi.mock('./remote-ssh/agent-probe', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('./remote-ssh/agent-probe')>()),
+ probeAgentSockToPin: async () => undefined
+}))
+
describe('pty create: requireRemote never falls back to a local shell', () => {
let fake: FakePlatform
let manager: import('./pty-manager').PtyManager
@@ -70,6 +86,7 @@ describe('pty create: requireRemote never falls back to a local shell', () => {
manager.registerIpc()
})
afterEach(() => {
+ vi.restoreAllMocks()
resetPlatformForTests()
})
@@ -98,11 +115,29 @@ describe('pty create: requireRemote never falls back to a local shell', () => {
expect(res.sessionId).not.toBe('')
})
- it('still JOINS a live session for that node — only a fresh local spawn is refused', async () => {
- // The session is already running (it was created while the master was up). A second view —
- // the kanban card modal, another window — must attach to it: the session runs wherever it
- // runs, and refusing the join would break a perfectly healthy remote terminal.
- const first = await create(ALICE, {})
+ it('still JOINS a live REMOTE session for that node — only a fresh local spawn is refused', async () => {
+ // The session is already running on the host (it was created while the master was up). A
+ // second view — the kanban card modal, another window — whose master is momentarily down must
+ // attach to it: refusing the join would break a perfectly healthy remote terminal. (A held
+ // LOCAL session is the opposite case and is refused: pty-require-remote-join.test.ts.)
+ const internals = manager as unknown as {
+ remoteSessionVerdict: () => Promise<string>
+ captureForResync: (s: string) => Promise<string>
+ paneCursor: (s: string) => Promise<unknown>
+ }
+ // No host to ask: the freshness read answers "absent" (so the first create spawns its ssh
+ // client) and the joiner's paint capture answers nothing, instead of running a real ssh.
+ vi.spyOn(internals, 'remoteSessionVerdict').mockResolvedValue('absent')
+ vi.spyOn(internals, 'captureForResync').mockResolvedValue('')
+ vi.spyOn(internals, 'paneCursor').mockResolvedValue(undefined)
+ const first = await create(ALICE, {
+ requireRemote: true,
+ sshRemote: { controlPath: '/tmp/nt-test-cm-require-remote', conn: { host: 'h1', user: 'u' }, remoteCwd: '/srv/app' }
+ })
+ expect(first.unavailable).toBeUndefined()
+ expect(spawned).toHaveLength(1)
+ expect(spawned[0].file).toBe('/usr/bin/ssh') // the remote branch, never a local shell
+
const joined = await create(BOB, { requireRemote: true })
expect(spawned).toHaveLength(1)
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 704aa4059..fc5e7f252 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -3684,8 +3684,10 @@ export function TerminalNode({
// this view does not hold), a refused-launch banner about a launch into a session that
// is not attached, and a letterbox sized to a pty that is not attached. Clear them the
// way the neighbouring refusals set theirs, say why the pane is empty, and stop;
- // "Refresh terminal" re-asks on demand.
- if (unavailable === 'join-only') {
+ // "Refresh terminal" re-asks on demand. `held-elsewhere` is the same shape: core found
+ // this remote node's id held by a session that is not on its host and did not join it —
+ // nothing is offline, and "Try again" would refuse again while that session runs.
+ if (unavailable === 'join-only' || unavailable === 'held-elsewhere') {
setCo(termKey, {
offline: false,
spawnError: null,
diff --git a/src/renderer/nodes/join-only-refusal-wiring.test.ts b/src/renderer/nodes/join-only-refusal-wiring.test.ts
index 060726e10..b8e9d20ef 100644
--- a/src/renderer/nodes/join-only-refusal-wiring.test.ts
+++ b/src/renderer/nodes/join-only-refusal-wiring.test.ts
@@ -1,5 +1,6 @@
// TerminalNode's handling of a `'join-only'` create refusal (a hosted-relay viewer asked for a
-// terminal it could not find running).
+// terminal it could not find running), and of `'held-elsewhere'` (a remote node's id is held by a
+// session that is not on its host), which takes the same branch: nothing is offline in either.
//
// The DECISION about the words is pure and tested in `shared/pty-refusal.test.ts`. What only the
// source can show is what the node does with it: this branch returns BEFORE the success path that
@@ -14,9 +15,9 @@ import path from 'path'
const src = fs.readFileSync(path.resolve(__dirname, 'TerminalNode.tsx'), 'utf8').replace(/\r\n/g, '\n')
-/** The body of `if (unavailable === 'join-only') { … }`, up to its `return`. */
+/** The body of the `'join-only'` / `'held-elsewhere'` branch, up to its `return`. */
function joinOnlyBranch(): string {
- const start = src.indexOf("if (unavailable === 'join-only') {")
+ const start = src.indexOf("if (unavailable === 'join-only' || unavailable === 'held-elsewhere') {")
expect(start, 'the join-only branch must still exist').toBeGreaterThan(-1)
const end = src.indexOf('return', start)
expect(end).toBeGreaterThan(start)
@@ -32,7 +33,7 @@ function coStateFields(): string[] {
return [...src.slice(start, end).matchAll(/^ {2}(\w+):/gm)].map((m) => m[1])
}
-describe("TerminalNode: a 'join-only' refusal", () => {
+describe("TerminalNode: a 'join-only' or 'held-elsewhere' refusal", () => {
it('resets every CoState field that describes a session, and only those', () => {
const branch = joinOnlyBranch()
const fields = coStateFields()
diff --git a/src/shared/pty-refusal.test.ts b/src/shared/pty-refusal.test.ts
index dac08aaad..1063e866e 100644
--- a/src/shared/pty-refusal.test.ts
+++ b/src/shared/pty-refusal.test.ts
@@ -22,4 +22,14 @@ describe('PTY refusal presentation', () => {
it('the join-only message does not claim the terminal is not running', () => {
expect(ptyRefusal('join-only').message).not.toMatch(/is not running/)
})
+ // A remote node's create found a live session with its id held somewhere else (locally, or on
+ // another host) and did not join it. The project's master is fine: read as `connectionLost`, the
+ // node would show "not connected" and kick the reconnector, whose retry refuses again.
+ it('a held-elsewhere refusal is not a lost connection, and says nothing was started', () => {
+ expect(ptyRefusal('held-elsewhere')).toEqual({
+ connectionLost: false,
+ message:
+ "a session with this terminal's id is already running somewhere other than its host, so it was not joined — nothing was started"
+ })
+ })
})
diff --git a/src/shared/pty-refusal.ts b/src/shared/pty-refusal.ts
index d650d9933..d75655562 100644
--- a/src/shared/pty-refusal.ts
+++ b/src/shared/pty-refusal.ts
@@ -21,5 +21,16 @@ export function ptyRefusal(unavailable: NonNullable<PtyCreateResult['unavailable
connectionLost: false
}
}
+ // A remote node's create found its id held by a live session that is not on its host (a local
+ // session, or another endpoint) and did not join it. The project's master may be perfectly
+ // healthy, so this is not a lost connection — reporting one would kick the reconnector, whose
+ // respawn refuses again.
+ if (unavailable === 'held-elsewhere') {
+ return {
+ message:
+ "a session with this terminal's id is already running somewhere other than its host, so it was not joined — nothing was started",
+ connectionLost: false
+ }
+ }
return { message: 'not connected — nothing was started locally', connectionLost: true }
}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 6a610a2d6..313eeed11 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -410,9 +410,15 @@ export interface PtyCreateResult {
* `PtyCreateOptions.requireRemote` for what used to happen instead. The renderer shows the
* "not connected" overlay and re-spawns the node once the project's master is back.
*
- * Only ever set for a create that would have SPAWNED: a co-attach to a live session for this
- * node id still joins (the session is already running wherever it runs), so a second view of a
- * healthy remote terminal is unaffected.
+ * `'ssh'` is only ever set for a create that would have SPAWNED: a co-attach to a live session
+ * for this node id on the requested remote still joins, so a second view of a healthy remote
+ * terminal is unaffected.
+ *
+ * `'held-elsewhere'`: a `requireRemote` create found a live session for this node id held by this
+ * process, but NOT on the requested remote — it is local, or its endpoint (host, user, port)
+ * differs from the create's `sshRemote`. The join is refused and nothing was started; the held
+ * session is left untouched. A create with no `sshRemote` (master down) still joins a held
+ * remote session. Not a lost connection: retrying would refuse again.
*
* `'codex-account'` is the S6 fail-closed twin: a LOCAL Codex node that explicitly selected a
* managed account whose home is missing refuses rather than spawning against the system login
@@ -423,7 +429,7 @@ export interface PtyCreateResult {
* session could be confirmed to join or reattach to — either it is gone, or its existence could
* not be checked — so nothing was started. Not a lost connection.
*/
- unavailable?: 'ssh' | 'codex-account' | 'join-only'
+ unavailable?: 'ssh' | 'codex-account' | 'join-only' | 'held-elsewhere'
}
/** Payload of `pty:recycled` — see IPC.ptyRecycled and `recycleAction` in the renderer. */