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.

20.6 KB
Raw Blame
// The session an unbound, live agent runs, found for the handoff (lib/handoffDiscovery.ts): read-only, born-only,
// and never a guess: each refusal below is a case where a Change agent must not pick a conversation.
import { describe, expect, it, vi } from 'vitest'

import { handoffProviderDeps, ownedByOther, sessionDiscovery, type DiscoveryDeps, type HandoffWiring } from './handoffDiscovery.js'
import type { RegisteredSession } from './registry.js'

const MARKER = 'Fri Oct  2 16:58:26 2026'

const agent = (over: Record<string, unknown> = {}): RegisteredSession => ({
  agentId: 'a1', sessionId: '', engine: 'codex', cwd: '/w', transcriptPath: null, registeredAt: 1_790_000_000_000,
  processIdentity: { pid: 4242, executable: 'claude', startMarker: MARKER }, ...over,
}) as unknown as RegisteredSession

type Spied = DiscoveryDeps & { findLiveSession: ReturnType<typeof vi.fn>; processSession: ReturnType<typeof vi.fn> }
/** Codex is the default engine here: Claude is looked for through its process record only (its own block below). */
function deps(over: Partial<DiscoveryDeps> = {}): Spied {
  const findLiveSession = vi.fn(async () => ({ sessionId: 's9', transcriptPath: '/t/s9.jsonl' }))
  const processSession = vi.fn(async () => ({ sessionId: 's9', transcriptPath: '/t/s9.jsonl' }))
  return { findLiveSession, processSession, isLive: () => true, ownedByOther: () => false, isRecentlyDeleted: () => false, ...over } as Spied
}

describe('sessionDiscovery', () => {
  it('finds the unique born session and passes the process start and pid, born-only', async () => {
    const d = deps()
    expect(await sessionDiscovery(d)(agent())).toEqual({ engine: 'codex', sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
    expect(d.findLiveSession).toHaveBeenCalledWith('codex', '/w', Date.parse(MARKER), { bornOnly: true, pid: 4242, codexHome: undefined })
  })

  it('passes a codex agent its own CODEX_HOME', async () => {
    const d = deps()
    await sessionDiscovery(d)(agent({ codexHome: '/h' }))
    expect(d.findLiveSession).toHaveBeenCalledWith('codex', '/w', Date.parse(MARKER), { bornOnly: true, pid: 4242, codexHome: '/h' })
  })

  describe('needs the process itself, as the repair sweep does: a valid start marker and a pid', () => {
    const cases: Array<[string, unknown]> = [
      ['no process identity', null],
      ['an unparseable start marker', { pid: 4242, executable: 'x', startMarker: 'garbage' }],
      ['an empty start marker', { pid: 4242, executable: 'x', startMarker: '' }],
      ['no pid', { executable: 'x', startMarker: MARKER }],
      ['a zero pid', { pid: 0, executable: 'x', startMarker: MARKER }],
      ['a fractional pid', { pid: 1.5, executable: 'x', startMarker: MARKER }],
    ]
    for (const engine of ['codex', 'claude']) {
      for (const [name, processIdentity] of cases) {
        it(`${engine}: ${name} looks nowhere, never falling back to registeredAt`, async () => {
          const d = deps()
          expect(await sessionDiscovery(d)(agent({ engine, processIdentity }))).toBeNull()
          expect(d.findLiveSession).not.toHaveBeenCalled()
          expect(d.processSession).not.toHaveBeenCalled()
        })
      }
    }
  })

  describe('Claude is identified by its process record alone', () => {
    it('accepts only the session the record names, and never scans the project folder', async () => {
      const d = deps()
      expect(await sessionDiscovery(d)(agent({ engine: 'claude' }))).toEqual({ engine: 'claude', sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
      expect(d.processSession).toHaveBeenCalledWith('claude', 4242, '/w', Date.parse(MARKER))
      expect(d.findLiveSession).not.toHaveBeenCalled()
    })
    it('answers nothing, with no scan to fall back on, when the record matches no session or does not exist', async () => {
      const d = deps({ processSession: async () => null })
      expect(await sessionDiscovery(d)(agent({ engine: 'claude' }))).toBeNull()
      expect(d.findLiveSession).not.toHaveBeenCalled()
    })
    it('still refuses a record whose session has no path, is a subagent file, is owned or deleted, or whose read throws', async () => {
      const claude = (over: Partial<DiscoveryDeps>) => sessionDiscovery(deps(over))(agent({ engine: 'claude' }))
      await expect(claude({ processSession: async () => ({ sessionId: 's9' }) })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(claude({ processSession: async () => ({ sessionId: 'a', transcriptPath: '/p/s/subagents/agent-a.jsonl' }) })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(claude({ ownedByOther: () => true })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(claude({ isRecentlyDeleted: () => true })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(claude({ processSession: async () => { throw new Error('boom') } })).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    })
  })

  describe('never looks', () => {
    const cases: Array<[string, Record<string, unknown>, Partial<DiscoveryDeps>?]> = [
      ['a bound session', { sessionId: 's1' }],
      ['a fork', { forkedFrom: { agentId: 'p', name: 'P' } }],
      ['a malformed fork record', { forkedFrom: 'x' }],
      ['an agent with no folder', { cwd: '' }],
      ['opencode', { engine: 'opencode' }],
      ['kilo', { engine: 'kilo' }],
      ['hermes', { engine: 'hermes' }],
      ['devin', { engine: 'devin' }],
      ['an agent that is not live (stopped)', {}, { isLive: () => false }],
    ]
    for (const [name, over, depOver] of cases) {
      it(name, async () => {
        const d = deps(depOver)
        expect(await sessionDiscovery(d)(agent(over))).toBeNull()
        expect(d.findLiveSession).not.toHaveBeenCalled()
      })
    }
  })

  describe('refuses a match', () => {
    it('with no transcript path', async () => {
      await expect(sessionDiscovery(deps({ findLiveSession: async () => ({ sessionId: 's9' }) }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    })
    it('that is a subagent transcript', async () => {
      await expect(sessionDiscovery(deps({ findLiveSession: async () => ({ sessionId: 'agent-a', transcriptPath: '/p/proj/s/subagents/agent-a.jsonl' }) }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    })
    it('owned by another agent', async () => {
      const ownedByOther = vi.fn(() => true)
      await expect(sessionDiscovery(deps({ ownedByOther }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      expect(ownedByOther).toHaveBeenCalledWith('s9', 'a1')
    })
    it('that was recently deleted', async () => {
      await expect(sessionDiscovery(deps({ isRecentlyDeleted: () => true }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    })
    it('when nothing is found, or the search throws, or an ownership check throws', async () => {
      expect(await sessionDiscovery(deps({ findLiveSession: async () => null }))(agent())).toBeNull()
      await expect(sessionDiscovery(deps({ findLiveSession: async () => { throw new Error('boom') } }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(sessionDiscovery(deps({ ownedByOther: () => { throw new Error('boom') } }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    })
  })

  // Verifier additions (unit-INT-a3-r1): the edges of each refusal.
  it('treats an explicit `forkedFrom: null` as no fork, and still looks', async () => {
    const d = deps()
    expect(await sessionDiscovery(d)(agent({ forkedFrom: null }))).toEqual({ engine: 'codex', sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
    expect(d.findLiveSession).toHaveBeenCalledTimes(1)
  })

  describe('never looks, for any fork record that is not null, however malformed', () => {
    for (const forkedFrom of ['', false, 0, {}, [], { agentId: '' }]) {
      it(JSON.stringify(forkedFrom), async () => {
        const d = deps()
        expect(await sessionDiscovery(d)(agent({ forkedFrom }))).toBeNull()
        expect(d.findLiveSession).not.toHaveBeenCalled()
      })
    }
  })

  it('never looks for an agent whose folder is missing altogether', async () => {
    const d = deps()
    expect(await sessionDiscovery(d)(agent({ cwd: undefined }))).toBeNull()
    expect(d.findLiveSession).not.toHaveBeenCalled()
  })

  it('never looks when the liveness check throws', async () => {
    const d = deps({ isLive: () => { throw new Error('boom') } })
    expect(await sessionDiscovery(d)(agent())).toBeNull()
    expect(d.findLiveSession).not.toHaveBeenCalled()
  })

  it('refuses a match with an empty session id', async () => {
    await expect(sessionDiscovery(deps({ findLiveSession: async () => ({ sessionId: '', transcriptPath: '/t/x.jsonl' }) }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  })

  it('refuses a subagent transcript written with backslashes, and accepts a folder that only contains the word', async () => {
    await expect(sessionDiscovery(deps({ findLiveSession: async () => ({ sessionId: 'agent-a', transcriptPath: 'C:\\p\\s\\subagents\\agent-a.jsonl' }) }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    expect(await sessionDiscovery(deps({ findLiveSession: async () => ({ sessionId: 's9', transcriptPath: '/p/my-subagents/s9.jsonl' }) }))(agent()))
      .toEqual({ engine: 'codex', sessionId: 's9', transcriptPath: '/p/my-subagents/s9.jsonl' })
  })

  it('checks deletion and ownership against the found session, and refuses when the deletion check throws', async () => {
    const isRecentlyDeleted = vi.fn(() => false)
    const ownedByOther = vi.fn(() => false)
    await sessionDiscovery(deps({ isRecentlyDeleted, ownedByOther }))(agent())
    expect(isRecentlyDeleted).toHaveBeenCalledWith('s9')
    expect(ownedByOther).toHaveBeenCalledWith('s9', 'a1')
    await expect(sessionDiscovery(deps({ isRecentlyDeleted: () => { throw new Error('boom') } }))(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  })

  it('answers with the agent\'s own engine, whatever else the match carries', async () => {
    const d = deps({ findLiveSession: async () => ({ sessionId: 's9', transcriptPath: '/t/s9.jsonl', engine: 'opencode' }) as never })
    expect(await sessionDiscovery(d)(agent({ engine: 'pi' }))).toEqual({ engine: 'pi', sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
  })

  it.each(['process', 'binding', 'runtime'])('holds an in-place %s update to the actual registry row during discovery', async field => {
    const row = agent()
    let release!: (value: { sessionId: string; transcriptPath: string }) => void
    const observed = vi.fn()
    const discover = sessionDiscovery(deps({ current: () => row, observed,
      findLiveSession: () => new Promise(resolve => { release = resolve }) }))
    const pending = discover(row)
    if (field === 'process') row.processIdentity!.pid = 4243
    if (field === 'binding') row.boundAt = 42
    if (field === 'runtime') row.runtimes = [{ backend: 'tmux', paneId: '%9' }]
    release({ sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
    await expect(pending).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    expect(observed).not.toHaveBeenCalled()
  })

  it('hands concurrent callers the very same promise', async () => {
    const findLiveSession = vi.fn(() => new Promise<null>(() => {}))
    const discover = sessionDiscovery(deps({ findLiveSession } as Partial<DiscoveryDeps>))
    expect(discover(agent())).toBe(discover(agent()))
    expect(findLiveSession).toHaveBeenCalledTimes(1)
  })

  it('forgets a search that threw (async or not), so the next call searches again', async () => {
    for (const findLiveSession of [vi.fn(async () => { throw new Error('boom') }), vi.fn(() => { throw new Error('sync boom') })]) {
      const discover = sessionDiscovery(deps({ findLiveSession } as Partial<DiscoveryDeps>))
      await expect(discover(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      await expect(discover(agent())).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
      expect(findLiveSession).toHaveBeenCalledTimes(2)
    }
  })

  it('shares one search between concurrent calls for an agent, and searches again once it settled', async () => {
    let release!: (v: { sessionId: string; transcriptPath: string }) => void
    const findLiveSession = vi.fn(() => new Promise<{ sessionId: string; transcriptPath: string }>((resolve) => { release = resolve }))
    const discover = sessionDiscovery(deps({ findLiveSession } as Partial<DiscoveryDeps>))
    const first = discover(agent())
    const second = discover(agent())
    expect(findLiveSession).toHaveBeenCalledTimes(1)
    release({ sessionId: 's9', transcriptPath: '/t/s9.jsonl' })
    expect(await first).toEqual(await second)
    release = () => {}
    void discover(agent())
    await Promise.resolve()
    expect(findLiveSession).toHaveBeenCalledTimes(2)
    // Another agent is not held up by the first.
    void discover(agent({ agentId: 'a2' }))
    expect(findLiveSession).toHaveBeenCalledTimes(3)
  })
})

describe('ownedByOther: another agent holds the session, running or stopped, failing closed', () => {
  const wiring = (over: Partial<Parameters<typeof ownedByOther>[0]> = {}) => ({
    bySession: () => undefined,
    stoppedIds: () => [] as string[],
    stopped: () => null,
    ...over,
  }) as Parameters<typeof ownedByOther>[0]
  const stoppedRow = (agentId: string, sessionId: string) => ({ agentId, sessionId }) as unknown as RegisteredSession

  it('is false for a session nobody holds, or only the agent itself holds', () => {
    expect(ownedByOther(wiring(), 's1', 'a1')).toBe(false)
    expect(ownedByOther(wiring({ bySession: () => ({ agentId: 'a1' }) as never }), 's1', 'a1')).toBe(false)
    expect(ownedByOther(wiring({ stoppedIds: () => ['a1'], stopped: () => stoppedRow('a1', 's1') }), 's1', 'a1')).toBe(false)
  })
  it('is true when a running agent holds it', () => {
    expect(ownedByOther(wiring({ bySession: () => ({ agentId: 'b' }) as never }), 's1', 'a1')).toBe(true)
  })
  it('is true when a stopped agent holds it', () => {
    expect(ownedByOther(wiring({ stoppedIds: () => ['b', 'c'], stopped: (id) => stoppedRow(id, id === 'c' ? 's1' : 'sx') }), 's1', 'a1')).toBe(true)
  })
  it('is true when ONE stopped record cannot be read, even though the others are fine and do not hold it', () => {
    const stopped = (id: string) => { if (id === 'bad') throw new Error('Could not read the saved stopped harness.'); return stoppedRow(id, 'sx') }
    expect(ownedByOther(wiring({ stoppedIds: () => ['b', 'bad', 'c'], stopped }), 's1', 'a1')).toBe(true)
  })
  it('is true when a stopped record exists but is unusable (get answers null), or the stopped folder cannot be listed', () => {
    expect(ownedByOther(wiring({ stoppedIds: () => ['b'], stopped: () => null }), 's1', 'a1')).toBe(true)
    expect(ownedByOther(wiring({ stoppedIds: () => { throw new Error('EACCES') } }), 's1', 'a1')).toBe(true)
  })
  it('is true when the running registry cannot answer', () => {
    expect(ownedByOther(wiring({ bySession: () => { throw new Error('boom') } }), 's1', 'a1')).toBe(true)
  })
})

describe('handoffProviderDeps: each dependency reaches the right function with the right arguments', () => {
  const fork = { agentId: 'f1' } as unknown as RegisteredSession
  const live = { agentId: 'a1', sessionId: '', engine: 'claude', cwd: '/w', registeredAt: 1, processIdentity: { pid: 7, executable: 'c', startMarker: MARKER } } as unknown as RegisteredSession
  function fakes(over: Partial<HandoffWiring> = {}): HandoffWiring {
    return {
      registry: { resolve: () => undefined, byAgent: () => undefined, bySession: () => undefined },
      stopped: { get: () => null, ids: () => [] },
      mirror: { recentAsks: vi.fn(() => ['ask']), lastFullText: vi.fn(() => 'full'), recent: vi.fn(() => []) } as never,
      databaseHistory: vi.fn(() => undefined),
      findLiveSession: vi.fn(async () => null),
      processSession: vi.fn(async () => null),
      isRecentlyDeleted: vi.fn(() => false),
      findResumedTranscript: vi.fn(async () => '/t/x.jsonl'),
      validTranscriptPath: vi.fn(() => true),
      ...over,
    }
  }

  it('resolves a running agent first, then a stopped one', () => {
    const run = { agentId: 'run' } as unknown as RegisteredSession
    const stoppedGet = vi.fn((id: string) => (id === 'gone' ? fork : null))
    const d = handoffProviderDeps(fakes({ registry: { resolve: (id) => (id === 'run' ? run : undefined), byAgent: () => undefined, bySession: () => undefined }, stopped: { get: stoppedGet, ids: () => [] } }))
    expect(d.resolve('run')).toBe(run)
    expect(d.resolve('gone')).toBe(fork)
    expect(stoppedGet).toHaveBeenCalledWith('gone')
    expect(stoppedGet).not.toHaveBeenCalledWith('run')
  })

  it('passes the mirror its session id and count, in that order, and keeps only summary recaps (recap, else text)', () => {
    const recent = vi.fn(() => [
      { kind: 'summary', recap: 'R1', text: 'T1' }, { kind: 'ask', text: 'not a recap' }, { kind: 'summary', recap: '', text: 'T3' }, { kind: 'summary', recap: '', text: '' },
    ])
    const f = fakes({ mirror: { recentAsks: vi.fn(() => ['a']), lastFullText: vi.fn(() => 'full'), recent } as never })
    const d = handoffProviderDeps(f)
    expect(d.recaps?.('sid', 3)).toEqual(['R1', 'T3'])
    expect(recent).toHaveBeenCalledWith('sid', 3)
    expect(d.recentAsks('sid', 4)).toEqual(['a'])
    expect(f.mirror.recentAsks).toHaveBeenCalledWith('sid', 4)
    expect(d.lastFullText('sid')).toBe('full')
    expect(f.mirror.lastFullText).toHaveBeenCalledWith('sid')
  })

  it('hands the database history reader through as is', () => {
    const f = fakes()
    expect(handoffProviderDeps(f).readHistory(live)).toBeUndefined()
    expect(f.databaseHistory).toHaveBeenCalledWith(live)
  })

  it('looks a transcript up by (engine, session id, {codexHome}) and vouches for a path with (engine, path, codexHome or undefined)', async () => {
    const f = fakes()
    const d = handoffProviderDeps(f)
    expect(await d.findTranscript?.('codex', 'sid', { codexHome: '/h' })).toBe('/t/x.jsonl')
    expect(f.findResumedTranscript).toHaveBeenCalledWith('codex', 'sid', { codexHome: '/h' })
    expect(d.transcriptOk?.('codex', '/t/x.jsonl', '/h')).toBe(true)
    expect(f.validTranscriptPath).toHaveBeenLastCalledWith('codex', '/t/x.jsonl', '/h')
    d.transcriptOk?.('claude', '/t/y.jsonl', null)
    expect(f.validTranscriptPath).toHaveBeenLastCalledWith('claude', '/t/y.jsonl', undefined)
  })

  it('discovery: live means a running agent; the deleted check gets the found session id; Claude goes by its process record', async () => {
    const byAgent = vi.fn(() => ({}))
    const isRecentlyDeleted = vi.fn(() => false)
    const processSession = vi.fn(async () => ({ sessionId: 'sx', transcriptPath: '/t/sx.jsonl' }))
    const f = fakes({ registry: { resolve: () => live, byAgent, bySession: () => undefined } as never, processSession, isRecentlyDeleted })
    expect(await handoffProviderDeps(f).discoverSession?.(live)).toEqual({ engine: 'claude', sessionId: 'sx', transcriptPath: '/t/sx.jsonl' })
    expect(byAgent).toHaveBeenCalledWith('a1')
    expect(isRecentlyDeleted).toHaveBeenCalledWith('sx')
    expect(processSession).toHaveBeenCalledWith('claude', 7, '/w', Date.parse(MARKER))
  })

  it('discovery owns the session check against the running registry and the stopped store', async () => {
    const processSession = vi.fn(async () => ({ sessionId: 'sx', transcriptPath: '/t/sx.jsonl' }))
    const running = fakes({ registry: { resolve: () => live, byAgent: () => ({}), bySession: (sid: string) => (sid === 'sx' ? { agentId: 'other' } : undefined) } as never, processSession })
    await expect(handoffProviderDeps(running).discoverSession?.(live)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
    const stopped = fakes({ registry: { resolve: () => live, byAgent: () => ({}), bySession: () => undefined }, stopped: { ids: () => ['old'], get: () => ({ agentId: 'old', sessionId: 'sx' }) as never }, processSession })
    await expect(handoffProviderDeps(stopped).discoverSession?.(live)).rejects.toMatchObject({ code: 'IDENTITY_UNAVAILABLE' })
  })

  it('creates the discovery once: two prepares for the same agent share one search while it is pending', async () => {
    let release!: (v: null) => void
    const processSession = vi.fn(() => new Promise<null>((resolve) => { release = resolve }))
    const d = handoffProviderDeps(fakes({ registry: { resolve: () => live, byAgent: () => ({}), bySession: () => undefined } as never, processSession }))
    // The same deps object serves every request: what the provider in cli.ts does.
    const first = d.discoverSession?.(live)
    const second = d.discoverSession?.(live)
    expect(processSession).toHaveBeenCalledTimes(1)
    release(null)
    await Promise.all([first, second])
  })
})