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.

47.3 KB
Raw Blame
import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
import { IPC } from '../shared/ipc'
import { initPlatform, resetPlatformForTests } from './platform'
import { fakePlatform, type FakePlatform } from './platform-fake'
import { DEFAULT_SETTINGS } from '../shared/types'

const backend = vi.hoisted(() => ({
  supported: vi.fn(() => true),
  create: vi.fn(),
  attachExisting: vi.fn(),
  capture: vi.fn(async () => ''),
  hasSession: vi.fn(async () => false),
  // Mirrors `sessionHostKillSession(name, options)`. The parameters are load-bearing even though
  // this default body ignores them: several tests assert on the options the caller passed, and a
  // zero-arg mock infers `() => Promise<void>`, which makes every one of those
  // `mockImplementationOnce((name, options) => …)` a type error.
  kill: vi.fn(
    async (
      _name: string,
      _options: {
        reserveReplacement?: boolean
        requireV2?: boolean
        expectedAbsent?: boolean
      } = {}
    ): Promise<void> => {}
  ),
  list: vi.fn(async () => []),
  paneCommand: vi.fn(async () => null),
  sendKeys: vi.fn(async () => false)
}))

vi.mock('./session-host-backend', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./session-host-backend')>()),
  sessionHostSupported: backend.supported,
  createSessionHostPty: backend.create,
  attachExistingSessionHostPty: backend.attachExisting,
  sessionHostCapture: backend.capture,
  sessionHostHasSession: backend.hasSession,
  sessionHostKillSession: backend.kill,
  sessionHostListSessions: backend.list,
  sessionHostPaneCommand: backend.paneCommand,
  sessionHostSendKeys: backend.sendKeys
}))

vi.mock('node-pty', () => ({
  spawn: vi.fn(() => {
    throw new Error('direct node-pty spawn must not run in the session-host suite')
  })
}))

vi.mock('./pty-devices', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./pty-devices')>()),
  readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
}))

function fakeSessionHostPty(ready = Promise.resolve({ fresh: true })) {
  let dataCb: ((data: string) => void) | undefined
  let exitCb: ((e: { exitCode: number }) => void) | undefined
  let attachErrorCb: ((error: Error) => void) | undefined
  let sizeCb: ((size: { cols: number; rows: number }) => void) | undefined
  return {
    ready,
    onSize: vi.fn((cb: (size: { cols: number; rows: number }) => void) => {
      sizeCb = cb
    }),
    emitSize: (cols: number, rows: number) => sizeCb?.({ cols, rows }),
    onData: vi.fn((cb: (data: string) => void) => {
      dataCb = cb
    }),
    onExit: vi.fn((cb: (e: { exitCode: number }) => void) => {
      exitCb = cb
    }),
    onAttachError: vi.fn((cb: (error: Error) => void) => {
      attachErrorCb = cb
    }),
    emitData: (data: string) => dataCb?.(data),
    emitExit: (exitCode: number) => exitCb?.({ exitCode }),
    emitAttachError: (error: Error) => attachErrorCb?.(error),
    write: vi.fn(),
    resize: vi.fn(),
    pause: vi.fn(),
    resume: vi.fn(),
    kill: vi.fn(),
    destroy: vi.fn()
  }
}

describe('PtyManager session-host contracts', () => {
  let manager: import('./pty-manager').PtyManager | undefined
  let host: FakePlatform
  let PtyManagerCtor: typeof import('./pty-manager').PtyManager

  // The first dynamic import of pty-manager is cold and heavy (~5 s on the windows-latest runner).
  // Paying it inside makeManager() charged it to whichever test ran first, which then hit the
  // default 5 s test timeout (the #914 size test failed that way twice). Load it once, here, under
  // a hook timeout sized for a cold import; every test then only constructs.
  beforeAll(async () => {
    PtyManagerCtor = (await import('./pty-manager')).PtyManager
  }, 60_000)

  beforeEach(() => {
    host = fakePlatform()
    initPlatform(host)
    backend.supported.mockReturnValue(true)
    backend.create.mockReset().mockImplementation(() => fakeSessionHostPty())
    backend.attachExisting
      .mockReset()
      .mockImplementation(() => fakeSessionHostPty(Promise.resolve({ fresh: false })))
    backend.capture.mockReset().mockResolvedValue('')
    backend.hasSession.mockReset().mockResolvedValue(false)
    backend.kill.mockReset().mockResolvedValue(undefined)
  })

  afterEach(async () => {
    await manager?.killAll()
    manager = undefined
    resetPlatformForTests()
    vi.restoreAllMocks()
  })

  async function makeManager() {
    manager = new PtyManagerCtor()
    return manager
  }

  describe('shared size follows the backend (issue #914)', () => {
    function sizesSent(sessionId: string): Array<{ to: number | 'broadcast'; size: unknown }> {
      return host.sent
        .filter((message) => message.channel === IPC.ptySize(sessionId))
        .map((message) => ({ to: message.to, size: message.args[0] }))
    }

    it('tells each view the size the host reports, once, and re-corrects a view that re-fits', async () => {
      const shim = fakeSessionHostPty()
      backend.create.mockReturnValue(shim)
      const m = await makeManager()
      m.registerIpc()
      await host.handlers[IPC.ptyCreate](7, { cols: 80, rows: 24, persistKey: 'node-geo' })

      // Another viewer of the session is the active one: the pty runs at ITS size.
      shim.emitSize(100, 30)
      shim.emitSize(100, 30)
      expect(sizesSent('pty-1')).toEqual([{ to: 7, size: { cols: 100, rows: 30 } }])

      // The view re-fits to its own grid. That is only a vote now — no local min broadcast — and
      // the backend's answer (unchanged, the other viewer is still active) corrects it again.
      m.resize(7, 'pty-1', 90, 20)
      expect(shim.resize).toHaveBeenLastCalledWith(90, 20, false)
      expect(sizesSent('pty-1')).toHaveLength(1)
      shim.emitSize(100, 30)
      expect(sizesSent('pty-1')).toEqual([
        { to: 7, size: { cols: 100, rows: 30 } },
        { to: 7, size: { cols: 100, rows: 30 } }
      ])
    })

    it('re-sends the last answer when a view re-fits but the vote does not move', async () => {
      const shim = fakeSessionHostPty()
      backend.create.mockReturnValue(shim)
      const m = await makeManager()
      m.registerIpc()
      await host.handlers[IPC.ptyCreate](7, { cols: 80, rows: 24, persistKey: 'node-geo-2' })
      shim.emitSize(100, 30)
      const resizes = shim.resize.mock.calls.length
      // Same vote as the spawn size: nothing goes to the backend, so nothing would come back.
      m.resize(7, 'pty-1', 80, 24)
      expect(shim.resize.mock.calls.length).toBe(resizes)
      expect(sizesSent('pty-1').at(-1)).toEqual({ to: 7, size: { cols: 100, rows: 30 } })
      expect(sizesSent('pty-1')).toHaveLength(2)
    })

    it('makes a relay sink a ceiling unless it renders Resized, and forwards the answer to it', async () => {
      const bounded = fakeSessionHostPty()
      const adaptive = fakeSessionHostPty()
      backend.create.mockReturnValueOnce(bounded).mockReturnValueOnce(adaptive)
      const m = await makeManager()
      const phoneSizes: unknown[] = []
      const sid = m.createDetached(
        { cols: 80, rows: 24, persistKey: 'node-phone' },
        { onData: () => {}, onExit: () => {}, onSize: (size) => phoneSizes.push(size) }
      )
      m.resize(null, sid, 45, 40)
      expect(bounded.resize).toHaveBeenLastCalledWith(45, 40, true)
      bounded.emitSize(45, 30)
      bounded.emitSize(45, 30)
      expect(phoneSizes).toEqual([{ cols: 45, rows: 30 }])

      // Every report from the phone is answered, even when the answer has not changed: the phone
      // clears its "sized to another screen" hint on each resize it sends and needs the host to
      // restate the truth — here an unchanged vote, re-answered from the last backend size.
      m.resize(null, sid, 45, 40)
      expect(phoneSizes).toEqual([
        { cols: 45, rows: 30 },
        { cols: 45, rows: 30 }
      ])
      // A changed vote is answered by the backend, and forwarded even when it equals the report.
      m.resize(null, sid, 45, 38)
      bounded.emitSize(45, 38)
      expect(phoneSizes.at(-1)).toEqual({ cols: 45, rows: 38 })
      expect(phoneSizes).toHaveLength(3)

      const other = m.createDetached(
        { cols: 80, rows: 24, persistKey: 'node-phone-2' },
        { onData: () => {}, onExit: () => {}, adaptsToSize: true }
      )
      m.resize(null, other, 45, 40)
      expect(adaptive.resize).toHaveBeenLastCalledWith(45, 40, false)
    })
  })

  it('asks the session host whether a no-tmux persisted session exists', async () => {
    const m = await makeManager()
    backend.hasSession.mockResolvedValue(true)

    await expect(m.sessionExists('node-a')).resolves.toBe(true)
    expect(backend.hasSession).toHaveBeenCalledWith('nt-node-a')
  })

  it('treats an unprobeable session host as possibly warm instead of cold-restoring on a guess', async () => {
    const m = await makeManager()
    backend.hasSession.mockRejectedValue(new Error('host connection unavailable'))

    await expect(m.sessionExists('node-a')).resolves.toBe(true)
  })

  it('captures a relay snapshot from the session host when tmux is absent', async () => {
    const m = await makeManager()
    backend.capture.mockResolvedValue('painted screen')

    await expect(m.captureSnapshot('node-a')).resolves.toBe('painted screen')
    expect(backend.capture).toHaveBeenCalledWith('nt-node-a', false)
  })

  it('passes the platform-resolved local shell into a session-host spawn', async () => {
    const m = await makeManager()
    m.createDetached({ cols: 80, rows: 24, persistKey: 'node-shell' }, { onData: () => {}, onExit: () => {} })

    expect(backend.create).toHaveBeenCalledTimes(1)
    const spawn = backend.create.mock.calls[0][1] as {
      shell: string
      args: string[]
    }
    if (process.platform === 'win32') {
      expect(spawn.shell).not.toBe('bash')
      expect(spawn.shell.toLowerCase()).toMatch(/(?:pwsh|powershell|cmd)(?:\.exe)?$/)
    } else {
      expect(spawn.shell).toBe(process.env.SHELL || 'bash')
    }
    expect(spawn.args).toEqual([])
  })

  it('caps the session-host emulator at the renderer scrollback cap, not tmux history-limit', async () => {
    const { PtyManager } = await import('./pty-manager')
    for (const [tmuxScrollback, expected] of [
      [50000, 10000],
      [2000, 2000],
      [500, 1000]
    ] as const) {
      backend.create.mockClear()
      const m = new PtyManager({ runtimePlatform: 'win32' })
      ;(m as unknown as { getSettings: () => unknown }).getSettings = () => ({
        ...DEFAULT_SETTINGS,
        tmuxScrollback
      })
      m.createDetached(
        { cols: 80, rows: 24, persistKey: `node-sb-${tmuxScrollback}` },
        { onData: () => {}, onExit: () => {} }
      )
      expect(backend.create).toHaveBeenCalledTimes(1)
      expect(backend.create.mock.calls[0][2]).toBe(expected)
      await m.killAll()
    }
  })

  it('sends no launch dialect from a POSIX core, so its spawn request is unchanged', async () => {
    const { PtyManager } = await import('./pty-manager')
    for (const runtimePlatform of ['darwin', 'linux'] as const) {
      backend.create.mockClear()
      const m = new PtyManager({ runtimePlatform })
      ;(m as unknown as { getSettings: () => unknown }).getSettings = () => ({
        ...DEFAULT_SETTINGS,
        defaultShell: 'pwsh'
      })
      m.createDetached({ cols: 80, rows: 24, persistKey: `node-${runtimePlatform}` }, { onData: () => {}, onExit: () => {} })
      const spawn = backend.create.mock.calls[0][1] as Record<string, unknown>
      expect('launchDialect' in spawn).toBe(false)
      await m.killAll()
    }
  })

  const PS = 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'

  it('records the Windows-native dialect at spawn and keeps the HOST-reported one for execute-launch', async () => {
    const { PtyManager } = await import('./pty-manager')
    // The host answers with its own record of the generation's parser (a warm attach reports what
    // the shell WAS spawned as) — that, not the spawn request, is what the launch is encoded for.
    backend.create.mockImplementation(() =>
      fakeSessionHostPty(Promise.resolve({ fresh: true, launchDialect: 'cmd' }) as never)
    )
    const m = new PtyManager({ runtimePlatform: 'win32' })
    manager = m
    ;(m as unknown as { getSettings: () => unknown }).getSettings = () => ({
      ...DEFAULT_SETTINGS,
      defaultShell: 'C:\\Program Files\\PowerShell\\7\\pwsh.exe'
    })
    m.registerIpc()
    await host.handlers[IPC.ptyCreate](7, { cols: 80, rows: 24, persistKey: 'node-win', agentId: 'claude' })
    const spawn = backend.create.mock.calls[0][1] as { launchDialect?: string }
    expect(spawn.launchDialect).toBe('pwsh')

    const execute = vi.fn(async () => ({ status: 'executed' as const }))
    ;(m as unknown as { launchIntentDepsOverride: Record<string, unknown> }).launchIntentDepsOverride = {
      customAgents: () => [],
      sharedIdentityAvailable: async () => false,
      codexCaps: async () => ({ approvalValues: null, noDaemon: null }),
      exists: (c: string) => c === 'C:\\Tools\\claude.exe' || c === PS,
      systemRoot: 'C:\\Windows',
      execute
    }
    // The spawn PATH recorded here is this POSIX test host's; point it at a Windows directory.
    ;(m as unknown as { sessions: Map<string, { launchPath?: string }> }).sessions.forEach((s) => {
      s.launchPath = 'C:\\Tools'
    })
    const result = await host.handlers[IPC.ptyExecuteLaunch]('node-win', {
      launchId: '123e4567-e89b-42d3-a456-426614174000',
      intent: { kind: 'agent', action: 'start', agentId: 'claude', prompt: "it's" }
    })
    expect(result).toEqual({ ok: true })
    // Encoded for `cmd` (the host's word), not `pwsh` (the request): the ASCII-only wrapper line.
    const plan = (execute.mock.calls[0] as unknown[])[2] as { command: string }
    expect(plan.command.startsWith(`"${PS}" -NoLogo -NoProfile -EncodedCommand `)).toBe(true)
    expect(plan.command).not.toContain("it's")
  })

  it('fails a create closed, parks racing followers, and publishes only the recovered generation', async () => {
    let rejectReady!: (error: Error) => void
    const pendingReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectReady = reject
    })
    const failed = fakeSessionHostPty(pendingReady)
    const recovered = fakeSessionHostPty()
    backend.create.mockImplementationOnce(() => failed).mockImplementationOnce(() => recovered)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-retry' }

    const first = create(7, options) as Promise<unknown>
    const firstFailure = expect(first).rejects.toThrow('attach refused after connect')
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(1))
    // Both followers arrive while the failed shim is indexed. They must wait for `ready`, not join
    // the provisional generation and receive a plausible session id whose writes disappear.
    const followerA = create(8, options) as Promise<unknown>
    const followerB = create(9, options) as Promise<unknown>
    failed.emitData('queued before the attach failure')
    rejectReady(new Error('attach refused after connect'))

    await firstFailure
    expect(failed.resume).not.toHaveBeenCalled()
    expect(failed.destroy).toHaveBeenCalledTimes(1)

    const [a, b] = (await Promise.all([followerA, followerB])) as Array<{
      sessionId: string
      fresh: boolean
      persistent: boolean
    }>
    expect(a.sessionId).toBe('pty-2')
    expect(b.sessionId).toBe('pty-2')
    expect([a.fresh, b.fresh].sort()).toEqual([false, true])
    expect(a.persistent).toBe(true)
    expect(b.persistent).toBe(true)
    expect(backend.create).toHaveBeenCalledTimes(2)

    // Rollback cancels queued bytes, and late callbacks from the discarded generation are inert.
    failed.emitData('late bytes')
    failed.emitExit(1)
    await new Promise((resolve) => setTimeout(resolve, 20))
    expect(host.sent.some((m) => m.channel === IPC.ptyData('pty-1'))).toBe(false)
    expect(host.sent.some((m) => m.channel === IPC.ptyExit('pty-1'))).toBe(false)
  })

  it('does not resolve the create as persistent until the provisional attach succeeds', async () => {
    let resolveReady!: (info: { fresh: boolean; screen?: string }) => void
    const pendingReady = new Promise<{ fresh: boolean; screen?: string }>((resolve) => {
      resolveReady = resolve
    })
    backend.create.mockReturnValue(fakeSessionHostPty(pendingReady))
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    let settled = false

    const resultPromise = (create(7, {
      cols: 80,
      rows: 24,
      persistKey: 'node-pending'
    }) as Promise<unknown>).then((result) => {
      settled = true
      return result
    })
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(1))
    await Promise.resolve()
    expect(settled).toBe(false)

    resolveReady({ fresh: false, screen: 'still alive' })
    await expect(resultPromise).resolves.toMatchObject({
      sessionId: 'pty-1',
      fresh: false,
      persistent: true,
      screen: 'still alive'
    })
  })

  it('keeps a deletion tombstone when its owner recovery attach fails', async () => {
    let rejectReady!: (error: Error) => void
    const pendingReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectReady = reject
    })
    const failed = fakeSessionHostPty(pendingReady)
    backend.create.mockReturnValue(failed)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-protected' }

    // A confirmed delete leaves the owner able to recover, while other clients remain refused.
    await m.destroySession(7, 'node-protected')
    const ownerRecovery = create(7, options) as Promise<unknown>
    const recoveryFailure = expect(ownerRecovery).rejects.toThrow('recovery attach refused')
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(1))
    rejectReady(new Error('recovery attach refused'))
    await recoveryFailure

    await expect(create(8, options)).resolves.toEqual({
      sessionId: '',
      fresh: false,
      closed: { by: 7 }
    })
    expect(backend.create).toHaveBeenCalledTimes(1)
  })

  it('fences an exit-before-rejection generation until a retry confirms the destroy', async () => {
    const proc = fakeSessionHostPty()
    backend.create.mockReturnValue(proc)
    let rejectKill!: (error: Error) => void
    backend.kill.mockImplementationOnce(
      () =>
        new Promise<void>((_resolve, reject) => {
          rejectKill = reject
        })
    )
    const m = await makeManager()
    m.registerIpc()
    const ended = vi.fn()
    m.onSessionEnded(ended)
    const create = host.handlers[IPC.ptyCreate]
    const destroy = host.handlers[IPC.ptyDestroy]
    const options = { cols: 80, rows: 24, persistKey: 'node-kill-ack' }

    const first = (await create(7, options)) as { sessionId: string; fresh: boolean }
    const second = (await create(8, options)) as { sessionId: string; fresh: boolean }
    expect(second).toMatchObject({ sessionId: first.sessionId, fresh: false })

    const pendingDestroy = destroy(7, 'node-kill-ack') as Promise<void>
    const rejectedDestroy = expect(pendingDestroy).rejects.toThrow('kill acknowledgement lost')
    await vi.waitFor(() => expect(backend.kill).toHaveBeenCalledTimes(1))

    // A create arriving while the host result is unknown waits behind the end barrier. It must
    // neither join a session that may be dying nor spawn a replacement before the outcome lands.
    let followerSettled = false
    const follower = (create(9, options) as Promise<unknown>).finally(() => {
      followerSettled = true
    })
    const followerFailure = expect(follower).rejects.toThrow(
      'session end outcome unknown; retry the close before reopening this node'
    )
    await Promise.resolve()
    expect(followerSettled).toBe(false)
    expect(backend.create).toHaveBeenCalledTimes(1)

    // The host may have acted and emitted exit before its correlated reply is lost. Exit is not a
    // kill acknowledgement: allowing the waiting create to spawn here resurrects an unknown delete.
    proc.emitExit(0)
    rejectKill(new Error('kill acknowledgement lost'))
    await rejectedDestroy
    await followerFailure

    // Nothing local claimed a confirmed close, and no replacement generation was spawned. The
    // exact same idempotent destroy remains available to establish absence.
    expect(backend.create).toHaveBeenCalledTimes(1)
    expect(proc.destroy).not.toHaveBeenCalled()
    expect(host.sent.some((message) => message.channel === IPC.ptyClosed(first.sessionId))).toBe(false)
    expect(ended).not.toHaveBeenCalled()

    backend.kill.mockResolvedValueOnce(undefined)
    await expect(destroy(7, 'node-kill-ack')).resolves.toBeUndefined()
    expect(backend.kill).toHaveBeenCalledTimes(2)
    expect(ended).toHaveBeenCalledWith('node-kill-ack')
    await expect(create(9, options)).resolves.toEqual({
      sessionId: '',
      fresh: false,
      closed: { by: 7 }
    })
  })

  it('contains a failed legacy destroy cast without local teardown or an unhandled rejection', async () => {
    const proc = fakeSessionHostPty()
    backend.create.mockReturnValue(proc)
    backend.kill.mockRejectedValueOnce(new Error('legacy reply path unavailable'))
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const m = await makeManager()
    m.registerIpc()
    const ended = vi.fn()
    m.onSessionEnded(ended)
    const created = (await host.handlers[IPC.ptyCreate](7, {
      cols: 80,
      rows: 24,
      persistKey: 'legacy-node'
    })) as { sessionId: string }

    host.senderListeners[IPC.ptyDestroy](7, 'legacy-node')
    await vi.waitFor(() => expect(backend.kill).toHaveBeenCalledTimes(1))
    await vi.waitFor(() => expect(warn).toHaveBeenCalled())

    expect(proc.destroy).not.toHaveBeenCalled()
    expect(ended).not.toHaveBeenCalled()
    expect(host.sent.some((message) => message.channel === IPC.ptyClosed(created.sessionId))).toBe(false)
  })

  it('rejects recycle before changing local generation state when the host kill fails', async () => {
    const proc = fakeSessionHostPty()
    backend.create.mockReturnValue(proc)
    backend.kill.mockRejectedValueOnce(new Error('recycle outcome unknown'))
    const m = await makeManager()
    m.registerIpc()
    const ended = vi.fn()
    m.onSessionEnded(ended)
    const created = (await host.handlers[IPC.ptyCreate](7, {
      cols: 80,
      rows: 24,
      persistKey: 'recycle-node'
    })) as { sessionId: string }

    await expect(host.handlers[IPC.ptyRecycle](7, 'recycle-node')).rejects.toThrow(
      'recycle outcome unknown'
    )
    expect(proc.destroy).not.toHaveBeenCalled()
    expect(ended).not.toHaveBeenCalled()
    expect(host.sent.some((message) => message.channel === IPC.ptyRecycled(created.sessionId))).toBe(false)
  })

  it('kills a live host-owned session even if tmux becomes available later', async () => {
    const proc = fakeSessionHostPty()
    backend.create.mockReturnValue(proc)
    const m = await makeManager()
    m.registerIpc()
    await host.handlers[IPC.ptyCreate](7, {
      cols: 80,
      rows: 24,
      persistKey: 'host-before-tmux'
    })
    ;(m as unknown as { tmuxPath: string }).tmuxPath = 'missing-test-tmux'

    await expect(host.handlers[IPC.ptyDestroy](7, 'host-before-tmux')).resolves.toBeUndefined()
    expect(backend.kill).toHaveBeenCalledWith('nt-host-before-tmux')
    expect(proc.destroy).toHaveBeenCalledTimes(1)
  })

  it('does not route an unheld tmux-session delete through the session host', async () => {
    const m = await makeManager()
    ;(m as unknown as { tmuxPath: string }).tmuxPath = 'missing-test-tmux'

    await expect(m.destroySession(7, 'tmux-orphan')).resolves.toBeUndefined()
    expect(backend.kill).not.toHaveBeenCalled()
  })

  it('does not publish a session that exits in the same turn its ready resolves', async () => {
    let resolveReady!: (info: { fresh: boolean }) => void
    const pendingReady = new Promise<{ fresh: boolean }>((resolve) => {
      resolveReady = resolve
    })
    const exited = fakeSessionHostPty(pendingReady)
    backend.create.mockReturnValue(exited)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]

    const result = create(7, {
      cols: 80,
      rows: 24,
      persistKey: 'node-exited-during-attach'
    }) as Promise<unknown>
    // This suite mocks './session-host-backend', so the create path exercised here is
    // pty-manager.ts's own ready-vs-exit race (the message below is its literal text, line
    // ~1998) — not session-host-client.ts's SessionHostPty class, which is a different,
    // unmocked implementation this harness never reaches. Matches the sibling test "rejects a
    // create whose provisional generation exits before ready resolves" below.
    const failure = expect(result).rejects.toThrow('exited before it became ready')
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(1))
    resolveReady({ fresh: true })
    exited.emitExit(0)

    await failure
  })

  it('retires a detached session-host shim and signals its sink when ready rejects', async () => {
    let rejectReady!: (error: Error) => void
    const pendingReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectReady = reject
    })
    const failed = fakeSessionHostPty(pendingReady)
    backend.create.mockReturnValue(failed)
    const m = await makeManager()
    const onData = vi.fn()
    const onExit = vi.fn()

    expect(
      m.createDetached(
        { cols: 80, rows: 24, persistKey: 'relay-node' },
        { onData, onExit }
      )
    ).toBe('pty-1')
    rejectReady(new Error('relay attach failed'))
    await vi.waitFor(() => expect(failed.destroy).toHaveBeenCalledTimes(1))

    expect(onExit).toHaveBeenCalledWith(1)
    failed.emitData('late relay bytes')
    failed.emitExit(9)
    expect(onData).not.toHaveBeenCalled()
    expect(onExit).toHaveBeenCalledTimes(1)
  })

  it('treats confirmed absence as recovered while invalid, uncertain, and rate-limited requests reject', async () => {
    const m = await makeManager()
    backend.supported.mockReturnValue(true)

    await expect(m.recycleSessionFromClient(7, '')).rejects.toThrow('invalid node id')
    expect(backend.kill).not.toHaveBeenCalled()

    backend.hasSession.mockResolvedValue(false)
    await expect(m.recycleSessionFromClient(7, 'node-missing')).resolves.toBeUndefined()
    expect(backend.kill).toHaveBeenCalledWith('nt-node-missing', {
      reserveReplacement: true,
      requireV2: true,
      expectedAbsent: true
    })
    backend.kill.mockClear()

    backend.hasSession.mockRejectedValueOnce(new Error('host probe unavailable'))
    await expect(m.recycleSessionFromClient(7, 'node-uncertain')).rejects.toThrow(
      'Could not confirm the terminal session'
    )
    expect(backend.kill).not.toHaveBeenCalled()

    const { PTY_END_BUDGET } = await import('./pty-manager')
    backend.hasSession.mockResolvedValue(true)
    vi.useFakeTimers()
    vi.setSystemTime(new Date('2026-08-16T00:00:00Z'))
    try {
      for (let i = 0; i < PTY_END_BUDGET.burst; i += 1)
        await m.recycleSessionFromClient(8, 'node-budget')
      await expect(m.recycleSessionFromClient(8, 'node-budget')).rejects.toThrow(
        'Too many terminal restart requests'
      )
      expect(backend.kill).toHaveBeenCalledTimes(PTY_END_BUDGET.burst)
    } finally {
      vi.useRealTimers()
    }
  })

  it('binds an honestly absent host reservation to expected absence', async () => {
    const m = await makeManager()
    backend.hasSession.mockResolvedValueOnce(false).mockResolvedValue(true)
    backend.kill.mockImplementationOnce(async (_name, options) => {
      expect(options).toEqual({
        reserveReplacement: true,
        requireV2: true,
        expectedAbsent: true
      })
      throw new Error('another client created the name before reservation')
    })

    await expect(m.recycleSessionFromClient(7, 'node-absence-race')).rejects.toThrow(
      'another client created the name before reservation'
    )
    expect(backend.kill).toHaveBeenCalledTimes(1)
  })

  it('requires protocol v2 for a confirmed host teardown even when the replacement is direct', async () => {
    const active = fakeSessionHostPty()
    backend.create.mockReturnValue(active)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-v1-direct-target' }
    await create(7, options)
    m.init(() => ({
      tmuxEnabled: false
    }) as never)
    backend.hasSession.mockResolvedValue(true)
    const { SessionHostProtocolCompatibilityError } = await import('./session-host-backend')
    backend.kill.mockImplementationOnce(async (_name, killOptions) => {
      if (killOptions?.requireV2)
        throw new SessionHostProtocolCompatibilityError('restart this terminal')
      active.emitExit(0)
    })

    await expect(m.recycleSessionFromClient(7, options.persistKey)).rejects.toBeInstanceOf(
      SessionHostProtocolCompatibilityError
    )
    expect(backend.kill).toHaveBeenCalledWith('nt-node-v1-direct-target', {
      reserveReplacement: false,
      requireV2: true
    })
    await expect(create(8, options)).resolves.toMatchObject({ sessionId: 'pty-1', fresh: false })
    expect(backend.create).toHaveBeenCalledTimes(1)
  })

  it('never tells a session-host joiner to enter the alternate screen (its scrollback is its history)', async () => {
    backend.create.mockReturnValue(fakeSessionHostPty())
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-alt-screen' }

    const spawned = (await create(7, options)) as { tmuxClient?: boolean }
    // Not a tmux client either, so a resync repaint re-applies no alt screen / tmux mouse.
    expect(spawned.tmuxClient).toBeUndefined()
    const joined = (await create(8, options)) as {
      fresh: boolean
      coAttachAltScreen?: boolean
      tmuxClient?: boolean
    }
    expect(joined.fresh).toBe(false) // it did join the live session…
    expect(joined.coAttachAltScreen).toBeUndefined() // …but there is no tmux alt screen to restore
    expect(joined.tmuxClient).toBeUndefined()
  })

  it('never tells a session-host joiner to enable tmux mouse tracking (no tmux runs `mouse on` there)', async () => {
    // Was gated on `persistKey`, which a session-host session carries: the joiner (card modal,
    // reloaded node, teammate) entered ?1000/?1002/?1006 tracking with no tmux behind it, so the
    // wheel and drags went to the shell as SGR reports instead of scrolling and selecting.
    backend.create.mockReturnValue(fakeSessionHostPty())
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-mouse' }

    await create(7, options)
    const joined = (await create(8, options)) as {
      fresh: boolean
      persistent?: boolean
      coAttachMouse?: boolean
      coAttachAltScreen?: boolean
      tmuxClient?: boolean
    }
    expect(joined.fresh).toBe(false)
    expect(joined.persistent).toBe(true) // still a session that outlives its clients…
    expect(joined.coAttachMouse).toBeUndefined() // …but with no tmux mouse to turn on
    expect(joined.coAttachAltScreen).toBeUndefined()
    expect(joined.tmuxClient).toBeUndefined()
  })

  it('leaves the live generation joinable when the confirmed backend kill rejects', async () => {
    const active = fakeSessionHostPty()
    backend.create.mockReturnValue(active)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-kill-reject' }

    await expect(create(7, options)).resolves.toMatchObject({
      sessionId: 'pty-1',
      persistent: true
    })
    backend.kill.mockImplementationOnce(async () => {
      throw new Error('kill acknowledgement lost')
    })
    backend.hasSession.mockResolvedValue(true)

    await expect(m.recycleSessionFromClient(7, options.persistKey)).rejects.toThrow(
      'kill acknowledgement lost'
    )
    expect(active.resume).not.toHaveBeenCalled()
    expect(active.kill).not.toHaveBeenCalled()
    expect(active.destroy).not.toHaveBeenCalled()

    // The original index and subscriber ledger remain intact: another client joins the same
    // generation, and no replacement host attach is attempted.
    await expect(create(8, options)).resolves.toMatchObject({
      sessionId: 'pty-1',
      fresh: false,
      persistent: true
    })
    expect(backend.create).toHaveBeenCalledTimes(1)
  })

  it('commits an exact early exit when the host response is lost and preserves the replacement lease', async () => {
    const active = fakeSessionHostPty()
    const replacement = fakeSessionHostPty()
    backend.create.mockImplementationOnce(() => active).mockImplementationOnce(() => replacement)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-exit-then-reject' }

    await create(7, options)
    backend.kill.mockImplementationOnce(async () => {
      // This is the real host order: exit broadcast first, then a response that may be lost.
      active.emitExit(23)
      throw new Error('kill response lost after exit')
    })

    await expect(m.recycleSessionFromClient(7, options.persistKey)).resolves.toBeUndefined()
    expect(backend.kill).toHaveBeenNthCalledWith(2, 'nt-node-exit-then-reject', {
      reserveReplacement: true,
      requireV2: true
    })
    expect(
      host.sent.some(
        (message) =>
          message.channel === IPC.ptyExit('pty-1') && message.args[0] === 23
      )
    ).toBe(false)
    expect(host.sent.some((message) => message.channel === IPC.ptyRecycled('pty-1'))).toBe(false)

    // The committed transaction reserved replacement creation for its primary owner. Its create
    // establishes the fresh generation; no ordinary exit/rejected-switch path intervenes.
    await expect(create(7, options)).resolves.toMatchObject({ sessionId: 'pty-2', fresh: true })
    expect(backend.create).toHaveBeenCalledTimes(2)
  })

  it('does not retain a replacement lease for generic node deletion', async () => {
    const active = fakeSessionHostPty()
    backend.create.mockReturnValue(active)
    const m = await makeManager()
    m.registerIpc()
    const options = { cols: 80, rows: 24, persistKey: 'node-generic-delete' }
    await host.handlers[IPC.ptyCreate](7, options)
    backend.kill.mockClear()

    await m.destroySession(7, options.persistKey)

    expect(backend.kill).toHaveBeenCalledTimes(1)
    expect(backend.kill.mock.calls[0]).toEqual(['nt-node-generic-delete'])
  })

  it('waits for backend kill acknowledgement before cleaning the confirmed generation', async () => {
    const order: string[] = []
    const active = fakeSessionHostPty()
    const replacement = fakeSessionHostPty()
    active.resume.mockImplementation(() => order.push('cleanup-resume'))
    active.destroy.mockImplementation(() => order.push('cleanup-destroy'))
    backend.create.mockImplementationOnce(() => active).mockImplementationOnce(() => replacement)
    backend.kill.mockImplementationOnce(async () => {
      order.push('host-exit')
      active.emitExit(0)
      order.push('kill-ack')
    })
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-kill-order' }

    await create(7, options)
    await create(8, options)
    await m.recycleSessionFromClient(7, options.persistKey)

    expect(order).toEqual(['host-exit', 'kill-ack', 'cleanup-resume', 'cleanup-destroy'])
    expect(host.sent.some((message) => message.channel === IPC.ptyExit('pty-1'))).toBe(false)

    // The co-viewer's subscriber ledger survived until the acknowledged cleanup, so registering
    // the replacement releases it through the recycle event rather than losing it to early exit.
    await create(7, options)
    expect(
      host.sent.some((message) => message.channel === IPC.ptyRecycled('pty-1'))
    ).toBe(true)
  })

  it('rejects a create whose provisional generation exits before ready resolves', async () => {
    let resolveReady!: (info: { fresh: boolean }) => void
    const pendingReady = new Promise<{ fresh: boolean }>((resolve) => {
      resolveReady = resolve
    })
    const exited = fakeSessionHostPty(pendingReady)
    const replacement = fakeSessionHostPty()
    backend.create.mockImplementationOnce(() => exited).mockImplementationOnce(() => replacement)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-exit-before-ready' }

    const first = create(7, options) as Promise<unknown>
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(1))
    exited.emitExit(17)
    resolveReady({ fresh: true })

    await expect(first).rejects.toThrow('exited before it became ready')
    expect(
      host.sent.some(
        (message) => message.channel === IPC.ptyExit('pty-1') && message.args[0] === 17
      )
    ).toBe(true)
    await expect(create(8, options)).resolves.toMatchObject({ sessionId: 'pty-2', fresh: true })
  })

  it('retains a deletion tombstone when the owner recovery attach rejects', async () => {
    const original = fakeSessionHostPty()
    let rejectRecovery!: (error: Error) => void
    const recoveryReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectRecovery = reject
    })
    const failedRecovery = fakeSessionHostPty(recoveryReady)
    const forbiddenFollower = fakeSessionHostPty()
    backend.create
      .mockImplementationOnce(() => original)
      .mockImplementationOnce(() => failedRecovery)
      .mockImplementationOnce(() => forbiddenFollower)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-deleted-recovery' }

    await create(7, options)
    await m.destroySession(7, options.persistKey)
    const ownerRecovery = create(7, options) as Promise<unknown>
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(2))
    const follower = create(8, options) as Promise<unknown>
    rejectRecovery(new Error('recovery attach refused'))

    await expect(ownerRecovery).rejects.toThrow('recovery attach refused')
    await expect(follower).resolves.toMatchObject({
      sessionId: '',
      fresh: false,
      closed: { by: 7 }
    })
    expect(backend.create).toHaveBeenCalledTimes(2)
  })

  it('retires only the exact generation when reconnect replay is rejected', async () => {
    const original = fakeSessionHostPty()
    const replacement = fakeSessionHostPty()
    backend.create.mockImplementationOnce(() => original).mockImplementationOnce(() => replacement)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-replay-reject' }

    await create(7, options)
    original.emitAttachError(new Error("no existing session 'nt-node-replay-reject'"))
    expect(
      host.sent.some(
        (message) => message.channel === IPC.ptyExit('pty-1') && message.args[0] === 1
      )
    ).toBe(true)
    await expect(create(7, options)).resolves.toMatchObject({ sessionId: 'pty-2', fresh: true })

    // A delayed duplicate callback from the retired shim cannot forget the replacement.
    original.emitAttachError(new Error('late replay failure'))
    await expect(create(8, options)).resolves.toMatchObject({ sessionId: 'pty-2', fresh: false })
    expect(backend.create).toHaveBeenCalledTimes(2)
  })

  it('reserves a recycled replacement for its owner and releases parked co-viewers on failure', async () => {
    const original = fakeSessionHostPty()
    let rejectReplacement!: (error: Error) => void
    const replacementReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectReplacement = reject
    })
    const failedReplacement = fakeSessionHostPty(replacementReady)
    backend.create
      .mockImplementationOnce(() => original)
      .mockImplementationOnce(() => failedReplacement)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-owner-reservation' }

    await create(7, options)
    await create(8, options)
    await m.recycleSessionFromClient(7, options.persistKey)
    const parkedFollower = create(8, options) as Promise<unknown>
    const ownerReplacement = create(7, options) as Promise<unknown>
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(2))
    rejectReplacement(new Error('selected replacement failed'))

    await expect(ownerReplacement).rejects.toThrow('selected replacement failed')
    await expect(parkedFollower).rejects.toThrow('replacement terminal did not become ready')
    expect(backend.create).toHaveBeenCalledTimes(2)
    expect(
      host.sent.some(
        (message) =>
          message.to === 8 &&
          message.channel === IPC.ptyRecycled('pty-1') &&
          (message.args[0] as { ready: boolean }).ready === false
      )
    ).toBe(true)
  })

  it('reserves a solo session replacement from an inactive co-viewer', async () => {
    const original = fakeSessionHostPty()
    let rejectReplacement!: (error: Error) => void
    const replacementReady = new Promise<{ fresh: boolean }>((_, reject) => {
      rejectReplacement = reject
    })
    backend.create
      .mockImplementationOnce(() => original)
      .mockImplementationOnce(() => fakeSessionHostPty(replacementReady))
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-solo-reservation' }
    await create(7, options)
    await m.recycleSessionFromClient(7, options.persistKey)

    const inactiveViewer = create(9, options) as Promise<unknown>
    const owner = create(7, options) as Promise<unknown>
    await vi.waitFor(() => expect(backend.create).toHaveBeenCalledTimes(2))
    rejectReplacement(new Error('owner replacement rejected'))

    await expect(owner).rejects.toThrow('owner replacement rejected')
    await expect(inactiveViewer).rejects.toThrow('replacement terminal did not become ready')
    expect(backend.create).toHaveBeenCalledTimes(2)
  })

  it('parks a same-client modal behind the primary replacement owner', async () => {
    const original = fakeSessionHostPty()
    const replacement = fakeSessionHostPty()
    backend.create.mockImplementationOnce(() => original).mockImplementationOnce(() => replacement)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-primary-view-owner' }

    await create(7, options)
    await m.recycleSessionFromClient(7, options.persistKey)

    let modalSettled = false
    const modal = (create(7, { ...options, viewerId: 'kanban-modal' }) as Promise<unknown>).then(
      (result) => {
        modalSettled = true
        return result
      }
    )
    await Promise.resolve()
    expect(modalSettled).toBe(false)
    expect(backend.create).toHaveBeenCalledTimes(1)

    await expect(create(7, options)).resolves.toMatchObject({ sessionId: 'pty-2', fresh: true })
    await expect(modal).resolves.toMatchObject({ sessionId: 'pty-2', fresh: false })
    expect(backend.create).toHaveBeenCalledTimes(2)
  })

  it('reserves an honestly absent session until the owner establishes its replacement', async () => {
    backend.hasSession.mockResolvedValue(false)
    backend.create.mockReturnValue(fakeSessionHostPty())
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-absent-reservation' }

    await expect(m.recycleSessionFromClient(7, options.persistKey)).resolves.toBeUndefined()
    const inactiveViewer = create(9, options) as Promise<unknown>
    const owner = create(7, options) as Promise<unknown>

    await expect(owner).resolves.toMatchObject({ sessionId: 'pty-1', fresh: true })
    await expect(inactiveViewer).resolves.toMatchObject({ sessionId: 'pty-1', fresh: false })
    expect(backend.create).toHaveBeenCalledTimes(1)
  })

  it('rejects a duplicate confirmed recycle while the first kill is in flight', async () => {
    let acknowledgeKill!: () => void
    const killPending = new Promise<void>((resolve) => {
      acknowledgeKill = resolve
    })
    backend.kill.mockReturnValue(killPending)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-double-recycle' }
    await create(7, options)

    const first = m.recycleSessionFromClient(7, options.persistKey)
    await vi.waitFor(() => expect(backend.kill).toHaveBeenCalledTimes(1))
    await expect(m.recycleSessionFromClient(7, options.persistKey)).rejects.toThrow(
      'already restarting'
    )
    acknowledgeKill()
    await expect(first).resolves.toBeUndefined()
    expect(backend.kill).toHaveBeenCalledTimes(1)
  })

  it('rejects parked create waiters when the manager shuts down', async () => {
    const original = fakeSessionHostPty()
    backend.create.mockReturnValue(original)
    const m = await makeManager()
    m.registerIpc()
    const create = host.handlers[IPC.ptyCreate]
    const options = { cols: 80, rows: 24, persistKey: 'node-shutdown-waiter' }
    await create(7, options)
    await create(8, options)
    await m.recycleSessionFromClient(7, options.persistKey)
    const parked = create(8, options) as Promise<unknown>

    await m.killAll()
    await expect(parked).rejects.toThrow('shut down before the replacement became ready')
  })
})

describe('resolveLocalSessionShell', () => {
  it('uses the Windows resolver when both explicit and configured shells are empty', async () => {
    const { resolveLocalSessionShell } = await import('./pty-manager')
    const windowsShell = vi.fn(() => String.raw`C:\Windows\System32\cmd.exe`)

    expect(
      resolveLocalSessionShell(undefined, '', {
        platform: 'win32',
        windowsShell,
        posixShell: '/bin/should-not-win'
      })
    ).toBe(String.raw`C:\Windows\System32\cmd.exe`)
    expect(windowsShell).toHaveBeenCalledTimes(1)
  })

  it('keeps an explicit program above a configured shell and every platform fallback', async () => {
    const { resolveLocalSessionShell } = await import('./pty-manager')
    const windowsShell = vi.fn(() => 'cmd.exe')

    expect(
      resolveLocalSessionShell('/opt/custom-shell', '/bin/configured', {
        platform: 'win32',
        windowsShell
      })
    ).toBe('/opt/custom-shell')
    expect(windowsShell).not.toHaveBeenCalled()
  })

  it('keeps a configured compatibility shell above platform fallback', async () => {
    const { resolveLocalSessionShell } = await import('./pty-manager')
    const windowsShell = vi.fn(() => 'cmd.exe')

    expect(
      resolveLocalSessionShell(undefined, String.raw`C:\Tools\My Shell\shell.exe`, {
        platform: 'win32',
        windowsShell
      })
    ).toBe(String.raw`C:\Tools\My Shell\shell.exe`)
    expect(windowsShell).not.toHaveBeenCalled()
  })

  it('uses the POSIX shell, then bash, outside Windows', async () => {
    const { resolveLocalSessionShell } = await import('./pty-manager')

    expect(
      resolveLocalSessionShell(undefined, '', { platform: 'linux', posixShell: '/bin/zsh' })
    ).toBe('/bin/zsh')
    expect(resolveLocalSessionShell(undefined, '', { platform: 'linux', posixShell: '' })).toBe(
      'bash'
    )
  })
})