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.

30.4 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { EventEmitter } from 'node:events'
import type { ChildProcess } from 'node:child_process'
import { mkdirSync, mkdtempSync, realpathSync, rmSync, utimesSync, writeFileSync } from 'node:fs'
import { createServer, type Server } from 'node:net'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import type { InstalledDsh } from './installed.js'
import { spawnDshCommand } from './shell.js'
import { DshViewerManager, buildViewerUrl, freeLoopbackPort, resolveViewer, waitForLoopbackPort } from './viewer.js'

// Off by default: set `net.fake` to hand the viewer a scripted server or socket instead of a real one.
const net = vi.hoisted(() => ({ fake: null as null | { createServer?: () => unknown; connect?: () => unknown } }))
vi.mock('node:net', async (importOriginal) => {
  const actual = await importOriginal<typeof import('node:net')>()
  const createServer = ((...args: Parameters<typeof actual.createServer>) => (net.fake?.createServer ? net.fake.createServer() : actual.createServer(...args))) as typeof actual.createServer
  const connect = ((...args: Parameters<typeof actual.connect>) => (net.fake?.connect ? net.fake.connect() : (actual.connect as (...a: unknown[]) => unknown)(...args))) as typeof actual.connect
  return { ...actual, createServer, connect, default: { ...actual, createServer, connect } }
})

// Every artifact watcher the manager opens, and whether it was closed: what a viewer that failed must not keep.
const watchers = vi.hoisted(() => [] as Array<{ closed: boolean }>)
vi.mock('chokidar', async (importOriginal) => {
  const actual = await importOriginal<typeof import('chokidar')>()
  const watch = ((...args: Parameters<typeof actual.watch>) => {
    const watcher = actual.watch(...args)
    const seen = { closed: false }
    watchers.push(seen)
    const close = watcher.close.bind(watcher)
    watcher.close = () => { seen.closed = true; return close() }
    return watcher
  }) as typeof actual.watch
  return { ...actual, watch, default: { ...actual.default, watch } }
})

function fakeChild(): ChildProcess & { exitWith: (code: number) => void } {
  const child = new EventEmitter() as ChildProcess & { exitWith: (code: number) => void }
  Object.assign(child, {
    // No pid: killProcessGroup returns early instead of signalling a real process group.
    pid: undefined,
    stdout: new EventEmitter(),
    stderr: new EventEmitter(),
    exitWith: (code: number) => child.emit('exit', code, null),
  })
  return child
}

function dsh(viewer: NonNullable<InstalledDsh['manifest']['viewer']>): InstalledDsh {
  return {
    id: 'acme/thing', dir: '/i/acme/thing', realDir: '/i/acme/thing', source: '', ref: null, commit: null,
    linked: false, installedAt: 0,
    manifest: { spec: 1, id: 'acme/thing', name: 'Thing', engine: 'claude', viewer },
  }
}

describe('buildViewerUrl', () => {
  it('fills the port and url-encodes the artifact per segment', () => {
    expect(buildViewerUrl('http://127.0.0.1:${port}/?file=${artifact}', 4790, 'models/my part.step'))
      .toBe('http://127.0.0.1:4790/?file=models/my%20part.step')
    expect(buildViewerUrl('http://127.0.0.1:${port}/', 4790, null)).toBe('http://127.0.0.1:4790/')
    expect(buildViewerUrl('http://127.0.0.1:${port}/?file=${artifact}', 1, null)).toBe('http://127.0.0.1:1/?file=')
  })
})

describe('DshViewerManager', () => {
  let manager: DshViewerManager | null = null
  afterEach(async () => { await manager?.stopAll(); manager = null })

  function setup(opts: { portUp?: boolean; now?: () => number } = {}) {
    const spawned: Array<{ child: ReturnType<typeof fakeChild>; env: Record<string, string>; cwd: string }> = []
    const urls: Array<string | null> = []
    manager = new DshViewerManager({
      onUrl: (_agentId, url) => urls.push(url),
      freePort: async () => 4790 + spawned.length,
      waitForPort: async () => opts.portUp ?? true,
      spawn: ((_script: string, o: { cwd: string; env?: Record<string, string> }) => {
        const child = fakeChild()
        spawned.push({ child, env: o.env ?? {}, cwd: o.cwd })
        return child
      }) as typeof import('./shell.js').spawnDshCommand,
      now: opts.now,
    })
    return { spawned, urls }
  }

  it('publishes a URL once the port answers, with the env the contract promises', async () => {
    const { spawned, urls } = setup()
    await manager!.start('a1', dsh({ command: 'toolchain/viewer.sh', url: 'http://127.0.0.1:${port}/' }), '/ws')
    expect(spawned).toHaveLength(1)
    expect(spawned[0].cwd).toBe('/i/acme/thing')
    expect(spawned[0].env).toMatchObject({
      HARNESS_DSH: 'acme/thing', HARNESS_DSH_DIR: '/i/acme/thing', HARNESS_WORKSPACE: '/ws', HARNESS_VIEWER_PORT: '4790',
    })
    expect(urls).toEqual(['http://127.0.0.1:4790/'])
    expect(manager!.url('a1')).toBe('http://127.0.0.1:4790/')
  })

  it('is idempotent for the same agent, DSH and workspace', async () => {
    const { spawned } = setup()
    const d = dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' })
    await manager!.start('a1', d, '/ws')
    await manager!.start('a1', d, '/ws')
    expect(spawned).toHaveLength(1)
  })

  it('forwards only a running viewer on the allocated loopback port', async () => {
    setup()
    expect(manager!.forwardingUrl('a1')).toBeNull()
    await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    expect(manager!.forwardingUrl('a1')).toBe('http://127.0.0.1:4790/')
    await manager!.stop('a1')
    expect(manager!.forwardingUrl('a1')).toBeNull()
  })

  it.each(['http://127.0.0.1:22/', 'http://example.com:${port}/', 'https://127.0.0.1:${port}/'])('does not forward a manifest URL outside its managed HTTP port: %s', async (url) => {
    setup()
    await manager!.start('a1', dsh({ command: 'v', url }), '/ws')
    expect(manager!.url('a1')).not.toBeNull()
    expect(manager!.forwardingUrl('a1')).toBeNull()
  })

  it('republishes when the verdict names an artifact, and only when the URL changes', async () => {
    const { urls } = setup()
    await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/?file=${artifact}' }), '/ws')
    manager!.setVerdictArtifact('a1', 'models/a.step')
    manager!.setVerdictArtifact('a1', 'models/a.step')
    manager!.setVerdictArtifact('a1', null)
    expect(urls).toEqual([
      'http://127.0.0.1:4790/?file=',
      'http://127.0.0.1:4790/?file=models/a.step',
      'http://127.0.0.1:4790/?file=',
    ])
  })

  it('publishes null when the port never answers, and stops the child', async () => {
    const { urls } = setup({ portUp: false })
    await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    expect(urls).toEqual([])
    expect(manager!.url('a1')).toBeNull()
  })

  it('restarts a viewer that exits, then gives up after four exits in a minute', async () => {
    let clock = 0
    const { spawned, urls } = setup({ now: () => clock })
    await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    expect(urls).toEqual(['http://127.0.0.1:4790/'])
    spawned[0].child.exitWith(1)
    expect(urls.at(-1)).toBeNull()
    // The restart is scheduled with a real timer (1s); the fourth exit inside the window gives up.
    for (let i = 0; i < 3; i++) {
      await new Promise((resolve) => setTimeout(resolve, 1_100 * 2 ** i))
      expect(spawned).toHaveLength(i + 2)
      clock += 1_000
      spawned[i + 1].child.exitWith(1)
    }
    await new Promise((resolve) => setTimeout(resolve, 200))
    expect(spawned).toHaveLength(4)
  }, 15_000)

  it('stops publish null and forgets the agent', async () => {
    const { urls } = setup()
    await manager!.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    await manager!.stop('a1')
    expect(urls.at(-1)).toBeNull()
    expect(manager!.url('a1')).toBeNull()
  })

  it('publishes no URL before the port answers, even when the verdict names an artifact meanwhile', async () => {
    // The pane navigates to whatever URL it is handed; a port nobody serves yet is a connection error
    // it never recovers from. A viewer that writes the verdict as it boots used to trigger exactly that.
    const urls: Array<string | null> = []
    let release!: (up: boolean) => void
    let spawnedOne!: () => void
    const spawned = new Promise<void>((resolve) => { spawnedOne = resolve })
    manager = new DshViewerManager({
      onUrl: (_agentId, url) => urls.push(url),
      freePort: async () => 4790,
      waitForPort: () => new Promise((resolve) => { release = resolve }),
      spawn: (() => { spawnedOne(); return fakeChild() }) as unknown as typeof import('./shell.js').spawnDshCommand,
    })
    const starting = manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/?file=${artifact}' }), '/ws')
    await spawned
    manager.setVerdictArtifact('a1', 'deck.md')
    expect(urls).toEqual([])
    expect(manager.url('a1')).toBeNull()
    release(true)
    await starting
    expect(urls).toEqual(['http://127.0.0.1:4790/?file=deck.md'])
  })

  it('opens on the artifact a verdict named before the viewer started, and forgets it once stopped', async () => {
    // The daemon watches the verdict before it starts the viewer, and the watch publishes the verdict
    // already on disk at once: a restored agent's artifact arrived when there was no viewer to tell.
    const { urls } = setup()
    const d = dsh({ command: 'v', url: 'http://127.0.0.1:${port}/?file=${artifact}' })
    manager!.setVerdictArtifact('a1', 'boards/main.board.json')
    await manager!.start('a1', d, '/ws')
    expect(urls).toEqual(['http://127.0.0.1:4790/?file=boards/main.board.json'])
    // a restart in another workspace keeps what the verdict last said
    await manager!.start('a1', d, '/ws2')
    expect(urls.at(-1)).toBe('http://127.0.0.1:4791/?file=boards/main.board.json')
    await manager!.stop('a1')
    await manager!.start('a1', d, '/ws')
    expect(urls.at(-1)).toBe('http://127.0.0.1:4792/?file=')
  })
})

describe('viewer.use (spec 1.1)', () => {
  const pkg: InstalledDsh = {
    id: 'acme/viewer', dir: '/i/acme/viewer', realDir: '/real/acme/viewer', source: '', ref: null, commit: null, linked: false, installedAt: 0,
    manifest: { spec: 1, kind: 'viewer', id: 'acme/viewer', name: 'Viewer', viewer: { command: 'viewer.sh', url: 'http://127.0.0.1:${port}/?file=${artifact}', artifactExtensions: ['.step', '.glb'] } },
  }
  const lookup = (id: string) => (id === 'acme/viewer' ? pkg : undefined)

  it('resolves a used viewer to the package: its command and directory, the harness narrowing url and extensions', () => {
    const own = resolveViewer(dsh({ command: 'mine.sh', url: 'http://127.0.0.1:${port}/' }), lookup)
    expect(own.ok && own.viewer).toEqual({ id: 'acme/thing', dir: '/i/acme/thing', command: 'mine.sh', url: 'http://127.0.0.1:${port}/', artifactExtensions: [] })
    const used = resolveViewer(dsh({ use: 'acme/viewer' }), lookup)
    expect(used.ok && used.viewer).toEqual({ id: 'acme/viewer', dir: '/real/acme/viewer', command: 'viewer.sh', url: 'http://127.0.0.1:${port}/?file=${artifact}', artifactExtensions: ['.step', '.glb'] })
    const narrowed = resolveViewer(dsh({ use: 'acme/viewer', artifactExtensions: ['.step'] }), lookup)
    expect(narrowed.ok && narrowed.viewer.artifactExtensions).toEqual(['.step'])
    const missing = resolveViewer(dsh({ use: 'acme/nope' }), lookup)
    expect(missing.ok).toBe(false)
    expect(!missing.ok && missing.error).toContain('not installed')
    const notViewer = resolveViewer(dsh({ use: 'acme/viewer' }), () => dsh({ command: 'x', url: 'http://127.0.0.1:${port}/' }))
    expect(!notViewer.ok && notViewer.error).toContain('not a viewer package')
  })

  it('launches a used viewer in the package directory, naming both the harness and the viewer in the env', async () => {
    const spawned: Array<{ env: Record<string, string>; cwd: string }> = []
    const urls: Array<string | null> = []
    const manager = new DshViewerManager({
      onUrl: (_a, url) => urls.push(url),
      freePort: async () => 4800,
      waitForPort: async () => true,
      spawn: ((_script: string, o: { cwd: string; env?: Record<string, string> }) => { spawned.push({ env: o.env ?? {}, cwd: o.cwd }); return fakeChild() }) as typeof import('./shell.js').spawnDshCommand,
      lookup,
    })
    try {
      await manager.start('a9', dsh({ use: 'acme/viewer' }), '/ws')
      expect(spawned).toHaveLength(1)
      expect(spawned[0]!.cwd).toBe('/real/acme/viewer')
      expect(spawned[0]!.env).toMatchObject({ HARNESS_DSH: 'acme/thing', HARNESS_DSH_DIR: '/i/acme/thing', HARNESS_VIEWER: 'acme/viewer', HARNESS_VIEWER_DIR: '/real/acme/viewer', HARNESS_WORKSPACE: '/ws', HARNESS_VIEWER_PORT: '4800' })
      expect(urls).toEqual(['http://127.0.0.1:4800/?file='])
      // a harness whose viewer package is missing gets no pane and no crash
      const logs: string[] = []
      const bare = new DshViewerManager({ onUrl: () => undefined, log: (l) => logs.push(l), lookup: () => undefined })
      await bare.start('a10', dsh({ use: 'acme/viewer' }), '/ws')
      expect(bare.url('a10')).toBeNull()
      expect(logs.join(' ')).toContain('not installed')
    } finally {
      await manager.stopAll()
    }
  })

  it('a used viewer with no extensions anywhere follows only the verdict; a harness with no viewer resolves to none', () => {
    const bare: InstalledDsh = { ...pkg, manifest: { spec: 1, kind: 'viewer', id: 'acme/viewer', name: 'Viewer', viewer: { command: 'viewer.sh', url: 'http://127.0.0.1:${port}/' } } }
    const used = resolveViewer(dsh({ use: 'acme/viewer' }), () => bare)
    expect(used.ok && used.viewer.artifactExtensions).toEqual([])
    const none: InstalledDsh = { ...dsh({ command: 'x', url: 'y' }), manifest: { spec: 1, id: 'acme/thing', name: 'Thing', engine: 'claude' } }
    expect(resolveViewer(none, lookup)).toEqual({ ok: false, error: 'acme/thing has no viewer' })
  })
})

describe('the loopback helpers', () => {
  const servers: Server[] = []
  afterEach(async () => {
    net.fake = null
    await Promise.all(servers.splice(0).map((server) => new Promise((resolve) => server.close(resolve))))
  })
  const listen = (port = 0): Promise<number> => new Promise((resolve) => {
    const server = createServer((socket) => socket.end())
    servers.push(server)
    server.listen(port, '127.0.0.1', () => resolve((server.address() as { port: number }).port))
  })

  it('freeLoopbackPort answers a port nothing holds, which can then be listened on', async () => {
    const port = await freeLoopbackPort()
    expect(port).toBeGreaterThan(0)
    expect(await listen(port)).toBe(port)
  })

  it('freeLoopbackPort rejects when loopback cannot be bound', async () => {
    const server = Object.assign(new EventEmitter(), {
      unref: () => undefined,
      listen: () => { queueMicrotask(() => server.emit('error', new Error('listen EADDRNOTAVAIL 127.0.0.1'))) },
    })
    net.fake = { createServer: () => server }
    await expect(freeLoopbackPort()).rejects.toThrow('EADDRNOTAVAIL')
  })

  it('waitForLoopbackPort: yes for a listening port, no once the deadline passes, and yes for one that opens late', async () => {
    const port = await listen()
    expect(await waitForLoopbackPort(port, 1_000)).toBe(true)
    const closed = await freeLoopbackPort()
    expect(await waitForLoopbackPort(closed, 0)).toBe(false)
    const started = Date.now()
    expect(await waitForLoopbackPort(closed, 600)).toBe(false)
    expect(Date.now() - started).toBeGreaterThanOrEqual(500)
    const late = await freeLoopbackPort()
    setTimeout(() => { void listen(late) }, 300)
    expect(await waitForLoopbackPort(late, 5_000)).toBe(true)
  })

  it('waitForLoopbackPort treats a connect that hangs past its second as not yet up, and tries again', async () => {
    const sockets: EventEmitter[] = []
    net.fake = {
      connect: () => {
        const socket = Object.assign(new EventEmitter(), { setTimeout: () => undefined, destroy: () => undefined })
        sockets.push(socket)
        queueMicrotask(() => socket.emit(sockets.length === 1 ? 'timeout' : 'connect'))
        return socket
      },
    }
    expect(await waitForLoopbackPort(1, 5_000)).toBe(true)
    expect(sockets).toHaveLength(2)
  })
})

describe('DshViewerManager, the rest of a viewer\'s life', () => {
  let manager: DshViewerManager | null = null
  let root: string
  beforeEach(() => { root = realpathSync(mkdtempSync(join(tmpdir(), 'dsh-viewer-'))) })
  afterEach(async () => {
    await manager?.stopAll()
    manager = null
    rmSync(root, { recursive: true, force: true })
  })

  const settle = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))

  function setup(deps: Partial<ConstructorParameters<typeof DshViewerManager>[0]> = {}) {
    const spawned: Array<ReturnType<typeof fakeChild>> = []
    const urls: Array<string | null> = []
    const logs: string[] = []
    manager = new DshViewerManager({
      onUrl: (_agentId, url) => urls.push(url),
      log: (line) => logs.push(line),
      freePort: async () => 4790 + spawned.length,
      waitForPort: async () => true,
      spawn: (() => { const child = fakeChild(); spawned.push(child); return child }) as unknown as typeof import('./shell.js').spawnDshCommand,
      ...deps,
    })
    return { spawned, urls, logs, manager }
  }

  it('runs a bare script name as the package\'s own file, the way `harness dsh check` reads it', async () => {
    writeFileSync(join(root, 'viewer.sh'), '#!/bin/sh\n', { mode: 0o755 })
    const scripts: string[] = []
    const { manager } = setup({ spawn: ((script: string) => { scripts.push(script); return fakeChild() }) as unknown as typeof import('./shell.js').spawnDshCommand })
    const own = (command: string): InstalledDsh => ({ ...dsh({ command, url: 'http://127.0.0.1:${port}/' }), dir: root, realDir: root })
    await manager.start('a1', own('viewer.sh'), '/ws')
    await manager.start('a2', own('node viewer.mjs --port $HARNESS_VIEWER_PORT'), '/ws')
    expect(scripts).toEqual([`'${join(root, 'viewer.sh')}'`, 'node viewer.mjs --port $HARNESS_VIEWER_PORT'])
  })

  it('does nothing for a harness with no viewer', async () => {
    const { spawned, logs, manager } = setup()
    await manager.start('a1', { ...dsh({ command: 'v', url: 'u' }), manifest: { spec: 1, id: 'acme/thing', name: 'Thing', engine: 'claude' } }, '/ws')
    expect(spawned).toEqual([])
    expect(logs).toEqual([])
  })

  it('moving to another workspace stops the old viewer and starts a new one', async () => {
    const { spawned, urls, manager } = setup()
    const d = dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' })
    await manager.start('a1', d, '/ws')
    await manager.start('a1', d, '/elsewhere')
    expect(spawned).toHaveLength(2)
    expect(urls).toEqual(['http://127.0.0.1:4790/', null, 'http://127.0.0.1:4791/'])
    await manager.stop('never-started')
  })

  it('logs when no port is free, whatever the failure was, and starts nothing', async () => {
    const d = dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' })
    const { spawned, urls, logs, manager } = setup({ freePort: async () => { throw new Error('EMFILE') } })
    await manager.start('a1', d, '/ws')
    const other = new DshViewerManager({ onUrl: () => undefined, log: (line) => logs.push(line), freePort: () => Promise.reject('no ports left'), spawn: () => { throw new Error('never') } })
    await other.start('a2', d, '/ws')
    expect(spawned).toEqual([])
    expect(urls).toEqual([])
    expect(logs).toEqual(['[dsh] acme/thing viewer: no free port · EMFILE', '[dsh] acme/thing viewer: no free port · no ports left'])
  })

  it('a stop while the port is being found, or while the viewer comes up, publishes nothing', async () => {
    let freePort!: (port: number) => void
    const { spawned, urls, manager } = setup({ freePort: () => new Promise((resolve) => { freePort = resolve }) })
    const d = dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' })
    const first = manager.start('a1', d, '/ws')
    await settle(0)
    await manager.stop('a1')
    freePort(4790)
    await first
    expect(spawned).toEqual([])

    let up!: (ok: boolean) => void
    const second = setup({ waitForPort: () => new Promise((resolve) => { up = resolve }) })
    const starting = second.manager.start('a1', d, '/ws')
    await vi.waitFor(() => expect(second.spawned).toHaveLength(1))
    await second.manager.stop('a1')
    up(true)
    await starting
    expect(second.urls).toEqual([])
    expect(urls).toEqual([])
  })

  it('logs what the viewer prints, up to forty lines, without blank lines or zsh noise, and a failure to start', async () => {
    const { spawned, logs, manager } = setup()
    await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    const printed = Array.from({ length: 45 }, (_, i) => `line ${i}`)
    spawned[0].stdout!.emit('data', Buffer.from(`\n${printed.slice(0, 20).join('\n')}\n   \n`))
    spawned[0].stderr!.emit('data', Buffer.from(`zsh: can't change option: zle\n${printed.slice(20).join('\n')}\n`))
    spawned[0].emit('error', new Error('spawn EACCES'))
    const viewerLines = logs.filter((line) => line.startsWith('[dsh] acme/thing viewer · '))
    expect(viewerLines).toEqual(printed.slice(0, 40).map((line) => `[dsh] acme/thing viewer · ${line}`))
    expect(logs).toContain('[dsh] acme/thing viewer could not start · spawn EACCES')
  })

  it('an exit after a stop is ignored; an exit during a stop publishes null and restarts nothing', async () => {
    const { spawned, urls, logs, manager } = setup()
    const workspace = join(root, 'ws')
    mkdirSync(workspace)
    await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/', artifactExtensions: ['.step'] }), workspace)
    // the stop is waiting on the artifact watcher to close when the child goes
    const stopping = manager.stop('a1')
    spawned[0].emit('exit', null, 'SIGTERM')
    await stopping
    spawned[0].exitWith(0)
    await settle(1_200)
    expect(spawned).toHaveLength(1)
    expect(urls).toEqual(['http://127.0.0.1:4790/', null])
    expect(logs.filter((line) => line.includes('restarting'))).toEqual([])
  })

  it('a viewer killed by a signal is restarted, and the log says which signal', async () => {
    const { spawned, logs, manager } = setup({ now: undefined })
    await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    spawned[0].emit('exit', null, 'SIGSEGV')
    expect(logs.at(-1)).toBe('[dsh] acme/thing viewer exited SIGSEGV · restarting in 1000ms')
    await vi.waitFor(() => expect(spawned).toHaveLength(2), { timeout: 3_000 })
  })

  it('gives up after four exits inside a minute, naming how the last one ended', async () => {
    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
    try {
      let clock = 0
      const { spawned, logs, manager } = setup({ now: () => clock })
      await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
      for (let i = 0; i < 3; i++) {
        spawned[i].emit('exit', null, 'SIGKILL')
        await vi.advanceTimersByTimeAsync(1_000 * 2 ** i)
        expect(spawned).toHaveLength(i + 2)
        clock += 1_000
      }
      spawned[3].emit('exit', null, 'SIGKILL')
      expect(logs.at(-1)).toBe('[dsh] acme/thing viewer exited SIGKILL 4 times in a minute · giving up')
      await vi.advanceTimersByTimeAsync(60_000)
      expect(spawned).toHaveLength(4)
    } finally {
      vi.useRealTimers()
    }
  })

  it('a viewer that never listens is logged and stopped', async () => {
    const { logs, urls, manager } = setup({ waitForPort: async () => false })
    await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/' }), '/ws')
    expect(urls).toEqual([])
    expect(logs).toContain('[dsh] acme/thing viewer did not listen on 4790 within 60s')
  })

  describe('a viewer whose start failed or timed out keeps nothing running', () => {
    const watched = () => dsh({ command: 'v', url: 'http://127.0.0.1:${port}/', artifactExtensions: ['.step'] })
    let workspace: string
    beforeEach(() => {
      watchers.length = 0
      workspace = join(root, 'ws')
      mkdirSync(workspace)
    })

    it('on Windows without Git Bash: says the viewer could not start, closes its watch, and is not tried again on every attach', async () => {
      let tries = 0
      const noGitBash = ((script: string, opts: Parameters<typeof spawnDshCommand>[1]) => {
        tries++
        return spawnDshCommand(script, { ...opts, host: { platform: 'win32', gitBash: () => null } })
      }) as typeof spawnDshCommand
      const { logs, urls, manager } = setup({ spawn: noGitBash })
      await manager.start('a1', watched(), workspace)
      expect(logs).toContain("[dsh] acme/thing viewer could not start · This harness's viewer needs Git Bash on Windows, and it was not found. Install Git for Windows from https://git-scm.com/download/win (or run: winget install --id Git.Git -e), then try again.")
      expect(watchers).toHaveLength(1)
      expect(watchers[0].closed).toBe(true)
      // The agents' scans attach every live agent again; the same viewer that just failed is not started each time.
      await manager.start('a1', watched(), workspace)
      expect(tries).toBe(1)
      // A stop, as when the agent restarts, lets it try again.
      await manager.stop('a1')
      await manager.start('a1', watched(), workspace)
      expect(tries).toBe(2)
      expect(urls).toEqual([])
    })

    it('a viewer that never listens is stopped for good: not restarted, its watch closed', async () => {
      const { spawned, logs, manager } = setup({ waitForPort: async () => false })
      await manager.start('a1', watched(), workspace)
      expect(logs).toContain('[dsh] acme/thing viewer did not listen on 4790 within 60s')
      // The stop ends the child; its exit is not a crash to restart.
      spawned[0].emit('exit', null, 'SIGTERM')
      await settle(1_200)
      expect(spawned).toHaveLength(1)
      expect(logs.filter((line) => line.includes('restarting'))).toEqual([])
      expect(watchers[0].closed).toBe(true)
      await manager.start('a1', watched(), workspace)
      expect(spawned).toHaveLength(1)
    })

    it('a viewer whose process could not be started, or that found no port, closes its watch', async () => {
      const failing = setup({ waitForPort: async () => { failing.spawned[0].emit('error', new Error('spawn EACCES')); return false } })
      await failing.manager.start('a1', watched(), workspace)
      expect(failing.logs).toContain('[dsh] acme/thing viewer could not start · spawn EACCES')
      expect(watchers[0].closed).toBe(true)
      const noPort = setup({ freePort: async () => { throw new Error('EMFILE') } })
      await noPort.manager.start('a2', watched(), workspace)
      expect(watchers[1].closed).toBe(true)
    })
  })

  it('follows the newest artifact as files change, in a workspace whose own path has an ignored name in it', async () => {
    // `build` is a folder name the artifact scan skips INSIDE a workspace; a workspace that itself lives
    // under a build/ folder used to have every change refused, so the pane never followed a new file.
    const workspace = join(root, 'build', 'ws')
    mkdirSync(join(workspace, 'models'), { recursive: true })
    const at = (rel: string, seconds: number): void => {
      mkdirSync(join(workspace, rel, '..'), { recursive: true })
      writeFileSync(join(workspace, rel), rel)
      utimesSync(join(workspace, rel), seconds, seconds)
    }
    at('models/old.step', 1_000)
    const { urls, logs, manager } = setup()
    await manager.start('a1', dsh({ command: 'v', url: 'http://127.0.0.1:${port}/?file=${artifact}', artifactExtensions: ['.step'] }), workspace)
    expect(urls).toEqual(['http://127.0.0.1:4790/?file=models/old.step'])
    await settle(300)

    at('models/new.step', 2_000)
    await vi.waitFor(() => expect(urls.at(-1)).toBe('http://127.0.0.1:4790/?file=models/new.step'), { timeout: 5_000 })
    // not artifacts, or not where artifacts are looked for: nothing changes
    at('notes.txt', 3_000)
    at('node_modules/lib/newest.step', 3_000)
    at('.cache/newest.step', 3_000)
    // the same newest file touched again, twice inside the debounce: one rescan, same answer
    at('models/new.step', 2_001)
    at('models/new.step', 2_002)
    await settle(900)
    expect(urls).toEqual(['http://127.0.0.1:4790/?file=models/old.step', 'http://127.0.0.1:4790/?file=models/new.step'])

    rmSync(join(workspace, 'models', 'new.step'))
    await vi.waitFor(() => expect(urls.at(-1)).toBe('http://127.0.0.1:4790/?file=models/old.step'), { timeout: 5_000 })
    rmSync(join(workspace, 'models', 'old.step'))
    await vi.waitFor(() => expect(urls.at(-1)).toBe('http://127.0.0.1:4790/?file='), { timeout: 5_000 })

    const inner = (manager as unknown as { states: Map<string, { watcher: EventEmitter }> }).states.get('a1')!.watcher
    inner.emit('error', new Error('EMFILE'))
    inner.emit('error', 'lost')
    expect(logs.filter((line) => line.includes('artifact watch error'))).toEqual(['[dsh] artifact watch error · EMFILE', '[dsh] artifact watch error · lost'])

    // a stop with a rescan still pending cancels it, and a watcher that fails to close does not fail the stop
    const state = (manager as unknown as { states: Map<string, { rescanTimer: unknown; watcher: { close: () => Promise<void> } }> }).states.get('a1')!
    const close = state.watcher.close.bind(state.watcher)
    state.watcher.close = async () => { await close(); throw new Error('close failed') }
    at('models/newest.step', 5_000)
    await vi.waitFor(() => expect(state.rescanTimer).not.toBeNull(), { timeout: 5_000 })
    await manager.stop('a1')
    await settle(500)
    expect(urls.at(-1)).toBeNull()
    expect(urls.filter((url) => url?.endsWith('newest.step'))).toEqual([])
  }, 20_000)

  it('runs a real viewer through the user\'s shell, on the port it was given, and stops it', async () => {
    const urls: Array<string | null> = []
    manager = new DshViewerManager({ onUrl: (_agentId, url) => urls.push(url) })
    const server = `require('http').createServer((q, s) => s.end(process.env.HARNESS_VIEWER + ' ' + process.env.HARNESS_WORKSPACE)).listen(+process.env.HARNESS_VIEWER_PORT, '127.0.0.1')`
    const d: InstalledDsh = { ...dsh({ command: `'${process.execPath}' -e "${server}"`, url: 'http://127.0.0.1:${port}/' }), dir: root, realDir: root }
    await manager.start('a1', d, root)
    const url = urls.at(-1)!
    expect(url).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/$/)
    expect(await (await fetch(url)).text()).toBe(`acme/thing ${root}`)
    await manager.stop('a1')
    await vi.waitFor(async () => { await expect(fetch(url)).rejects.toThrow() }, { timeout: 5_000 })
    expect(urls.at(-1)).toBeNull()
  }, 30_000)
})