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.

32.9 KB
Raw Blame
import { chmodSync } from 'fs'
import { appendFile, mkdtemp, open, rm, writeFile } from 'fs/promises'
import { tmpdir } from 'os'
import { join } from 'path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { Watcher, type HistoryEvent, type LineEvent, type RewrittenEvent } from './watcher.js'

const cleanup: string[] = []

/** Waits for what a timer delivers — a released hold's read, an expired hold — however slow the machine. */
const until = async (what: string, test: () => boolean, ms = 10_000): Promise<void> => {
  const deadline = Date.now() + ms
  while (!test()) {
    if (Date.now() > deadline) throw new Error(`timed out waiting for ${what}`)
    await new Promise((resolve) => setTimeout(resolve, 20))
  }
}

afterEach(async () => {
  await Promise.all(cleanup.splice(0).map((path) => rm(path, { recursive: true, force: true })))
})

describe('Watcher.pollAll', () => {
  it('drains every registered transcript to EOF without waiting for chokidar', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"n":1}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
    await appendFile(transcriptPath, '{"n":2}\n{"n":3}\n')

    await watcher.pollAll()

    expect(lines).toEqual(['{"n":2}', '{"n":3}'])
    await watcher.stop()
  })

  it('replays only the changed Cursor suffix when a trailing turn sentinel is replaced', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-cursor-watcher-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    const user = '{"role":"user","message":{"content":[{"type":"text","text":"hi"}]}}'
    const assistant = '{"role":"assistant","message":{"content":[{"type":"text","text":"hello"}]}}'
    const ended = '{"type":"turn_ended","status":"completed"}'
    await writeFile(transcriptPath, `${user}\n${ended}\n`)
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    await watcher.addSession({ sessionId: 's1', engine: 'cursor', transcriptPath })

    await writeFile(transcriptPath, `${user}\n${assistant}\n`)
    await watcher.pollSession('s1')
    await appendFile(transcriptPath, `${ended}\n`)
    await watcher.pollSession('s1')

    expect(lines).toEqual([assistant, ended])
    await watcher.stop()
  })

  it('can emit an existing Cursor transcript from the start for first-turn discovery', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-cursor-first-turn-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"n":1}\n{"n":2}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))

    await watcher.addSession(
      { sessionId: 's1', engine: 'cursor', transcriptPath },
      { fromStart: true },
    )
    await watcher.pollSession('s1')

    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('emits a file-backed transcript from the start when nothing was folded', async () => {
    // The generic byte-tail branch, which every JSONL engine uses. `fromStart` was only ever covered for
    // cursor, and the gap was live: pi's agent is discovered the moment the engine starts but its session
    // file only materialises once the first answer is written, so the re-attach that finally brought the
    // path tailed from the file's END and the whole first turn — prompt, tools and answer — was read as
    // history that never reached web or device.
    const dir = await mkdtemp(join(tmpdir(), 'machine-first-turn-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"a":1}\n{"a":2}\n{"a":3}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    const history: string[][] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (batch: HistoryEvent) => history.push(batch.lines.map((l) => l.text)))

    await watcher.addSession({ sessionId: 'p1', engine: 'pi', transcriptPath }, { fromStart: true })
    await watcher.pollSession('p1')

    // Everything that was on disk when the tail was placed arrives as ONE history batch, so the
    // consumer can tell a prompt already answered from the one turn that may still be running; what
    // is appended afterwards is live, line by line.
    expect(history).toEqual([['{"a":1}', '{"a":2}', '{"a":3}']])
    expect(lines).toEqual([])
    await appendFile(transcriptPath, '{"a":4}\n')
    await watcher.pollSession('p1')
    expect(lines).toEqual(['{"a":4}'])
    expect(history).toHaveLength(1)
    await watcher.stop()
  })

  it('reads a file that shrank under it as history, not as a conversation happening now', async () => {
    // The untrusted-producer version of the repair case below: a transcript rewritten in place by
    // something that never called setTail. The old behaviour re-emitted the whole file as live — on
    // prod that was one agent credited with 42 turns in a single second.
    const dir = await mkdtemp(join(tmpdir(), 'machine-shrink-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"t":1}\n{"t":2}\n{"t":3}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    const history: string[][] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (batch: HistoryEvent) => history.push(batch.lines.map((l) => l.text)))

    await watcher.addSession({ sessionId: 'x1', engine: 'pi', transcriptPath })
    await watcher.pollSession('x1')
    expect(lines).toEqual([])

    await writeFile(transcriptPath, '{"t":1}\n{"t":2}\n') // shorter than the tail's cursor
    await watcher.pollSession('x1')
    expect(history).toEqual([['{"t":1}', '{"t":2}']])
    expect(lines).toEqual([])

    await appendFile(transcriptPath, '{"t":4}\n')
    await watcher.pollSession('x1')
    expect(lines).toEqual(['{"t":4}'])
    expect(history).toHaveLength(1)
    await watcher.stop()
  })

  it('splits one chunk into its historical prefix and its live rest', async () => {
    // A `fromStart` tail placed on a file that grows before the first read: the bytes below the
    // cursor's placement are history, the bytes appended since are not, and they arrive in the
    // same read. The split is by byte position, so a multi-byte line cannot shift it.
    const dir = await mkdtemp(join(tmpdir(), 'machine-split-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"h":"xin chào"}\n{"h":2}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    const history: string[][] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (batch: HistoryEvent) => history.push(batch.lines.map((l) => l.text)))

    await watcher.addSession({ sessionId: 's1', engine: 'pi', transcriptPath }, { fromStart: true })
    await appendFile(transcriptPath, '{"live":3}\n')
    await watcher.pollSession('s1')

    expect(history).toEqual([['{"h":"xin chào"}', '{"h":2}']])
    expect(lines).toEqual(['{"live":3}'])
    await watcher.stop()
  })

  it('still starts at the end by default, so a resumed session does not replay', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-resume-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"old":1}\n{"old":2}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))

    await watcher.addSession({ sessionId: 'p2', engine: 'pi', transcriptPath })
    await watcher.pollSession('p2')
    expect(lines).toEqual([])

    await writeFile(transcriptPath, '{"old":1}\n{"old":2}\n{"new":3}\n')
    await watcher.pollSession('p2')
    expect(lines).toEqual(['{"new":3}'])
    await watcher.stop()
  })

  it('does not replay a rollout repaired (shrunk) in place once the tail is re-synced', async () => {
    // The Codex resume reasoning-id repair rewrites the rollout to a SHORTER file before the engine
    // relaunches. Without moving the tail, the next read sees size < offset, treats the shrink as a
    // truncation, resets to 0, and re-emits the whole conversation into the live normalizer. setTail
    // pins the offset to the repaired length so only the resumed turn is read.
    const dir = await mkdtemp(join(tmpdir(), 'machine-repair-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"meta":1}\n{"reasoning":"msg_bad_id"}\n{"answer":1}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))

    await watcher.addSession({ sessionId: 'c1', engine: 'codex', transcriptPath })
    await watcher.pollSession('c1')
    expect(lines).toEqual([])

    const repaired = '{"meta":1}\n{"reasoning":""}\n{"answer":1}\n' // shorter: the stale id was stripped
    await writeFile(transcriptPath, repaired)
    watcher.setTail('c1', Buffer.byteLength(repaired))
    await watcher.pollSession('c1')
    expect(lines).toEqual([]) // the repaired history is NOT re-emitted

    await appendFile(transcriptPath, '{"resumed":2}\n')
    await watcher.pollSession('c1')
    expect(lines).toEqual(['{"resumed":2}']) // only the resumed engine's new turn
    await watcher.stop()
  })

  it('setTail is a harmless no-op for a session that is not registered', async () => {
    // The post-reboot restore path repairs the rollout before it re-attaches the tail, so there is
    // nothing to move — this must not throw.
    const watcher = new Watcher()
    expect(() => watcher.setTail('never-registered', 123)).not.toThrow()
    await watcher.stop()
  })
})

describe('Watcher.addSession fromOffset', () => {
  const setup = async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-offset-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    const watcher = new Watcher()
    const lines: string[] = []
    const history: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (event: HistoryEvent) => history.push(...event.lines.map((line) => line.text)))
    return { transcriptPath, watcher, lines, history }
  }

  it('tails from where the attach stopped reading, so a record written meanwhile is streamed live', async () => {
    const { transcriptPath, watcher, lines, history } = await setup()
    await writeFile(transcriptPath, '{"n":1}\n{"n":2}\n')
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath }, { fromOffset: 8 })
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":2}'])
    expect(history).toEqual([])
    await watcher.stop()
  })

  it('starts at the new end when the file shrank since the attach read it', async () => {
    const { transcriptPath, watcher, lines } = await setup()
    await writeFile(transcriptPath, '{"n":1}\n')
    await watcher.addSession({ sessionId: 's1', engine: 'claude', transcriptPath }, { fromOffset: 500 })
    await appendFile(transcriptPath, '{"n":2}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":2}'])
    await watcher.stop()
  })

  it('lets fromStart win, reading the existing content as history', async () => {
    const { transcriptPath, watcher, lines, history } = await setup()
    await writeFile(transcriptPath, '{"n":1}\n{"n":2}\n')
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath }, { fromStart: true, fromOffset: 8 })
    await watcher.pollSession('s1')
    expect(history).toEqual(['{"n":1}', '{"n":2}'])
    expect(lines).toEqual([])
    await watcher.stop()
  })
})

describe('Watcher.hold and release', () => {
  const tailed = async (content: string | Buffer) => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-hold-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, content)
    const watcher = new Watcher()
    const lines: string[] = []
    const history: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (event: HistoryEvent) => history.push(...event.lines.map((line) => line.text)))
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
    return { transcriptPath, watcher, lines, history }
  }

  it('stops delivery where the next line starts, a carried partial line included, and resumes from a given byte', async () => {
    const { transcriptPath, watcher, lines } = await tailed('{"n":1}\n')
    await appendFile(transcriptPath, '{"n":2}\n{"n":')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":2}'])
    const hold = (await watcher.hold('s1', transcriptPath))!
    expect(hold.offset).toBe(16)
    await appendFile(transcriptPath, '3}\n{"n":4}\n')
    await new Promise((resolve) => setTimeout(resolve, 60))
    expect(lines).toEqual(['{"n":2}'])
    hold.release(24)
    hold.release(0)
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":2}', '{"n":4}'])
    await watcher.stop()
  })

  it('counts a partial line in bytes, a character split between two reads included, and decodes it whole', async () => {
    const { transcriptPath, watcher, lines } = await tailed('{"n":1}\n')
    const accented = Buffer.from('{"a":"é漢"}\n')
    await appendFile(transcriptPath, accented.subarray(0, 9))
    await watcher.pollSession('s1')
    expect(lines).toEqual([])
    const hold = (await watcher.hold('s1', transcriptPath))!
    expect(hold.offset).toBe(8)
    hold.release()
    await appendFile(transcriptPath, accented.subarray(9))
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"a":"é漢"}'])
    await watcher.stop()
  })

  it('keeps its own position when released without one, and delivers what arrived while held', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    const hold = (await watcher.hold('s1', transcriptPath))!
    await appendFile(transcriptPath, '{"n":1}\n')
    hold.release()
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}'])
    await watcher.stop()
  })

  it('stays held until every hold is released, and a drain waits for that', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    const first = (await watcher.hold('s1', transcriptPath))!
    const second = (await watcher.hold('s1', transcriptPath))!
    await appendFile(transcriptPath, '{"n":1}\n')
    let drained = false
    const drain = watcher.pollSession('s1').then(() => { drained = true })
    first.release()
    await new Promise((resolve) => setTimeout(resolve, 60))
    expect(drained).toBe(false)
    expect(lines).toEqual([])
    second.release()
    await drain
    expect(lines).toEqual(['{"n":1}'])
    await watcher.stop()
  })

  it('lets go of a hold an attach never releases, says so, and lets a late release change nothing', async () => {
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    try {
      const { transcriptPath, watcher, lines } = await tailed('')
      const hold = (await watcher.hold('s1', transcriptPath, 40))!
      expect(hold.expired).toBe(false)
      await appendFile(transcriptPath, '{"n":1}\n')
      await until('the hold to let go and its read to deliver', () => lines.length > 0)
      expect(warn).toHaveBeenCalledOnce()
      expect(hold.expired).toBe(true)
      expect(lines).toEqual(['{"n":1}'])
      // The attach finishing late: where its read stopped is behind what was delivered since.
      hold.release(0)
      await appendFile(transcriptPath, '{"n":2}\n')
      await watcher.pollSession('s1')
      expect(lines).toEqual(['{"n":1}', '{"n":2}'])
      await watcher.stop()
    } finally { warn.mockRestore() }
  })

  it('keeps the position a repair moved the tail to while it was held', async () => {
    const { transcriptPath, watcher, lines, history } = await tailed(`{"n":1,"r":"${'x'.repeat(200)}"}\n{"n":2}\n`)
    const hold = (await watcher.hold('s1', transcriptPath))!
    // The Codex resume repair shrinks the rollout in place and pins the tail to its new end.
    const repaired = '{"n":1}\n{"n":2}\n'
    await writeFile(transcriptPath, repaired)
    watcher.setTail('s1', Buffer.byteLength(repaired))
    await appendFile(transcriptPath, '{"n":3}\n')
    hold.release(hold.offset)
    await watcher.pollSession('s1')
    expect({ lines, history }).toEqual({ lines: ['{"n":3}'], history: [] })
    await watcher.stop()
  })

  it('drains through a hold that lands during its read, once the hold lets go', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    await appendFile(transcriptPath, '{"n":1}\n')
    const reading = watcher.pollAll()
    let drained = false
    // A drain asked for while that read runs (the Stop hook's), then a reset attach takes the tail.
    const drain = watcher.pollSession('s1').then(() => { drained = true })
    const held = watcher.hold('s1', transcriptPath)
    await appendFile(transcriptPath, '{"n":2}\n')
    await reading
    const hold = (await held)!
    await new Promise((resolve) => setTimeout(resolve, 60))
    expect(drained).toBe(false)
    hold.release()
    await drain
    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('ends a drain waiting on a hold when the session is removed, or the watcher stops', async () => {
    for (const end of ['remove', 'stop'] as const) {
      const { transcriptPath, watcher } = await tailed('')
      const hold = (await watcher.hold('s1', transcriptPath))!
      const drain = watcher.pollSession('s1')
      if (end === 'remove') await watcher.removeSession('s1')
      else await watcher.stop()
      await drain
      hold.release()
      await watcher.stop()
    }
  })

  it('says which file it tails for a session', async () => {
    const { transcriptPath, watcher } = await tailed('')
    expect(watcher.tails('s1', transcriptPath)).toBe(true)
    expect(watcher.tails('s1', `${transcriptPath}.other`)).toBe(false)
    expect(watcher.tails('nobody', transcriptPath)).toBe(false)
    await watcher.removeSession('s1')
    expect(watcher.tails('s1', transcriptPath)).toBe(false)
    await watcher.stop()
  })

  it('stops a read in progress that more data would keep going, at the hold', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    await appendFile(transcriptPath, '{"n":1}\n')
    const reading = watcher.pollAll()
    const held = watcher.hold('s1', transcriptPath)
    // Asks for another read while the first is running: without the hold the read would loop on.
    const another = watcher.pollAll()
    await appendFile(transcriptPath, '{"n":2}\n')
    await reading
    const hold = (await held)!
    await another
    expect(lines).toEqual(['{"n":1}'])
    hold.release()
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('reads again when more is asked for during a read', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    await appendFile(transcriptPath, '{"n":1}\n')
    const reading = watcher.pollSession('s1')
    const another = watcher.pollAll()
    await appendFile(transcriptPath, '{"n":2}\n')
    await reading
    await another
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('skips blank lines and line endings in a live read', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    await appendFile(transcriptPath, '\n  \r\n{"n":1}\r\n\n{"n":2}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('waits out a read in progress, and that read stops at the hold', async () => {
    const { transcriptPath, watcher, lines } = await tailed('')
    await appendFile(transcriptPath, '{"n":1}\n')
    const reading = watcher.pollAll()
    const held = watcher.hold('s1', transcriptPath)
    await appendFile(transcriptPath, '{"n":2}\n')
    await reading
    const hold = (await held)!
    // The read in progress stops at the hold: everything before the hold's offset has been delivered,
    // and nothing after it. Where that is depends on whether the read had already reached the second
    // line (on a slow disk it has; CI saw it once), and either way nothing is lost or sent twice.
    expect([8, 16]).toContain(hold.offset)
    expect(Buffer.byteLength(lines.map((line) => `${line}\n`).join(''))).toBe(hold.offset)
    hold.release()
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}', '{"n":2}'])
    await watcher.stop()
  })

  it('cancels a read that was only scheduled, and reads it after release', async () => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-hold-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, '{"n":1}\n{"n":2}\n')
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath }, { fromOffset: 8 })
    const hold = (await watcher.hold('s1', transcriptPath))!
    expect(hold.offset).toBe(8)
    await new Promise((resolve) => setTimeout(resolve, 80))
    expect(lines).toEqual([])
    hold.release()
    await until('the read the release schedules', () => lines.length > 0)
    expect(lines).toEqual(['{"n":2}'])
    await watcher.stop()
  })

  it('holds nothing for a session it does not tail, or for another file than the one it tails', async () => {
    const { transcriptPath, watcher } = await tailed('')
    expect(await watcher.hold('nobody', transcriptPath)).toBeNull()
    expect(await watcher.hold('s1', `${transcriptPath}.other`)).toBeNull()
    await watcher.stop()
  })

  it('releases quietly after the session was removed', async () => {
    const { transcriptPath, watcher } = await tailed('')
    const hold = (await watcher.hold('s1', transcriptPath))!
    await watcher.removeSession('s1')
    expect(() => hold.release(5)).not.toThrow()
    await watcher.stop()
  })
})

describe('Watcher, at its edges', () => {
  const fresh = async (content = '') => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-edges-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, content)
    const watcher = new Watcher()
    const lines: string[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    return { dir, transcriptPath, watcher, lines }
  }
  // Private state, read only to see what the file system's events did.
  const internals = (watcher: Watcher) => watcher as unknown as {
    watcher: { emit(event: string, ...args: unknown[]): boolean } | null
    files: Map<string, { pending: boolean }>
    readNew(filePath: string): Promise<void>
  }

  it('follows what chokidar reports from start to stop, and logs the changes the turn engines ride on', async () => {
    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    try {
      const { dir, transcriptPath, watcher, lines } = await fresh()
      await watcher.addSession({ sessionId: 's1', engine: 'commandcode', transcriptPath })
      watcher.start()
      watcher.start()
      const second = join(dir, 'second.jsonl')
      await writeFile(second, '')
      await watcher.addSession({ sessionId: 's2', engine: 'codex', transcriptPath: second })
      await appendFile(transcriptPath, '{"n":1}\n')
      await until('the change to be read', () => lines.includes('{"n":1}'))
      expect(log.mock.calls.some(([line]) => String(line).startsWith('[watcher] change commandcode s1'))).toBe(true)
      await appendFile(second, '{"n":2}\n')
      await until('the second file to be read', () => lines.includes('{"n":2}'))
      expect(log.mock.calls.some(([line]) => String(line).startsWith('[watcher] change codex'))).toBe(false)
      await rm(transcriptPath)
      await until('the unlink to be noticed', () => internals(watcher).files.get(transcriptPath)?.pending === true)
      // Events for a file no longer tailed are dropped, however often they come.
      internals(watcher).watcher!.emit('change', join(dir, 'gone.jsonl'), undefined)
      internals(watcher).watcher!.emit('change', join(dir, 'gone.jsonl'), undefined)
      internals(watcher).watcher!.emit('unlink', join(dir, 'gone.jsonl'))
      internals(watcher).watcher!.emit('error', new Error('EMFILE'))
      expect(error).toHaveBeenCalledWith('[watcher] error:', expect.any(Error))
      await watcher.stop()
      await watcher.stop()
      // Started before anything is tailed: there is nothing to watch yet.
      const idle = new Watcher()
      idle.start()
      await idle.stop()
    } finally {
      log.mockRestore()
      error.mockRestore()
    }
  })

  it('moves a session to its new file, and starts a missing one from nothing', async () => {
    const { dir, transcriptPath, watcher, lines } = await fresh('{"n":1}\n')
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
    const moved = join(dir, 'moved.jsonl')
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath: moved })
    expect(watcher.tails('s1', transcriptPath)).toBe(false)
    expect(watcher.tails('s1', moved)).toBe(true)
    await writeFile(moved, '{"n":2}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":2}'])
    await watcher.stop()
  })

  it('hands a file to the session added last, and lets a session that lost it go quietly', async () => {
    const { transcriptPath, watcher, lines } = await fresh()
    const seen: string[] = []
    watcher.on('line', (event: LineEvent) => seen.push(event.sessionId))
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
    await watcher.addSession({ sessionId: 's2', engine: 'codex', transcriptPath })
    await appendFile(transcriptPath, '{"n":1}\n')
    await watcher.pollSession('s2')
    expect(seen).toEqual(['s2'])
    await watcher.removeSession('s2')
    // s1 still names the file, which is no longer tailed.
    watcher.setTail('s1', 0)
    await watcher.pollSession('s1')
    expect(await watcher.hold('s1', transcriptPath)).toBeNull()
    expect(lines).toEqual(['{"n":1}'])
    await watcher.removeSession('nobody')
    await watcher.pollSession('nobody')
    await watcher.stop()
  })

  it('drops a read that was only scheduled when the tail is moved or the session removed', async () => {
    for (const end of ['setTail', 'remove'] as const) {
      const { transcriptPath, watcher, lines } = await fresh('{"n":1}\n{"n":2}\n')
      await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath }, { fromOffset: 0 })
      if (end === 'setTail') watcher.setTail('s1', 16)
      else await watcher.removeSession('s1')
      await new Promise((resolve) => setTimeout(resolve, 80))
      expect(lines).toEqual([])
      await watcher.stop()
    }
  })

  it('skips a read of a file it does not tail, one that is gone, and one it may not open', async () => {
    const error = vi.spyOn(console, 'error').mockImplementation(() => {})
    try {
      const { transcriptPath, watcher, lines } = await fresh('{"n":1}\n')
      await internals(watcher).readNew('/nowhere.jsonl')
      await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
      await appendFile(transcriptPath, '{"n":2}\n')
      chmodSync(transcriptPath, 0o000)
      await watcher.pollSession('s1')
      expect(error).toHaveBeenCalledOnce()
      expect(String(error.mock.calls[0][0])).toContain('[watcher] read failed (session.jsonl)')
      chmodSync(transcriptPath, 0o600)
      await rm(transcriptPath)
      await watcher.pollSession('s1')
      expect(lines).toEqual([])
      await watcher.stop()
    } finally { error.mockRestore() }
  })

  it('reads Cursor transcripts whole: none to begin with, a last line not yet ended, and one that vanishes', async () => {
    const { transcriptPath, watcher, lines } = await fresh()
    await rm(transcriptPath)
    await watcher.addSession({ sessionId: 's1', engine: 'cursor', transcriptPath })
    await writeFile(transcriptPath, '{"c":1}\n\n{"c":2}\r\n{"c":3')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"c":1}', '{"c":2}'])
    await appendFile(transcriptPath, '}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"c":1}', '{"c":2}', '{"c":3}'])
    await rm(transcriptPath)
    await watcher.pollSession('s1')
    expect(lines).toHaveLength(3)
    await watcher.stop()
  })
})

describe('Watcher, reading a backlog', () => {
  const backlog = async (options: ConstructorParameters<typeof Watcher>[0], content = '') => {
    const dir = await mkdtemp(join(tmpdir(), 'machine-watcher-backlog-'))
    cleanup.push(dir)
    const transcriptPath = join(dir, 'session.jsonl')
    await writeFile(transcriptPath, content)
    const watcher = new Watcher(options)
    const lines: string[] = []
    const history: string[] = []
    const rewritten: RewrittenEvent[] = []
    watcher.on('line', (event: LineEvent) => lines.push(event.text))
    watcher.on('history', (event: HistoryEvent) => history.push(...event.lines.map((line) => line.text)))
    watcher.on('rewritten', (event: RewrittenEvent) => rewritten.push(event))
    await watcher.addSession({ sessionId: 's1', engine: 'codex', transcriptPath })
    return { transcriptPath, watcher, lines, history, rewritten }
  }
  const records = [
    '{"n":1}', '{"n":2,"text":"漢字 📘 across a chunk"}', `{"n":3,"long":"${'x'.repeat(200)}"}`, '{"n":4}', '', '   ', '{"n":5}',
  ]

  it('reads what fell behind a chunk at a time: lines and characters split between chunks, a line longer than many', async () => {
    for (const chunk of [1, 3, 16, 64, 1 << 20]) {
      const { transcriptPath, watcher, lines } = await backlog({ readChunkBytes: chunk })
      await appendFile(transcriptPath, records.join('\r\n') + '\r\n{"n":6, still')
      await watcher.pollSession('s1')
      expect(lines, `chunks of ${chunk}`).toEqual(records.filter((record) => record.trim()))
      await appendFile(transcriptPath, ' being written}\n')
      await watcher.pollSession('s1')
      expect(lines.at(-1)).toBe('{"n":6, still being written}')
      await watcher.stop()
    }
  })

  it('stops a long read at a hold that lands in it, and hands over every line exactly once', async () => {
    const all = Array.from({ length: 400 }, (_, i) => `{"n":${i},"pad":"${'y'.repeat(i % 37)}"}`)
    const { transcriptPath, watcher, lines } = await backlog({ readChunkBytes: 32 })
    await appendFile(transcriptPath, all.join('\n') + '\n')
    const reading = watcher.pollAll()
    const hold = (await watcher.hold('s1', transcriptPath))!
    await reading
    const size = Buffer.byteLength(all.join('\n') + '\n')
    expect(hold.offset).toBeLessThan(size)
    // Delivery stopped exactly at a line: what came out is everything before that byte.
    expect(Buffer.byteLength(lines.map((line) => line + '\n').join(''))).toBe(hold.offset)
    hold.release(hold.offset)
    await watcher.pollSession('s1')
    expect(lines).toEqual(all)
    await watcher.stop()
  })

  it('attaches a file that shrank to more history than one batch should hold, instead of replaying it', async () => {
    const { transcriptPath, watcher, lines, history, rewritten } = await backlog({ historyMaxBytes: 40 }, records.join('\n') + '\n')
    await writeFile(transcriptPath, records.slice(0, 4).join('\n') + '\n')
    await watcher.pollSession('s1')
    expect(rewritten).toEqual([{ sessionId: 's1', engine: 'codex', transcriptPath }])
    expect({ lines, history }).toEqual({ lines: [], history: [] })
    // The tail goes on from the new end.
    await appendFile(transcriptPath, '{"n":7}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":7}'])
    // A shrink small enough is still read as history.
    await writeFile(transcriptPath, '{"n":8}\n')
    await watcher.pollSession('s1')
    expect(history).toEqual(['{"n":8}'])
    await watcher.stop()
  })

  it('stops where a file cut short under the read ends', async () => {
    const shorted = async (path: string) => {
      const handle = await open(path, 'r')
      let reads = 0
      return Object.assign(Object.create(handle), {
        read: (...args: Parameters<typeof handle.read>) => (++reads > 1 ? Promise.resolve({ bytesRead: 0, buffer: args[0] }) : handle.read(...args)),
        close: () => handle.close(),
      })
    }
    const { transcriptPath, watcher, lines } = await backlog({ readChunkBytes: 8, openFile: shorted })
    await appendFile(transcriptPath, '{"n":1}\n{"n":2}\n')
    await watcher.pollSession('s1')
    expect(lines).toEqual(['{"n":1}'])
    await watcher.stop()
  })
})