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): never join a local session for a remote-only create
review46028defeea0
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 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 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.tsnew file mode 100644index 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.tsindex 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: FakePlatformlet 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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['unavailableconnectionLost: 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.tsindex 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. */