Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

35.5 KB
Raw Blame
import { describe, expect, it, vi } from 'vitest'
import type { RegisteredSession } from './registry.js'
import type { DiscoveredTerminalAgent, TerminalAgentProbe } from './terminalAgentDiscovery.js'
import type { TerminalBackend } from './terminalBackend.js'
import { TerminalAgentReconciler } from './terminalAgentReconciler.js'
import { terminalRouteKey } from './terminalRuntime.js'
import type { TerminalRuntimeRef } from './terminalTypes.js'

const tmux: TerminalRuntimeRef = { backend: 'tmux', paneId: '%1' }
const identity = { pid: 42, executable: 'claude', startMarker: 'Sat Aug 15 10:00:00 2026' }

function session(runtimes: TerminalRuntimeRef[] = [tmux]): RegisteredSession {
  return {
    schemaVersion: 2, active: true, agentId: 'agent-1', sessionId: '', boundAt: null, engine: 'claude',
    transcriptPath: null, projectDir: 'work', cwd: '/work', runtimes,
    primaryRuntimeKey: terminalRouteKey(runtimes[0]), tmuxPane: runtimes.find((runtime) => runtime.backend === 'tmux')?.paneId ?? '',
    source: null, title: null, model: null, cliVersion: null, processIdentity: identity,
    registeredAt: 1, touchedAt: 1, lastHookAt: 1, lastTranscriptAt: 1,
  }
}

function observed(runtimes: TerminalRuntimeRef[]): DiscoveredTerminalAgent {
  return {
    engine: 'claude', cwd: '/work', processIdentity: identity, args: 'claude', resumeSessionId: null,
    runtimes, primaryRuntimeKey: terminalRouteKey(runtimes[0]),
  }
}

function probe(targets: TerminalAgentProbe['targets'], agents: DiscoveredTerminalAgent[] = []): TerminalAgentProbe {
  return { processTableAvailable: true, targets, agents, ambiguousPlacements: new Set() }
}

describe('composite terminal reconciliation', () => {
  function initialLaunch() {
    const current: RegisteredSession = { ...session(), processIdentity: null, launch: { state: 'starting' } }
    const snapshot = probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }])
    const read = vi.fn(async () => snapshot)
    const onDormant = vi.fn(() => { current.active = false })
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({ current: () => [current], backends: [], backendOrder: ['tmux'],
      probe: read, onDiscovered: vi.fn(), onObserved: observed => { current.processIdentity = observed.processIdentity },
      onDormant, onRemoved })
    return { current, snapshot, read, onDormant, onRemoved, reconciler }
  }

  it('keeps an initial launch active until an engine is observed, then detects its later exit', async () => {
    const run = initialLaunch()
    for (let n = 0; n < 3; n++) await run.reconciler.trigger()
    expect(run.current.active).toBe(true)
    expect(run.onDormant).not.toHaveBeenCalled()
    expect(run.onRemoved).not.toHaveBeenCalled()
    run.snapshot.agents = [observed([tmux])]
    await run.reconciler.trigger()
    expect(run.current.processIdentity).toEqual(identity)
    // Even if startup's ready marker has not arrived, a known engine can exit.
    run.snapshot.agents = []
    await run.reconciler.trigger()
    expect(run.onDormant).not.toHaveBeenCalled()
    await run.reconciler.trigger()
    expect(run.onDormant).toHaveBeenCalledOnce()
    expect(run.current.active).toBe(false)
  })

  it('does not apply initial-start absence after readiness changes during the probe', async () => {
    const run = initialLaunch()
    run.read.mockImplementationOnce(async () => { run.current.launch = { state: 'ready' }; return run.snapshot })
    await run.reconciler.trigger()
    await run.reconciler.trigger()
    expect(run.current.active).toBe(true)
    expect(run.onDormant).not.toHaveBeenCalled()
    await run.reconciler.trigger()
    expect(run.onDormant).toHaveBeenCalledOnce()
  })

  it('discards earlier engine misses when a new initial start owns the pane', async () => {
    const run = initialLaunch()
    run.current.launch = { state: 'ready' }
    await run.reconciler.trigger()
    run.current.launch = { state: 'starting' }
    await run.reconciler.trigger()
    expect(run.onDormant).not.toHaveBeenCalled()
    run.current.launch = { state: 'ready' }
    await run.reconciler.trigger()
    expect(run.onDormant).not.toHaveBeenCalled()
    await run.reconciler.trigger()
    expect(run.onDormant).toHaveBeenCalledOnce()
  })

  it('still detects a genuinely missing pane during an initial start', async () => {
    const run = initialLaunch()
    run.read.mockResolvedValue(probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]))
    await run.reconciler.trigger()
    await run.reconciler.trigger()
    expect(run.onRemoved).toHaveBeenCalledOnce()
    expect(run.onDormant).not.toHaveBeenCalled()
  })

  it('defers early startup hooks until restored panes have their original owners', async () => {
    const current = { ...session([tmux]), sessionId: 'saved-conversation', processIdentity: null }
    const onRemoved = vi.fn()
    const onDiscovered = vi.fn()
    const onObserved = vi.fn()
    const probed = vi.fn(async (_hints: ReadonlyMap<string, unknown>) =>
      probe([{ instanceId: 'tmux:default', result: { state: 'available' as const, roots: [] } }]))
    const reconciler = new TerminalAgentReconciler({
      deferUntilStart: true,
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved, onDormant: vi.fn(), onRemoved, probe: probed,
    })
    const restored: TerminalRuntimeRef = { backend: 'tmux', paneId: '%24' }
    // Hooks from an earlier restored pane used to run two full negative inventories here and
    // remove this row before its new pane was allocated. Never block a hook waiting for boot.
    await reconciler.triggerHint(restored, 'claude')
    await reconciler.trigger()
    expect(probed).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()

    current.runtimes = [restored]
    current.primaryRuntimeKey = terminalRouteKey(restored)
    current.launch = { state: 'starting' }
    const live = observed([restored])
    probed.mockImplementation(async () => probe([
      { instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: restored, rootPid: 1, cwd: '/work' }] } },
    ], [live]))
    try {
      await reconciler.start(60_000)
      expect(probed).toHaveBeenCalledWith(new Map([[terminalRouteKey(restored), 'claude']]))
      expect(onObserved).toHaveBeenCalledWith(live, current)
      expect(onDiscovered).not.toHaveBeenCalled()
      expect(onRemoved).not.toHaveBeenCalled()
    } finally { reconciler.stop() }
  })

  it('observes a bound agent saved before start ticks as the same process seen with them', async () => {
    const current = { ...session([tmux]), sessionId: 'saved-conversation' }
    const live = { ...observed([tmux]), processIdentity: { ...identity, startTicks: 26385008 } }
    const onDiscovered = vi.fn()
    const onObserved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe([
        { instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } },
      ], [live]),
    })
    try {
      await reconciler.start(60_000)
      expect(onObserved).toHaveBeenCalledWith(live, current)
      expect(onDiscovered).not.toHaveBeenCalled()
    } finally { reconciler.stop() }
  })

  it('advertises a retained pane even when no engine process is observed', async () => {
    const current = { ...session([tmux]), active: false }
    const onTerminalAvailability = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      onTerminalAvailability,
      probe: async () => probe([
        { instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } },
      ]),
    })

    await reconciler.trigger()

    expect(onTerminalAvailability).toHaveBeenCalledWith(current, true)
  })

  it('verifies a shell row on a drain host\'s pane, by that host\'s instance and not the target\'s', async () => {
    const old: TerminalRuntimeRef = { backend: 'ptyhost', instance: 'p2-0.4.901', paneId: '%1' }
    // The target's host has a pane of the same id: only the row's own instance may answer for it.
    const target: TerminalRuntimeRef = { backend: 'ptyhost', instance: 'p2-0.4.902', paneId: '%1' }
    const current = { ...session([old]), engine: 'terminal' as const, active: false, processIdentity: null }
    const onTerminalAvailability = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['ptyhost'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      onTerminalAvailability,
      probe: async () => probe([
        { instanceId: 'ptyhost:p2-0.4.902', result: { state: 'available', roots: [{ runtime: target, rootPid: 1, cwd: '/work' }] } },
        { instanceId: 'ptyhost:p2-0.4.901', result: { state: 'available', roots: [{ runtime: old, rootPid: 2, cwd: '/work' }] } },
      ]),
    })

    await reconciler.trigger()

    expect(onTerminalAvailability).toHaveBeenCalledWith(current, true)
  })

  it('still verifies retained panes when the process table is unavailable', async () => {
    const current = { ...session([tmux]), active: false }
    const onTerminalAvailability = vi.fn()
    const onProbeStatus = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      onTerminalAvailability, onProbeStatus,
      probe: async () => ({
        processTableAvailable: false,
        targets: [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
        agents: [], ambiguousPlacements: new Set(),
      }),
    })

    await reconciler.trigger()

    expect(onTerminalAvailability).toHaveBeenCalledWith(current, true)
    expect(onProbeStatus).toHaveBeenCalledWith({ ready: true, error: 'process table unavailable' })
  })

  it('awaits the initial discovery pass before start resolves', async () => {
    let release!: () => void
    const pending = new Promise<void>((resolve) => { release = resolve })
    const probed = vi.fn(async () => {
      await pending
      return probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }])
    })
    const reconciler = new TerminalAgentReconciler({
      current: () => [], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(), probe: probed,
    })
    let started = false
    const start = reconciler.start(60_000).then(() => { started = true })
    await Promise.resolve()
    expect(started).toBe(false)
    release()
    await start
    expect(started).toBe(true)
    reconciler.stop()
  })

  it('does not count an unavailable backend as a confirmed miss', async () => {
    const current = session([tmux])
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'unavailable', reason: 'stopped' } }]),
    })
    await reconciler.trigger()
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()
  })

  it('removes only after two successful negative inventories', async () => {
    const current = session([tmux])
    const onRemoved = vi.fn()
    const validate = vi.fn(async () => ({ state: 'gone' as const, reason: 'process exited' }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })
    await reconciler.trigger()
    expect(onRemoved).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onRemoved).toHaveBeenCalledWith(current, 'terminal runtime absent after 2 confirmed scans')
    expect(validate).toHaveBeenCalledTimes(2)
  })

  it('keeps a pane advertised but marks its missing engine dormant after two scans', async () => {
    const current = session([tmux])
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const validate = vi.fn(async () => ({ state: 'alive' as const }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })

    await reconciler.trigger()
    await reconciler.trigger()
    await reconciler.trigger()

    expect(validate).toHaveBeenCalledTimes(3)
    expect(onDormant).toHaveBeenCalledTimes(1)
    expect(onDormant).toHaveBeenCalledWith(current, 'engine process absent after 2 confirmed scans')
    expect(onRemoved).not.toHaveBeenCalled()
  })

  it('does not count a scan that began before the engine was identified against that engine', async () => {
    // The race four agents created at once hit (e2e/soak.e2e.ts): the first scan finds the pane still
    // running its launcher; the new-pane watcher identifies the engine while the second scan's probe
    // runs, and that probe, taken before the engine existed, used to count its second miss.
    const current: RegisteredSession = { ...session([tmux]), processIdentity: null, launch: { state: 'starting' } }
    const pane = { runtime: tmux, rootPid: 1, cwd: '/work' }
    let whileProbing: (() => void) | null = null
    const onDormant = vi.fn()
    const onObserved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved, onDormant, onRemoved: vi.fn(),
      probe: async () => {
        whileProbing?.()
        whileProbing = null
        return probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [pane] } }])
      },
    })
    await reconciler.trigger()
    whileProbing = () => { current.processIdentity = identity; current.launch = { state: 'ready' } }
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    // A probe that began after the engine was identified does speak for it, from a count of one.
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onDormant).toHaveBeenCalledWith(current, 'engine process absent after 2 confirmed scans')
    expect(onObserved).not.toHaveBeenCalled()
  })

  it('counts misses against one engine: an engine identified since starts again', async () => {
    const current = session([tmux])
    const pane = { runtime: tmux, rootPid: 1, cwd: '/work' }
    const onDormant = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved: vi.fn(),
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [pane] } }]),
    })
    await reconciler.trigger()
    current.processIdentity = { ...identity, pid: 43 }
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onDormant).toHaveBeenCalledTimes(1)
  })

  it('does not judge an agent created, or a pane given to one, while the probe ran', async () => {
    const agents: RegisteredSession[] = []
    const moved: TerminalRuntimeRef = { backend: 'tmux', paneId: '%2' }
    let whileProbing: (() => void) | null = null
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const validate = vi.fn(async () => ({ state: 'gone' as const, reason: 'no such pane' }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => agents, backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => {
        whileProbing?.()
        whileProbing = null
        return probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }])
      },
    })
    // Created mid-probe: the inventory was taken before its pane existed.
    whileProbing = () => { agents.push(session([tmux])) }
    await reconciler.trigger()
    // Given a new pane mid-probe: the same.
    whileProbing = () => {
      agents[0].runtimes = [moved]
      agents[0].primaryRuntimeKey = terminalRouteKey(moved)
    }
    await reconciler.trigger()
    expect(onRemoved).not.toHaveBeenCalled()
    expect(onDormant).not.toHaveBeenCalled()
    // Probes that began after both judge the pane as they find it: gone, twice.
    await reconciler.trigger()
    expect(onRemoved).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onRemoved).toHaveBeenCalledWith(agents[0], 'terminal runtime absent after 2 confirmed scans')
  })

  it('does not open an agent for a route that was held and released while the probe ran', async () => {
    // A stop retiring a starting agent's pane holds its route and lets it go; a probe taken before it
    // still saw the engine there, and opened a second agent for a pane that no longer existed.
    const onDiscovered = vi.fn()
    const onReconciled = vi.fn()
    const route = terminalRouteKey(tmux)
    let whileProbing: (() => void) | null = null
    const reconciler = new TerminalAgentReconciler({
      current: () => [], backends: [], backendOrder: ['tmux'],
      onDiscovered, onReconciled, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => {
        whileProbing?.()
        whileProbing = null
        return probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }], [observed([tmux])])
      },
    })
    whileProbing = () => { reconciler.holdRoute(route); reconciler.releaseRoute(route) }
    await reconciler.trigger()
    expect(onDiscovered).not.toHaveBeenCalled()
    expect(onReconciled).toHaveBeenLastCalledWith([])
    // Releasing a route nobody held changes nothing, and a probe that began afterwards speaks for it.
    reconciler.releaseRoute(route)
    await reconciler.trigger()
    expect(onDiscovered).toHaveBeenCalledTimes(1)
    expect(onReconciled).toHaveBeenLastCalledWith([observed([tmux])])
  })

  it('does not count a miss for an agent whose route changed hands while the probe ran', async () => {
    const current = session([tmux])
    const pane = { runtime: tmux, rootPid: 1, cwd: '/work' }
    const route = terminalRouteKey(tmux)
    let whileProbing: (() => void) | null = null
    const onDormant = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved: vi.fn(),
      probe: async () => {
        whileProbing?.()
        whileProbing = null
        return probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [pane] } }])
      },
    })
    await reconciler.trigger()
    whileProbing = () => { reconciler.holdRoute(route); reconciler.releaseRoute(route) }
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onDormant).toHaveBeenCalledTimes(1)
  })

  it('keeps an agent active when pane-specific validation is inconclusive', async () => {
    const current = session([tmux])
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const validate = vi.fn(async () => ({ state: 'unknown' as const, reason: 'process table timed out' }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })

    await reconciler.trigger()
    await reconciler.trigger()

    expect(onDormant).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()
  })

})

describe('restart route hold', () => {
  it('skips dormant-detection for a held route while a restart is in progress', async () => {
    const current = session([tmux])
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    // Same shape as "keeps a pane advertised but marks its missing engine dormant after two scans"
    // above: the pane's terminal placement validates alive, but no engine process is ever observed —
    // ordinarily that drives the agent dormant after MISS_LIMIT scans.
    const validate = vi.fn(async () => ({ state: 'alive' as const }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })
    reconciler.holdRoute(terminalRouteKey(tmux))

    await reconciler.trigger()
    await reconciler.trigger()
    await reconciler.trigger()

    expect(onDormant).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()
    expect(validate).not.toHaveBeenCalled()
  })

  it('does not open the replacement process as a new agent while its route is held', async () => {
    const current = session([tmux])
    const replacement = {
      ...observed([tmux]),
      processIdentity: { pid: 99, executable: 'claude', startMarker: 'Sat Aug 15 10:05:00 2026' },
    }
    const onDiscovered = vi.fn()
    const onObserved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe(
        [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
        [replacement],
      ),
    })
    reconciler.holdRoute(terminalRouteKey(tmux))

    await reconciler.trigger()

    expect(onDiscovered).not.toHaveBeenCalled()
    // The pre-existing agent isn't rebound through ordinary observation either — the restart handler
    // owns that via `registry.updateProcessIdentity` once it confirms the new process itself.
    expect(onObserved).not.toHaveBeenCalled()
  })

  it.each([30_000, null])('resumes normal reconciliation only when the current %s hold is released', async timeout => {
    const current = session([tmux])
    const onDormant = vi.fn()
    const validate = vi.fn(async () => ({ state: 'alive' as const }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved: vi.fn(),
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })
    const routeKey = terminalRouteKey(tmux)
    const releaseOld = reconciler.holdRoute(routeKey, timeout)
    const releaseCurrent = reconciler.holdRoute(routeKey, timeout)
    releaseOld()
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    expect(validate).not.toHaveBeenCalled()

    releaseCurrent()
    await reconciler.trigger()
    await reconciler.trigger()

    expect(onDormant).toHaveBeenCalledTimes(1)
  })
})

describe('a row matched by its route, before or without its process', () => {
  it('keeps a sessionless agent when the engine replaces its process inside the same pane', async () => {
    const existing = session([tmux])
    const replacement = {
      ...observed([tmux]),
      processIdentity: { pid: 84, executable: 'claude', startMarker: 'Sat Aug 15 10:00:02 2026' },
    }
    let current = existing
    const onObserved = vi.fn(async (candidate: DiscoveredTerminalAgent) => {
      current = { ...current, processIdentity: candidate.processIdentity }
    })
    const onDiscovered = vi.fn()
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved, onDormant: vi.fn(), onRemoved,
      probe: async () => probe(
        [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
        [replacement],
      ),
    })

    await reconciler.trigger()

    expect(onObserved).toHaveBeenCalledWith(replacement, existing)
    expect(current.agentId).toBe(existing.agentId)
    expect(current.processIdentity).toEqual(replacement.processIdentity)
    expect(onDiscovered).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()
  })

  it('validates an unbound route by its live engine rather than its provisional process id', async () => {
    const current = session([tmux])
    const validate = vi.fn(async () => ({ state: 'alive' as const }))
    const backend = { instanceId: 'tmux:default', validate } as unknown as TerminalBackend
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [backend], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })

    await reconciler.trigger()

    expect(validate).toHaveBeenCalledWith(tmux, { engine: 'claude', processIdentity: undefined })
  })

  it('sees a resumed row that has its conversation but not yet its process', async () => {
    // `resumePendingAgent` keeps the archived sessionId and clears processIdentity, so this row can
    // only be matched by its route. It used to be skipped for having an id at all — leaving the one
    // row that is waiting to be confirmed invisible to every scan, and its launch state stuck.
    const current = {
      ...session([tmux]),
      sessionId: 'archived-conversation',
      processIdentity: null,
      resumeOnly: true as const,
      active: false,
      launch: { state: 'failed' as const, error: 'RESUME_UNCONFIRMED', detail: 'not confirmed' },
    }
    const onObserved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe(
        [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
        [observed([tmux])],
      ),
    })

    await reconciler.trigger()

    expect(onObserved).toHaveBeenCalledOnce()
    expect(onObserved.mock.calls[0][1]).toBe(current)
  })

  it('leaves a bound row with its own process to process identity alone', async () => {
    // Both an id and a process: the stricter rule still holds, so another engine in the same pane
    // cannot inherit this row's transcript through the route.
    const current = { ...session([tmux]), sessionId: 'bound-conversation' }
    const onObserved = vi.fn()
    const intruder: DiscoveredTerminalAgent = {
      ...observed([tmux]),
      processIdentity: { pid: 999, executable: 'claude', startMarker: 'Tue Sep 24 09:00:00 2026' },
    }
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe(
        [{ instanceId: 'tmux:default', result: { state: 'available', roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }],
        [intruder],
      ),
    })

    await reconciler.trigger()

    expect(onObserved).not.toHaveBeenCalled()
  })

})

describe('start()', () => {
  it('keeps scanning when the opening pass fails — the interval is armed before it runs', async () => {
    // Awaiting first meant one bad probe left discovery unscheduled for the life of the daemon, and
    // rejected the caller's start-up on the way: no agents, no liveness, `discoveryReady` never true.
    vi.useFakeTimers()
    try {
      let pass = 0
      const scan = vi.fn(async () => {
        pass++
        if (pass === 1) throw new Error('ps timed out')
        return probe([])
      })
      const reconciler = new TerminalAgentReconciler({
        current: () => [], backends: [], backendOrder: ['tmux'],
        onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(),
        probe: scan,
      })
      await expect(reconciler.start(5_000)).resolves.toBeUndefined()
      expect(scan).toHaveBeenCalledTimes(1)
      await vi.advanceTimersByTimeAsync(5_000)
      expect(scan).toHaveBeenCalledTimes(2)
      reconciler.stop()
    } finally {
      vi.useRealTimers()
    }
  })
})

describe('a terminal pane (engine `terminal`)', () => {
  const live = [{ instanceId: 'tmux:default', result: { state: 'available' as const, roots: [{ runtime: tmux, rootPid: 1, cwd: '/work' }] } }]
  function terminal(overrides: Partial<RegisteredSession> = {}): RegisteredSession {
    return { ...session([tmux]), engine: 'terminal', terminalHost: true, processIdentity: null, ...overrides }
  }

  it('is never marked dormant for having no engine process — a shell at its prompt is the normal state', async () => {
    const current = terminal()
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe(live),
    })
    for (let i = 0; i < 4; i++) await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    expect(onRemoved).not.toHaveBeenCalled()
  })

  it('owns an engine process that appears in its pane: observed for THIS row, never discovered as a new agent', async () => {
    const current = terminal()
    const onDiscovered = vi.fn()
    const onObserved = vi.fn()
    const claude = observed([tmux])
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved, onDormant: vi.fn(), onRemoved: vi.fn(),
      probe: async () => probe(live, [claude]),
    })
    await reconciler.trigger()
    expect(onDiscovered).not.toHaveBeenCalled()
    expect(onObserved).toHaveBeenCalledTimes(1)
    expect(onObserved.mock.calls[0][1]).toBe(current)
    expect(onObserved.mock.calls[0][0]).toMatchObject({ engine: 'claude', processIdentity: identity })
  })

  it('reports the adopted engine dormant when it exits and the pane lives on (the handler turns it back into a terminal)', async () => {
    const current = terminal({ engine: 'claude', processIdentity: identity })
    const onDormant = vi.fn()
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved,
      probe: async () => probe(live),
    })
    await reconciler.trigger()
    expect(onDormant).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onDormant).toHaveBeenCalledWith(current, 'engine process absent after 2 confirmed scans')
    expect(onRemoved).not.toHaveBeenCalled()
  })

  it('is removed like any agent once its pane is gone — the shell exited', async () => {
    const current = terminal()
    const onRemoved = vi.fn()
    const reconciler = new TerminalAgentReconciler({
      current: () => [current], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant: vi.fn(), onRemoved,
      probe: async () => probe([{ instanceId: 'tmux:default', result: { state: 'available', roots: [] } }]),
    })
    await reconciler.trigger()
    expect(onRemoved).not.toHaveBeenCalled()
    await reconciler.trigger()
    expect(onRemoved).toHaveBeenCalledWith(current, 'terminal runtime absent after 2 confirmed scans')
  })
})

describe('a pass with a deadline', () => {
  const available = (roots: Array<{ runtime: TerminalRuntimeRef; rootPid: number; cwd: string }> = []) =>
    [{ instanceId: 'tmux:default', result: { state: 'available' as const, roots } }]

  it('gives up a probe that has not answered by the deadline, applies nothing, and probes again on the next pass', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const onRemoved = vi.fn()
    const onDormant = vi.fn()
    let answer: TerminalAgentProbe | null = null
    const probed = vi.fn(() => answer ? Promise.resolve(answer) : new Promise<TerminalAgentProbe>(() => {}))
    const reconciler = new TerminalAgentReconciler({
      current: () => [session()], backends: [], backendOrder: ['tmux'],
      onDiscovered: vi.fn(), onObserved: vi.fn(), onDormant, onRemoved, probe: probed, passDeadlineMs: 50,
    })
    // Before, this never returned: not to a hook waiting to bind, nor to anything after it. It says the
    // pass was not done, so the hook knows to wait for its agent another way.
    await expect(reconciler.triggerHint(tmux, 'claude')).resolves.toBe(false)
    expect(warn).toHaveBeenCalledWith('[discovery] the terminal probe has not answered in 50 ms; this pass is given up, every agent kept as it is')
    expect(onRemoved).not.toHaveBeenCalled()
    expect(onDormant).not.toHaveBeenCalled()
    answer = probe(available())
    await expect(reconciler.trigger()).resolves.toBe(true)
    expect(probed).toHaveBeenCalledTimes(2)
    // The hint the given-up pass did not use is still there for the one that answered.
    expect(probed.mock.calls[1]).toEqual([new Map([[terminalRouteKey(tmux), 'claude']])])
    warn.mockRestore()
  })

  it('lets whoever waits for a pass go on when its apply does not finish, and keeps passes one at a time', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    let release!: () => void
    const stuck = new Promise<void>((resolve) => { release = resolve })
    const onDiscovered = vi.fn(() => stuck)
    const probed = vi.fn(async () => probe(available([{ runtime: tmux, rootPid: 1, cwd: '/work' }]), [observed([tmux])]))
    const reconciler = new TerminalAgentReconciler({
      current: () => [], backends: [], backendOrder: ['tmux'],
      onDiscovered, onObserved: vi.fn(), onDormant: vi.fn(), onRemoved: vi.fn(), probe: probed, passDeadlineMs: 50,
    })
    await reconciler.trigger()
    expect(onDiscovered).toHaveBeenCalledTimes(1)
    await reconciler.triggerHint(tmux, 'claude')
    expect(warn.mock.calls).toEqual([['[discovery] a pass has run for 50 ms; whoever waits for it goes on without it']])
    // No second pass beside the stuck one; the one asked for runs once it is done.
    expect(probed).toHaveBeenCalledTimes(1)
    release()
    await vi.waitFor(() => expect(probed).toHaveBeenCalledTimes(2))
    warn.mockRestore()
  })
})