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.

46.9 KB
Raw Blame
import fs from 'fs'
import net from 'net'
import os from 'os'
import path from 'path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { sessionHostPaths } from '../session-host/paths'
import {
  SESSION_HOST_PROTOCOL_VERSION,
  LineFramer,
  encodeFrame,
  type SessionHostRequest,
  type SessionHostSpawnOptions
} from '../session-host/protocol'
import { SessionHostClient } from './session-host-client'
import { SessionHostPty } from './session-host-pty'

const openServers = new Set<net.Server>()
const openSockets = new Set<net.Socket>()
const tempDirs = new Set<string>()
const livePtys = new Set<SessionHostPty>()

interface Deferred<T> {
  promise: Promise<T>
  resolve(value: T): void
  reject(error: unknown): void
}

function deferred<T>(): Deferred<T> {
  let resolve!: (value: T) => void
  let reject!: (error: unknown) => void
  const promise = new Promise<T>((res, rej) => {
    resolve = res
    reject = rej
  })
  return { promise, resolve, reject }
}

function within<T>(promise: Promise<T>, label: string, ms = 2_500): Promise<T> {
  return new Promise<T>((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error(`${label} did not finish within ${ms}ms`)), ms)
    promise.then(
      (value) => {
        clearTimeout(timer)
        resolve(value)
      },
      (error) => {
        clearTimeout(timer)
        reject(error)
      }
    )
  })
}

function eventLoopTurn(): Promise<void> {
  return new Promise((resolve) => setImmediate(resolve))
}

function fixture(prefix: string): { userDataDir: string; endpoint: string } {
  const userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix))
  tempDirs.add(userDataDir)
  const paths = sessionHostPaths(userDataDir)
  fs.writeFileSync(paths.tokenPath, 'a'.repeat(64))
  fs.writeFileSync(
    paths.statePath,
    JSON.stringify({
      pid: process.pid,
      endpoint: paths.endpoint,
      tokenPath: paths.tokenPath,
      startedAt: Date.now(),
      // These fixtures must model a CURRENT host: the flows here create terminals, and creation is
      // a v2-only operation the client rightly refuses against a legacy host. So the published
      // version, the advertised hello version and the per-attach `generation` all have to agree —
      // a fake host that publishes 2 while answering like a v1 host is inconsistent, not legacy.
      protocolVersion: SESSION_HOST_PROTOCOL_VERSION
    })
  )
  return { userDataDir, endpoint: paths.endpoint }
}

function spawnOptions(
  userDataDir: string,
  cols: number,
  rows: number,
  args: string[] = []
): SessionHostSpawnOptions {
  return {
    cwd: userDataDir,
    shell: process.execPath,
    args,
    env: {},
    cols,
    rows
  }
}

function trackSocket(socket: net.Socket): void {
  openSockets.add(socket)
  socket.once('close', () => openSockets.delete(socket))
}

function sessionPty(
  client: SessionHostClient,
  name: string,
  spawn: SessionHostSpawnOptions,
  scrollback: number
): SessionHostPty {
  const pty = new SessionHostPty(client, name, spawn, scrollback)
  livePtys.add(pty)
  return pty
}

async function listen(server: net.Server, endpoint: string): Promise<void> {
  openServers.add(server)
  await new Promise<void>((resolve, reject) => {
    server.once('error', reject)
    server.listen(endpoint, resolve)
  })
}

afterEach(async () => {
  for (const pty of livePtys) pty.destroy()
  livePtys.clear()
  // Let synchronous unsubscribe bookkeeping cancel every idle reconnect timer before its socket
  // is torn down by the harness. A failed assertion must not leak a client into the next Chut.
  await eventLoopTurn()
  for (const socket of openSockets) socket.destroy()
  openSockets.clear()
  await Promise.all(
    [...openServers].map(
      (server) =>
        new Promise<void>((resolve) => {
          if (!server.listening) {
            resolve()
            return
          }
          server.close(() => resolve())
        })
    )
  )
  openServers.clear()
  for (const dir of tempDirs) {
    const endpoint = sessionHostPaths(dir).endpoint
    if (process.platform !== 'win32') fs.rmSync(endpoint, { force: true })
    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 })
  }
  tempDirs.clear()
})

describe('SessionHostClient subscriber flow and reconnect barriers', () => {
  it('holds one host pause ticket until the last exact local owner resumes or unsubscribes', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-owner-')
    const flowCommands: Array<'pause' | 'resume' | 'detach'> = []
    const firstPause = deferred<void>()
    const firstResume = deferred<void>()
    const secondPause = deferred<void>()
    const secondResume = deferred<void>()
    const detached = deferred<void>()
    const ownerBoundaryResize = deferred<void>()
    const unsubscribeBoundaryResize = deferred<void>()
    let pauseCount = 0
    let resumeCount = 0

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            // The second local subscriber co-attaches to the same already-live generation, so the
            // client sends `attachExisting` (warm, no spawn plan) rather than a second `attach`.
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false, generation: 'flow-generation' } }))
          } else if (request.cmd === 'pause') {
            flowCommands.push('pause')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            pauseCount++
            if (pauseCount === 1) firstPause.resolve()
            if (pauseCount === 2) secondPause.resolve()
          } else if (request.cmd === 'resume') {
            flowCommands.push('resume')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            resumeCount++
            if (resumeCount === 1) firstResume.resolve()
            if (resumeCount === 2) secondResume.resolve()
          } else if (request.cmd === 'detach') {
            flowCommands.push('detach')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            detached.resolve()
          } else if (request.cmd === 'resize') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
            if (request.cols === 79 && request.rows === 23) ownerBoundaryResize.resolve()
            if (request.cols === 78 && request.rows === 22) unsubscribeBoundaryResize.resolve()
          } else if (request.cmd === 'write') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const first = sessionPty(client, 'nt-flow-owner', spawnOptions(userDataDir, 120, 40), 500)
    const second = sessionPty(client, 'nt-flow-owner', spawnOptions(userDataDir, 80, 24), 500)
    await expect(within(Promise.all([first.ready, second.ready]), 'both local attaches')).resolves.toHaveLength(2)

    first.pause()
    await within(firstPause.promise, 'first aggregate pause')
    second.pause()
    first.resume()
    first.resize(79, 23)
    await within(ownerBoundaryResize.promise, 'co-owner flow boundary')
    expect(flowCommands).toEqual(['pause'])
    second.resume()
    await within(firstResume.promise, 'last-owner resume')

    first.pause()
    await within(secondPause.promise, 'second aggregate pause')
    second.destroy()
    first.resize(78, 22)
    await within(unsubscribeBoundaryResize.promise, 'surviving-owner flow boundary')
    expect(flowCommands).toEqual(['pause', 'resume', 'pause'])
    first.destroy()
    await within(secondResume.promise, 'unsubscribe-owned resume')
    await within(detached.promise, 'last-subscriber detach')
    await eventLoopTurn()

    expect(flowCommands).toEqual(['pause', 'resume', 'pause', 'resume', 'detach'])
  })

  it('returns a pause acknowledged during last-subscriber teardown before detaching', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-retiring-pause-')
    const pauseReachedHost = deferred<void>()
    const resumed = deferred<void>()
    const detached = deferred<void>()
    const flowCommands: Array<'pause' | 'resume' | 'detach'> = []

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            // The second local subscriber co-attaches to the same already-live generation, so the
            // client sends `attachExisting` (warm, no spawn plan) rather than a second `attach`.
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false, generation: 'flow-generation' } }))
          } else if (request.cmd === 'pause') {
            flowCommands.push('pause')
            // Resolve in this same server callback after writing the acknowledgement. The test's
            // continuation removes the owners before the client socket can consume that frame.
            socket.write(encodeFrame({ id: request.id, ok: true }))
            pauseReachedHost.resolve()
          } else if (request.cmd === 'resume') {
            flowCommands.push('resume')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            resumed.resolve()
          } else if (request.cmd === 'detach') {
            flowCommands.push('detach')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            detached.resolve()
          } else if (request.cmd === 'resize' || request.cmd === 'write') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const first = sessionPty(
      client,
      'nt-retiring-pause',
      spawnOptions(userDataDir, 100, 32),
      500
    )
    const second = sessionPty(
      client,
      'nt-retiring-pause',
      spawnOptions(userDataDir, 80, 24),
      500
    )
    await within(Promise.all([first.ready, second.ready]), 'retiring-pause co-attach')

    first.pause()
    await within(pauseReachedHost.promise, 'in-flight pause acknowledgement')
    first.destroy()
    second.destroy()
    await within(resumed.promise, 'retiring pause resume')
    await within(detached.promise, 'retiring pause detach')
    await eventLoopTurn()
    expect(flowCommands).toEqual(['pause', 'resume', 'detach'])
  })

  it('returns the surviving pause ticket and detaches when a delayed co-attach rejects after its neighbor leaves', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-rejected-neighbor-')
    const pauseReachedHost = deferred<void>()
    const rejectedAttach = deferred<{ socket: net.Socket; id: number }>()
    const resumed = deferred<void>()
    const detached = deferred<void>()
    const commands: string[] = []

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            // The owner is the only fresh create for this name; the neighbor co-attaches to the
            // already-live generation and therefore sends `attachExisting` instead (below).
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            commands.push('attach:rejected-neighbor')
            rejectedAttach.resolve({ socket, id: request.id })
          } else if (request.cmd === 'pause') {
            commands.push('pause')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            pauseReachedHost.resolve()
          } else if (request.cmd === 'resume') {
            commands.push('resume')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            resumed.resolve()
          } else if (request.cmd === 'detach') {
            commands.push('detach')
            socket.write(encodeFrame({ id: request.id, ok: true }))
            detached.resolve()
          } else if (request.cmd === 'resize' || request.cmd === 'write') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const owner = sessionPty(
      client,
      'nt-rejected-neighbor',
      spawnOptions(userDataDir, 100, 30, ['surviving-owner']),
      500
    )
    await within(owner.ready, 'surviving owner attach')
    owner.pause()
    await within(pauseReachedHost.promise, 'surviving owner pause')

    const neighbor = sessionPty(
      client,
      'nt-rejected-neighbor',
      spawnOptions(userDataDir, 80, 24, ['rejected-neighbor']),
      500
    )
    const heldAttach = await within(rejectedAttach.promise, 'delayed neighbor attach')
    owner.destroy()
    await eventLoopTurn()
    expect(commands).toEqual(['pause', 'attach:rejected-neighbor'])

    heldAttach.socket.write(
      encodeFrame({ id: heldAttach.id, ok: false, error: 'neighbor attach rejected' })
    )
    await expect(within(neighbor.ready, 'rejected neighbor settlement')).rejects.toThrow(
      'neighbor attach rejected'
    )
    await within(resumed.promise, 'rejected-neighbor resume')
    await within(detached.promise, 'rejected-neighbor detach')
    expect(commands).toEqual(['pause', 'attach:rejected-neighbor', 'resume', 'detach'])
  })

  it('buffers a cold session data frame received before attach acknowledgement and delivers it exactly once', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-cold-data-')
    const attachHeld = deferred<{ socket: net.Socket; id: number }>()
    const preAckFrameWritten = deferred<void>()
    const delivered: string[] = []
    const order: string[] = []

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            attachHeld.resolve({ socket, id: request.id })
            // A v2 event frame is dropped by the client unless it carries a valid `generation`
            // (session-host-client.ts's `handleFrame`); a pre-ack frame with no expected generation
            // yet is what the client adopts as this session's generation, so it must match the
            // generation the held attach acknowledgement below eventually confirms.
            socket.write(
              encodeFrame({
                type: 'data',
                name: request.name,
                data: 'COLD-PRE-ACK',
                generation: 'flow-generation'
              }),
              () => preAckFrameWritten.resolve()
            )
          } else if (request.cmd === 'hasSession') {
            socket.write(
              encodeFrame({
                type: 'data',
                name: request.name,
                data: 'POST-ACK',
                generation: 'flow-generation'
              }) + encodeFrame({ id: request.id, ok: true, result: { exists: true, generation: 'flow-generation' } })
            )
          } else if (request.cmd === 'detach' || request.cmd === 'resize') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const pty = sessionPty(
      client,
      'nt-cold-pre-ack',
      spawnOptions(userDataDir, 80, 24),
      500
    )
    pty.onData((data) => {
      delivered.push(data)
      order.push(`data:${data}`)
    })
    const ready = pty.ready.then((result) => {
      order.push('ready')
      return result
    })

    const heldAttach = await within(attachHeld.promise, 'cold attach request')
    await within(preAckFrameWritten.promise, 'pre-ack data write')
    await eventLoopTurn()
    expect(delivered).toEqual([])
    heldAttach.socket.write(
      encodeFrame({ id: heldAttach.id, ok: true, result: { fresh: true, generation: 'flow-generation' } })
    )
    await expect(within(ready, 'cold attach acknowledgement')).resolves.toEqual({ fresh: true, generation: 'flow-generation' })
    expect(order).toEqual(['data:COLD-PRE-ACK', 'ready'])

    await expect(within(client.hasSession('nt-cold-pre-ack'), 'post-ack data barrier')).resolves.toBe(
      true
    )
    expect(delivered).toEqual(['COLD-PRE-ACK', 'POST-ACK'])
  })

  it('follows the most recently active view, normalizes invalid axes, and falls back when it leaves (issue #914)', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-geometry-')
    // `narrow`'s attach co-attaches to the already-live generation `wide` created, so it reaches
    // the host as `attachExisting` rather than a second `attach` — and `attachExisting` deliberately
    // carries no spawn plan (session-host-client.ts's `SubscriberEntry.spawn` doc comment), so only
    // cols/rows are checkable for it, not `args`.
    const attachClaims: Array<{ cmd: 'attach' | 'attachExisting'; cols: number; rows: number }> = []
    const resizeRequests: Array<{ cols: number; rows: number }> = []
    const normalizedFirst = deferred<void>()
    const normalizedSecond = deferred<void>()
    const wideLatest = deferred<void>()
    const fellBackAfterDetach = deferred<void>()

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            attachClaims.push({
              cmd: 'attach',
              cols: request.spawn.cols,
              rows: request.spawn.rows
            })
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            attachClaims.push({
              cmd: 'attachExisting',
              cols: request.cols ?? -1,
              rows: request.rows ?? -1
            })
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false, generation: 'flow-generation' } }))
          } else if (request.cmd === 'resize') {
            resizeRequests.push({ cols: request.cols, rows: request.rows })
            socket.write(encodeFrame({ id: request.id, ok: true }))
            if (request.cols === 120 && request.rows === 1) normalizedFirst.resolve()
            if (request.cols === 90 && request.rows === 40) {
              if (resizeRequests.length === 2) normalizedSecond.resolve()
              else fellBackAfterDetach.resolve()
            }
            if (request.cols === 100 && request.rows === 20) wideLatest.resolve()
          } else if (request.cmd === 'detach' || request.cmd === 'write') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const wide = sessionPty(
      client,
      'nt-local-geometry',
      spawnOptions(userDataDir, 120, 30, ['wide-short']),
      500
    )
    await within(wide.ready, 'wide geometry attach')
    const narrow = sessionPty(
      client,
      'nt-local-geometry',
      spawnOptions(userDataDir, 80, 40, ['narrow-tall']),
      500
    )
    await within(narrow.ready, 'narrow geometry attach')
    // The newly attached view is the most recently active one, so the session takes ITS size —
    // not the componentwise minimum (80x30) it used to, which is what left a phone that dismissed
    // its keyboard stuck at a shorter desktop view's rows.
    expect(attachClaims).toEqual([
      { cmd: 'attach', cols: 120, rows: 30 },
      { cmd: 'attachExisting', cols: 80, rows: 40 }
    ])

    // A CHANGED claim makes that view the active one; each axis still normalizes independently.
    wide.resize(Number.NaN, -5)
    await within(normalizedFirst.promise, 'NaN and negative geometry normalization')
    narrow.resize(90.9, Number.POSITIVE_INFINITY)
    await within(normalizedSecond.promise, 'fractional and infinite geometry normalization')
    wide.resize(100, 20)
    await within(wideLatest.promise, 'the resized view becomes the active one')
    // The active view leaves: the session falls back to the one that was active before it.
    wide.destroy()
    await within(fellBackAfterDetach.promise, 'fallback to the previous view after detach')

    expect(resizeRequests).toEqual([
      { cols: 120, rows: 1 },
      { cols: 90, rows: 40 },
      { cols: 100, rows: 20 },
      { cols: 90, rows: 40 }
    ])
  })

  it('finishes paused geometry replay before normal requests and releases buffered repaint data only after resume', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-replay-')
    const firstClosed = deferred<void>()
    const initialPause = deferred<void>()
    // v2 reconnect restoration warm-replays via `attachExisting`, not a second `attach` — see
    // `restoreSocket` in session-host-client.ts, which never sends a spawn plan on reattach.
    const replayAttach = deferred<Extract<SessionHostRequest, { cmd: 'attachExisting' }>>()
    const bothNormalRequests = deferred<void>()
    const replayResume = deferred<{ socket: net.Socket; id: number }>()
    const replayBufferFlushed = deferred<void>()
    const sequence: string[] = []
    const secondNormalCommands: string[] = []
    let connection = 0
    let firstSocket: net.Socket | undefined
    let replaySocket: net.Socket | undefined
    let replayRequestId: number | undefined
    let normalCount = 0

    const server = net.createServer((socket) => {
      const ownConnection = ++connection
      if (ownConnection === 1) firstSocket = socket
      trackSocket(socket)
      socket.once('close', () => {
        if (ownConnection === 1) firstClosed.resolve()
      })
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            if (ownConnection === 2) sequence.push('request:hello')
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            // Only the initial cold create (`larger`) arrives here — `smaller` co-attaches below,
            // and the reconnect below that, both via `attachExisting`.
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            if (ownConnection === 1) {
              // `smaller` co-attaches to the already-live generation `larger` just created.
              socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false, generation: 'flow-generation' } }))
            } else {
              // The label stays `request:attach` — it names the attach-family step in the test's
              // own sequence, not the literal wire command.
              sequence.push('request:attach')
              replaySocket = socket
              replayRequestId = request.id
              replayAttach.resolve(request)
            }
          } else if (request.cmd === 'pause') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
            if (ownConnection === 1) initialPause.resolve()
          } else if (request.cmd === 'resume') {
            sequence.push('request:resume')
            replayResume.resolve({ socket, id: request.id })
          } else if (request.cmd === 'hasSession') {
            sequence.push('request:hasSession')
            secondNormalCommands.push(request.cmd)
            socket.write(
              encodeFrame({ id: request.id, ok: true, result: { exists: true, generation: 'flow-generation' } })
            )
            if (++normalCount === 2) bothNormalRequests.resolve()
          } else if (request.cmd === 'write') {
            sequence.push('request:write')
            secondNormalCommands.push(request.cmd)
            socket.write(encodeFrame({ id: request.id, ok: true }))
            if (++normalCount === 2) bothNormalRequests.resolve()
          } else if (request.cmd === 'resize' || request.cmd === 'detach') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const largerDelivered: string[] = []
    const smallerDelivered: string[] = []
    const maybeFinishReplayDelivery = (): void => {
      if (
        largerDelivered.join('').includes('REPLAY-SCREEN') &&
        largerDelivered.join('').includes('LIVE-WHILE-PAUSED') &&
        smallerDelivered.join('').includes('REPLAY-SCREEN') &&
        smallerDelivered.join('').includes('LIVE-WHILE-PAUSED')
      ) {
        replayBufferFlushed.resolve()
      }
    }
    const client = new SessionHostClient({ userDataDir })
    const larger = sessionPty(
      client,
      'nt-replay-barrier',
      spawnOptions(userDataDir, 120, 40, ['larger']),
      500
    )
    const smaller = sessionPty(
      client,
      'nt-replay-barrier',
      spawnOptions(userDataDir, 80, 24, ['smaller']),
      500
    )
    larger.onData((data) => {
      sequence.push('data:larger')
      largerDelivered.push(data)
      maybeFinishReplayDelivery()
    })
    smaller.onData((data) => {
      sequence.push('data:smaller')
      smallerDelivered.push(data)
      maybeFinishReplayDelivery()
    })
    await within(Promise.all([larger.ready, smaller.ready]), 'initial co-attach')
    larger.pause()
    await within(initialPause.promise, 'initial pause acknowledgement')

    firstSocket?.destroy()
    await within(firstClosed.promise, 'first socket close')
    const replay = await within(replayAttach.promise, 'automatic reconnect attach')
    const hasSession = client.hasSession('nt-replay-barrier')
    smaller.write('normal-write-after-replay')

    await eventLoopTurn()
    expect(sequence.slice(0, 2)).toEqual(['request:hello', 'request:attach'])
    expect(secondNormalCommands).toEqual([])
    expect(largerDelivered).toEqual([])
    expect(smallerDelivered).toEqual([])
    expect(replay.paused).toBe(true)
    expect(replay.cols).toBe(80)
    expect(replay.rows).toBe(24)

    // Written as two SEPARATE socket writes, the second only once the first's bytes have flushed:
    // the repaint screen the response carries is delivered through `restoreSocket`'s own awaited
    // continuation (a microtask, scheduled once the response frame is parsed), while a raw `data`
    // event frame is delivered synchronously the instant it is parsed. Concatenating both frames
    // into one write lets the client parse them in the same synchronous pass, which would hand the
    // live marker to `deliverData` before the repaint's continuation has even run — reversing the
    // very ordering this test exists to prove. A real flush boundary between the two writes is what
    // gives the response's continuation a chance to run first.
    replaySocket!.write(
      encodeFrame({
        id: replayRequestId!,
        ok: true,
        result: { fresh: false, screen: 'REPLAY-SCREEN', generation: 'flow-generation' }
      }),
      () => {
        replaySocket!.write(
          encodeFrame({
            type: 'data',
            name: 'nt-replay-barrier',
            data: 'LIVE-WHILE-PAUSED',
            generation: 'flow-generation'
          })
        )
      }
    )
    await expect(within(hasSession, 'post-replay hasSession')).resolves.toBe(true)
    await within(bothNormalRequests.promise, 'both requests held behind replay')
    expect(largerDelivered).toEqual([])
    expect(smallerDelivered).toEqual([])

    larger.resume()
    const heldResume = await within(replayResume.promise, 'reconnect resume request')
    await eventLoopTurn()
    expect(largerDelivered).toEqual([])
    expect(smallerDelivered).toEqual([])
    heldResume.socket.write(encodeFrame({ id: heldResume.id, ok: true }))
    await within(replayBufferFlushed.promise, 'buffered reconnect data release')
    for (const delivered of [largerDelivered, smallerDelivered]) {
      const repaintIndex = delivered.findIndex((data) => data.includes('REPLAY-SCREEN'))
      const liveIndex = delivered.findIndex((data) => data.includes('LIVE-WHILE-PAUSED'))
      expect(repaintIndex).toBeGreaterThanOrEqual(0)
      expect(repaintIndex).toBeLessThan(liveIndex)
    }
    expect(sequence.indexOf('request:attach')).toBeLessThan(sequence.indexOf('request:hasSession'))
    expect(sequence.indexOf('request:attach')).toBeLessThan(sequence.indexOf('request:write'))
    expect(sequence.indexOf('request:resume')).toBeLessThan(sequence.indexOf('data:larger'))
  })

  it('reconnects and reattaches an idle live subscriber without another client API call', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-idle-')
    const firstClosed = deferred<void>()
    const idleReplay = deferred<void>()
    const markerDelivered = deferred<string>()
    let connection = 0
    let firstSocket: net.Socket | undefined

    const server = net.createServer((socket) => {
      const ownConnection = ++connection
      if (ownConnection === 1) firstSocket = socket
      trackSocket(socket)
      socket.once('close', () => {
        if (ownConnection === 1) firstClosed.resolve()
      })
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            // Only the initial cold create arrives here; v2 reconnect replay warm-reattaches via
            // `attachExisting` (below), never a second `attach`.
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
          } else if (request.cmd === 'attachExisting') {
            socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false, generation: 'flow-generation' } }))
            idleReplay.resolve()
            socket.write(
              encodeFrame({
                type: 'data',
                name: request.name,
                data: 'IDLE-RECONNECT-MARKER',
                generation: 'flow-generation'
              })
            )
          } else if (request.cmd === 'detach' || request.cmd === 'resize') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const pty = sessionPty(
      client,
      'nt-idle-reconnect',
      spawnOptions(userDataDir, 90, 30),
      500
    )
    pty.onData((data) => {
      if (data.includes('IDLE-RECONNECT-MARKER')) markerDelivered.resolve(data)
    })
    await within(pty.ready, 'initial idle attach')

    firstSocket?.destroy()
    await within(firstClosed.promise, 'idle socket close')
    await within(idleReplay.promise, 'automatic idle replay', 4_000)
    await expect(within(markerDelivered.promise, 'idle replay data', 4_000)).resolves.toContain(
      'IDLE-RECONNECT-MARKER'
    )
    expect(connection).toBeGreaterThanOrEqual(2)
  })

  it('compensates a canceled delayed attach with detach and never replays the retired subscriber', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-cancel-')
    const attachSeen = deferred<void>()
    const detachSeen = deferred<void>()
    const firstClosed = deferred<void>()
    let connection = 0
    let firstSocket: net.Socket | undefined
    let delayedAttachId: number | undefined
    const reconnectCommands: string[] = []
    const firstDetachNames: string[] = []

    const server = net.createServer((socket) => {
      const ownConnection = ++connection
      if (ownConnection === 1) firstSocket = socket
      trackSocket(socket)
      socket.once('close', () => {
        if (ownConnection === 1) firstClosed.resolve()
      })
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            if (ownConnection === 1) {
              delayedAttachId = request.id
              attachSeen.resolve()
            } else {
              reconnectCommands.push(request.cmd)
              socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: false } }))
            }
          } else if (request.cmd === 'detach') {
            if (ownConnection === 1) {
              firstDetachNames.push(request.name)
              detachSeen.resolve()
            }
            socket.write(encodeFrame({ id: request.id, ok: true }))
          } else if (request.cmd === 'hasSession') {
            if (ownConnection === 1) {
              // Give the test a client-observed disconnect: awaiting this request's rejection is
              // stronger than observing the peer socket's local close event.
              socket.destroy()
            } else {
              reconnectCommands.push(request.cmd)
              socket.write(
                encodeFrame({ id: request.id, ok: true, result: { exists: true, generation: 'flow-generation' } })
              )
            }
          } else if (request.cmd === 'listSessions') {
            reconnectCommands.push(request.cmd)
            socket.write(encodeFrame({ id: request.id, ok: true, result: { names: [] } }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const pty = sessionPty(
      client,
      'nt-canceled-attach',
      spawnOptions(userDataDir, 80, 24),
      500
    )
    const readySettled = pty.ready.then(
      () => 'resolved' as const,
      () => 'rejected' as const
    )
    await within(attachSeen.promise, 'delayed attach request')
    pty.destroy()
    firstSocket!.write(
      encodeFrame({ id: delayedAttachId!, ok: true, result: { fresh: true, generation: 'flow-generation' } })
    )
    await within(detachSeen.promise, 'compensating detach')
    await expect(within(readySettled, 'canceled ready settlement')).resolves.toBe('rejected')

    await expect(
      within(client.hasSession('nt-canceled-attach'), 'disconnect observation probe')
    ).rejects.toThrow(/connection lost/i)
    await within(firstClosed.promise, 'canceled attach socket close')
    await expect(within(client.hasSession('nt-canceled-attach'), 'forced reconnect')).resolves.toBe(
      true
    )
    await expect(within(client.listSessions(), 'post-reconnect request barrier')).resolves.toEqual([])
    expect(reconnectCommands).toEqual(['hasSession', 'listSessions'])
    expect(firstDetachNames).toEqual(['nt-canceled-attach'])
  })

  it('keeps kill ordered ahead of a replacement attach after the old local state retires', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-kill-lane-')
    const oldWriteReachedHost = deferred<void>()
    const releaseOldWrite = deferred<void>()
    const killReachedHost = deferred<void>()
    const replacementAttachReachedHost = deferred<void>()
    const afterInitial: string[] = []
    let killCount = 0

    const server = net.createServer((socket) => {
      trackSocket(socket)
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            if (request.spawn.args[0] === 'old-generation') {
              socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'flow-generation' } }))
            } else {
              afterInitial.push('attach:replacement')
              replacementAttachReachedHost.resolve()
              socket.write(
                encodeFrame({
                  id: request.id,
                  ok: true,
                  result: { fresh: true, generation: 'replacement-generation-id' }
                })
              )
            }
          } else if (request.cmd === 'write') {
            afterInitial.push('write:old')
            oldWriteReachedHost.resolve()
            void releaseOldWrite.promise.then(() => {
              if (!socket.destroyed) socket.write(encodeFrame({ id: request.id, ok: true }))
            })
          } else if (request.cmd === 'killSession') {
            afterInitial.push('kill')
            killCount++
            socket.write(encodeFrame({ id: request.id, ok: true, result: {} }))
            killReachedHost.resolve()
          } else if (request.cmd === 'detach' || request.cmd === 'resize') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const old = sessionPty(
      client,
      'nt-kill-name-lane',
      spawnOptions(userDataDir, 100, 32, ['old-generation']),
      500
    )
    await within(old.ready, 'old generation attach')
    old.write('hold-old-name-lane')
    await within(oldWriteReachedHost.promise, 'old queued write')

    const killedOld = client.killSession('nt-kill-name-lane')
    old.destroy()
    await eventLoopTurn()
    expect(afterInitial).toEqual(['write:old'])

    releaseOldWrite.resolve()
    await within(killReachedHost.promise, 'old generation kill')
    // The kill barrier (`killReplayBarriers` in session-host-client.ts) refuses ANY attach for
    // this name — cold create included, not just reconnect replay — until the kill is confirmed;
    // see session-host-client.test.ts's "rejects a concurrent attach while kill confirmation is
    // in progress" for the same contract asserted directly. The replacement therefore only
    // attaches once the kill has actually settled, which is what keeps its wire request ordered
    // strictly behind the kill's rather than racing it.
    await expect(within(killedOld, 'old generation kill acknowledgement')).resolves.toBeUndefined()

    const replacement = sessionPty(
      client,
      'nt-kill-name-lane',
      spawnOptions(userDataDir, 80, 24, ['replacement-generation']),
      500
    )
    await within(replacementAttachReachedHost.promise, 'post-kill replacement attach')
    await expect(within(replacement.ready, 'replacement generation attach')).resolves.toEqual({
      fresh: true,
      generation: 'replacement-generation-id'
    })
    expect(afterInitial).toEqual(['write:old', 'kill', 'attach:replacement'])
    expect(killCount).toBe(1)
  })

  it('retires an exiting generation before a synchronous replacement attach and replays only the replacement', async () => {
    const { userDataDir, endpoint } = fixture('nodeterm-session-flow-generation-')
    const oldExit = vi.fn()
    const replacementExit = vi.fn()
    const replacementCreated = deferred<SessionHostPty>()
    const replacementData = deferred<string>()
    const firstClosed = deferred<void>()
    // v2 reconnect restoration warm-replays via `attachExisting`, not a second `attach` — see
    // `restoreSocket` in session-host-client.ts, which never sends a spawn plan on reattach.
    const replayAttach = deferred<Extract<SessionHostRequest, { cmd: 'attachExisting' }>>()
    let connection = 0
    let firstSocket: net.Socket | undefined
    const firstConnectionAttachArgs: string[][] = []
    // `attachExisting` deliberately carries no spawn plan, so the reconnect is identified by the
    // exact generation it expects rather than by `spawn.args`.
    const reconnectExpectedGenerations: Array<string | undefined> = []

    const server = net.createServer((socket) => {
      const ownConnection = ++connection
      if (ownConnection === 1) firstSocket = socket
      trackSocket(socket)
      socket.once('close', () => {
        if (ownConnection === 1) firstClosed.resolve()
      })
      const framer = new LineFramer()
      socket.on('data', (chunk: Buffer) => {
        for (const request of framer.push<SessionHostRequest>(chunk.toString('utf8'))) {
          if (request.cmd === 'hello') {
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { protocolVersion: SESSION_HOST_PROTOCOL_VERSION }
              })
            )
          } else if (request.cmd === 'attach') {
            // Both `old` and its replacement are cold creates (the replacement attaches only after
            // `old`'s state has fully retired, so there is nothing local to co-attach onto) — both
            // therefore arrive here as plain `attach`, distinguished by generation below.
            if (request.spawn.args[0] === 'old-generation') {
              firstConnectionAttachArgs.push(request.spawn.args)
              socket.write(encodeFrame({ id: request.id, ok: true, result: { fresh: true, generation: 'old-generation-id' } }))
            } else {
              firstConnectionAttachArgs.push(request.spawn.args)
              socket.write(
                encodeFrame({
                  id: request.id,
                  ok: true,
                  result: { fresh: true, generation: 'replacement-generation-id' }
                })
              )
            }
          } else if (request.cmd === 'attachExisting') {
            // The automatic reconnect warm-replays whichever generation is still locally attached —
            // proven below to be the replacement's, never the retired old one.
            reconnectExpectedGenerations.push(request.expectedGeneration)
            replayAttach.resolve(request)
            socket.write(
              encodeFrame({
                id: request.id,
                ok: true,
                result: { fresh: false, generation: 'replacement-generation-id' }
              }) +
                encodeFrame({
                  type: 'data',
                  name: request.name,
                  data: 'REPLACEMENT-REPLAY-MARKER',
                  generation: 'replacement-generation-id'
                })
            )
          } else if (request.cmd === 'hasSession') {
            socket.write(
              encodeFrame({ id: request.id, ok: true, result: { exists: true, generation: 'flow-generation' } })
            )
          } else if (request.cmd === 'detach' || request.cmd === 'resize') {
            socket.write(encodeFrame({ id: request.id, ok: true }))
          }
        }
      })
    })
    await listen(server, endpoint)

    const client = new SessionHostClient({ userDataDir })
    const old = sessionPty(
      client,
      'nt-generation-replace',
      spawnOptions(userDataDir, 100, 32, ['old-generation']),
      500
    )
    old.onExit((event) => {
      oldExit(event)
      const replacement = sessionPty(
        client,
        'nt-generation-replace',
        spawnOptions(userDataDir, 70, 20, ['replacement-generation']),
        500
      )
      replacement.onExit(replacementExit)
      replacement.onData((data) => {
        if (data.includes('REPLACEMENT-REPLAY-MARKER')) replacementData.resolve(data)
      })
      replacementCreated.resolve(replacement)
    })
    await within(old.ready, 'old generation attach')

    firstSocket!.write(
      encodeFrame({ type: 'exit', name: 'nt-generation-replace', exitCode: 17, generation: 'old-generation-id' })
    )
    const replacement = await within(replacementCreated.promise, 'synchronous replacement creation')
    await within(replacement.ready, 'replacement attach')
    expect(oldExit).toHaveBeenCalledTimes(1)
    expect(oldExit).toHaveBeenCalledWith({ exitCode: 17 })
    expect(replacementExit).not.toHaveBeenCalled()
    expect(firstConnectionAttachArgs).toEqual([['old-generation'], ['replacement-generation']])

    firstSocket?.destroy()
    await within(firstClosed.promise, 'replacement socket close')
    const replay = await within(replayAttach.promise, 'replacement automatic replay', 4_000)
    expect(replay.expectedGeneration).toBe('replacement-generation-id')
    await expect(
      within(replacementData.promise, 'replacement replay data', 4_000)
    ).resolves.toContain('REPLACEMENT-REPLAY-MARKER')
    await expect(
      within(client.hasSession('nt-generation-replace'), 'replacement replay request barrier')
    ).resolves.toBe(true)
    expect(reconnectExpectedGenerations).toEqual(['replacement-generation-id'])
    expect(replacementExit).not.toHaveBeenCalled()
  })
})