Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

21.9 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
import {
  useAgentStatus,
  createAgentStatusSession,
  inferInterruptAfterSettle,
  DONE_HOLDOFF_MS,
  STALE_WORKING_MS
} from './agentStatus'

let seq = 0
const nid = (): string => `node-${++seq}`

beforeEach(() => {
  vi.useFakeTimers()
})
afterEach(() => {
  vi.useRealTimers()
})

describe('sessionEnded — an announced exit is its own fact, not an idle state', () => {
  it('is set explicitly and withdrawn by the next state transition', () => {
    const id = nid()
    const s = useAgentStatus.getState()
    s.setState(id, 'done', 'claude')
    s.setState(id, undefined, 'claude')
    useAgentStatus.getState().setSessionEnded(id, true)
    expect(useAgentStatus.getState().byId[id]?.sessionEnded).toBe(true)
    const same = useAgentStatus.getState().byId
    useAgentStatus.getState().setSessionEnded(id, true)
    expect(useAgentStatus.getState().byId).toBe(same)
    useAgentStatus.getState().setState(id, 'working', 'claude', true)
    expect(useAgentStatus.getState().byId[id]?.sessionEnded).toBeUndefined()
  })

  it('can be recorded for a node whose status entry was already cleared (a parked pane)', () => {
    const id = nid()
    useAgentStatus.getState().setSessionEnded(id, true)
    expect(useAgentStatus.getState().byId[id]?.sessionEnded).toBe(true)
    useAgentStatus.getState().setSessionEnded(id, false)
    expect(useAgentStatus.getState().byId[id]?.sessionEnded).toBeUndefined()
  })

  it('the agent-event reducer records it on SessionEnd and withdraws it on SessionStart', () => {
    // A store flag with no writer is the bug in a new place: the levers would type-check and stay
    // protected forever. Pinned at source level, like the setState argument list above.
    // (The listener's store writes moved out of Canvas into state/applyAgentEvent.ts.)
    const src = readFileSync(resolve(__dirname, '../../..', 'src/renderer/state/applyAgentEvent.ts'), 'utf8')
    const end = src.slice(src.indexOf("if (e.sessionPhase === 'end') {"))
    expect(end.slice(0, 600)).toMatch(/cs\.setSessionEnded\(e\.nodeId, true\)/)
    const start = src.slice(src.indexOf("if (e.sessionPhase === 'start') {"), src.indexOf("if (e.sessionPhase === 'end') {"))
    expect(start).toMatch(/cs\.setSessionEnded\(e\.nodeId, false\)/)
  })
})

describe('done-holdoff race guard', () => {
  // Claude Code runs hooks in parallel: the last PostToolUse's curl can land AFTER the
  // Stop's curl. Without a holdoff that late "working" resurrects a finished turn.
  it('ignores a non-newTurn working arriving right after done', () => {
    const id = nid()
    const s = useAgentStatus.getState()
    s.setState(id, 'working', 'claude')
    s.setState(id, 'done', 'claude')
    vi.advanceTimersByTime(1000)
    useAgentStatus.getState().setState(id, 'working', 'claude')
    expect(useAgentStatus.getState().byId[id].state).toBe('done')
  })

  it('a genuine new turn (newTurn) overrides the holdoff', () => {
    const id = nid()
    const s = useAgentStatus.getState()
    s.setState(id, 'done', 'claude')
    vi.advanceTimersByTime(1000)
    useAgentStatus.getState().setState(id, 'working', 'claude', true)
    expect(useAgentStatus.getState().byId[id].state).toBe('working')
  })

  it('working is accepted again once the holdoff has passed', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'done', 'claude')
    vi.advanceTimersByTime(DONE_HOLDOFF_MS + 500)
    useAgentStatus.getState().setState(id, 'working', 'claude')
    expect(useAgentStatus.getState().byId[id].state).toBe('working')
  })
})

describe('stale-working sweeper', () => {
  it('clears a working entry whose last event is older than the stale threshold', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'working', 'claude')
    vi.advanceTimersByTime(STALE_WORKING_MS + 60_000)
    useAgentStatus.getState().sweepStaleWorking()
    expect(useAgentStatus.getState().byId[id]).toMatchObject({
      state: undefined,
      lastEventAt: Date.now()
    })
  })

  it('keeps a working entry fresh as long as events keep arriving', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'working', 'claude')
    // Repeated same-state events (each tool use) must refresh freshness.
    vi.advanceTimersByTime(STALE_WORKING_MS - 60_000)
    useAgentStatus.getState().setState(id, 'working', 'claude')
    vi.advanceTimersByTime(120_000)
    useAgentStatus.getState().sweepStaleWorking()
    expect(useAgentStatus.getState().byId[id].state).toBe('working')
  })

  it('never touches done/waiting entries', () => {
    const a = nid()
    const b = nid()
    useAgentStatus.getState().setState(a, 'done', 'claude')
    useAgentStatus.getState().setState(b, 'waiting', 'claude')
    vi.advanceTimersByTime(STALE_WORKING_MS * 2)
    useAgentStatus.getState().sweepStaleWorking()
    expect(useAgentStatus.getState().byId[a].state).toBe('done')
    expect(useAgentStatus.getState().byId[b].state).toBe('waiting')
  })
})

describe('focus tracking', () => {
  it('switches the watched node without changing either session state', () => {
    const left = nid()
    const right = nid()
    const status = useAgentStatus.getState()
    status.setState(left, 'done', 'claude')
    status.setState(right, 'working', 'claude')
    status.setActive(left, true)
    status.setActive(right, true)

    expect(useAgentStatus.getState().activeId).toBe(right)
    expect(useAgentStatus.getState().byId[left].state).toBe('done')
    expect(useAgentStatus.getState().byId[right].state).toBe('working')
  })
})

describe('interrupt inference (Esc/Ctrl-C with no final hook)', () => {
  it('flips a still-working node to done after the settle window', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'working', 'claude')
    inferInterruptAfterSettle(id, 1500)
    vi.advanceTimersByTime(1500)
    expect(useAgentStatus.getState().byId[id].state).toBe('done')
  })

  it('aborts when any hook event lands during the settle window (agent still alive)', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'working', 'claude')
    inferInterruptAfterSettle(id, 1500)
    vi.advanceTimersByTime(700)
    useAgentStatus.getState().setState(id, 'working', 'claude') // e.g. next PreToolUse
    vi.advanceTimersByTime(800)
    expect(useAgentStatus.getState().byId[id].state).toBe('working')
  })

  it('is a no-op when the node is not working (Esc at an idle prompt)', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'done', 'claude')
    inferInterruptAfterSettle(id, 1500)
    vi.advanceTimersByTime(1500)
    expect(useAgentStatus.getState().byId[id].state).toBe('done')
  })
})

describe('background-task stamp (Eco / bulk-restart guard)', () => {
  it('markBackgroundTask stamps, and a non-working transition never clears it', () => {
    const id = nid()
    const s = useAgentStatus.getState()
    s.setState(id, 'done', 'claude')
    s.markBackgroundTask(id)
    expect(useAgentStatus.getState().byId[id]?.backgroundTaskAt).toBeTypeOf('number')
    // done → waiting is a transition, but the task is still running: the guard must hold.
    s.setState(id, 'waiting', 'claude')
    expect(useAgentStatus.getState().byId[id]?.backgroundTaskAt).toBeTypeOf('number')
  })

  // Only a turn START — a `working` arriving from `done` — clears the stamp. Everything else keeps
  // it. blocked/waiting → working is a MID-TURN RESUMPTION (the same turn picking back up; see the
  // approval walk-through below), and an UNKNOWN previous state is not evidence of a turn start
  // at all: it is what a renderer reload or the stale-working sweeper leaves behind MID-TURN, so
  // clearing there would delete the stamp for a task that is still running.
  it('clears only on a turn start (done → working), never on a resumption or from an unknown state', () => {
    for (const { from, cleared } of [
      { from: 'blocked' as const, cleared: false },
      { from: 'waiting' as const, cleared: false },
      { from: undefined, cleared: false },
      { from: 'done' as const, cleared: true }
    ]) {
      const id = nid()
      const s = useAgentStatus.getState()
      if (from) s.setState(id, from, 'claude')
      s.markBackgroundTask(id)
      // A `done` predecessor needs the holdoff to lapse, or the working event is dropped whole.
      if (from === 'done') vi.advanceTimersByTime(DONE_HOLDOFF_MS + 500)
      useAgentStatus.getState().setState(id, 'working', 'claude')
      const label = String(from)
      expect(useAgentStatus.getState().byId[id].state, label).toBe('working')
      const stamp = useAgentStatus.getState().byId[id].backgroundTaskAt
      if (cleared) expect(stamp, label).toBeUndefined()
      else expect(stamp, label).toBeTypeOf('number')
    }
  })

  // The scenario the predicate exists for: a background Bash whose command needs approval runs
  // UserPromptSubmit(working) → PreToolUse(stamp) → PermissionRequest(blocked) → approve →
  // PostToolUse(working). That last edge IS a transition, and clearing on it would drop the guard
  // milliseconds after the stamp was set, while the task runs on.
  it('a background task that needed approval keeps its stamp across the approve edge', () => {
    const id = nid()
    const s = useAgentStatus.getState()
    s.setState(id, 'working', 'claude', true) // UserPromptSubmit — the turn starts
    s.markBackgroundTask(id) // PreToolUse Bash, run_in_background
    s.setState(id, 'blocked', 'claude') // PermissionRequest
    s.setState(id, 'working', 'claude') // approved, the turn resumes
    expect(useAgentStatus.getState().byId[id].backgroundTaskAt).toBeTypeOf('number')
  })

  it('stamps a node with no entry yet (the task can precede any state event)', () => {
    const id = nid()
    useAgentStatus.getState().markBackgroundTask(id)
    expect(useAgentStatus.getState().byId[id]?.backgroundTaskAt).toBeTypeOf('number')
    expect(useAgentStatus.getState().byId[id]?.unread).toBe(false)
  })
})

describe('clearUnread — cross-surface ack vs. external (host-driven) clear', () => {
  it('a normal clear of a done+unread node ACKs the read (dismisses the phone activity)', () => {
    const acked: string[] = []
    const { store } = createAgentStatusSession(undefined, (id) => acked.push(id))
    const id = 'nt-1'
    store.getState().setState(id, 'done', 'claude')
    store.getState().markUnread(id)
    store.getState().clearUnread(id)
    expect(store.getState().byId[id].unread).toBe(false)
    expect(acked).toEqual(['nt-1'])
  })

  it('an EXTERNAL clear (driven by a swept phone read-ack) does NOT re-ack — no loop', () => {
    const acked: string[] = []
    const { store } = createAgentStatusSession(undefined, (id) => acked.push(id))
    const id = 'nt-2'
    store.getState().setState(id, 'done', 'claude')
    store.getState().markUnread(id)
    store.getState().clearUnread(id, { external: true })
    expect(store.getState().byId[id].unread).toBe(false)
    // The ack already happened phone-side; re-acking here would loop host→renderer→ackDone.
    expect(acked).toEqual([])
  })

  it('acks a done with NO unread flag — the session the user watched finish', () => {
    const acked: string[] = []
    const { store } = createAgentStatusSession(undefined, (id) => acked.push(id))
    const id = 'nt-watched'
    // Watching the node when it finished means markUnread was skipped, so opening it is the only
    // read signal there will ever be. Without this ack the notch blob / phone activity kept glowing.
    store.getState().setState(id, 'done', 'claude')
    store.getState().clearUnread(id)
    expect(acked).toEqual(['nt-watched'])
    expect(store.getState().byId[id].unread).toBeFalsy()
  })

  it('acks even while the node is WORKING — a previous turn may still be unread', () => {
    const acked: string[] = []
    const { store } = createAgentStatusSession(undefined, (id) => acked.push(id))
    const id = 'nt-3'
    // The user opens a node whose last turn finished while a NEW turn is already running. That
    // finish is on screen, so it is read; the mirror no-ops if there is nothing pending, and it
    // only ever resolves `done` events, so a live approval is untouched.
    store.getState().setState(id, 'working', 'claude')
    store.getState().markUnread(id)
    store.getState().clearUnread(id)
    expect(acked).toEqual(['nt-3'])
  })

  it('an EXTERNAL clear still never acks, whatever the state', () => {
    const acked: string[] = []
    const { store } = createAgentStatusSession(undefined, (id) => acked.push(id))
    const id = 'nt-4'
    store.getState().setState(id, 'working', 'claude')
    store.getState().markUnread(id)
    store.getState().clearUnread(id, { external: true })
    expect(acked).toEqual([])
  })
})

describe('the verified evidence for a transition', () => {
  it('setState records it', () => {
    const s = useAgentStatus.getState()
    const id = nid()
    s.setState(id, 'done', 'claude', false, undefined, true)
    expect(useAgentStatus.getState().byId[id].stateVerified).toBe(true)
    s.setState(id, 'working', 'claude', true, undefined, false)
    expect(useAgentStatus.getState().byId[id].stateVerified).toBe(false)
  })

  it('an omitted argument is not proof (every existing call site keeps compiling, and lies about nothing)', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'done', 'claude')
    expect(useAgentStatus.getState().byId[id].stateVerified).toBe(false)
  })

  it('the agent-event reducer hands the event\'s flag to the store — the drop this whole change exists to fix', () => {
    // A store field with no writer is the same bug in a new place, and this one is a plain
    // argument list: nothing else in the suite would notice if the last argument disappeared.
    // (The listener's store writes moved out of Canvas into state/applyAgentEvent.ts.)
    const src = readFileSync(resolve(__dirname, '../../..', 'src/renderer/state/applyAgentEvent.ts'), 'utf8')
    expect(src).toMatch(
      /cs\.setState\(\s*e\.nodeId,\s*e\.state,\s*e\.agentId,\s*e\.newTurn,\s*e\.pendingId,\s*e\.verified,\s*e\.errored,\s*e\.held,\s*recordsTurnInterrupt\(e\)\s*\)/
    )
  })

  it('a same-state re-assert by a legacy POST drops the earlier proof', () => {
    // The same-state fast path refreshes in place instead of allocating; the evidence has to ride
    // along, or this copy would keep saying `verified` about a state a tokenless event re-asserted.
    const s = useAgentStatus.getState()
    const id = nid()
    s.setState(id, 'working', 'claude', true, undefined, true)
    s.setState(id, 'working', 'claude', false, undefined, false)
    expect(useAgentStatus.getState().byId[id].stateVerified).toBe(false)
  })

  it('stateVerified is TRANSIENT — never persisted', () => {
    // This suite runs under node, not jsdom, so the store's localStorage writes are swallowed by
    // its own try/catch. A minimal in-memory stub is what makes the durable whitelist observable
    // at all — without it this assertion would pass against ANY whitelist, including a broken one.
    const mem = new Map<string, string>()
    ;(globalThis as unknown as { localStorage: unknown }).localStorage = {
      getItem: (k: string) => mem.get(k) ?? null,
      setItem: (k: string, v: string) => void mem.set(k, v),
      removeItem: (k: string) => void mem.delete(k)
    }
    try {
      const KEY = 'nodeterm.agentStatus.verified-test'
      const { store } = createAgentStatusSession(KEY)
      const id = nid()
      // ORDER IS LOAD-BEARING, and the first draft of this test had it backwards. `setState` does
      // not itself call `save`, and `save` skips entries with no durable field — so writing the
      // blob BEFORE the verified transition produced a blob that could not contain `stateVerified`
      // whatever the whitelist said, and the assertion below passed against a whitelist that
      // included it. Set the flag first, then trigger a save with a durable write.
      store.getState().setState(id, 'done', 'claude', false, undefined, true)
      expect(store.getState().byId[id].stateVerified).toBe(true)
      store.getState().markUnread(id)
      const saved = JSON.parse(mem.get(KEY) ?? '{}')
      expect(saved[id]).toBeTruthy()
      expect(saved[id].unread).toBe(true)
      expect(saved[id].stateVerified).toBeUndefined()
    } finally {
      delete (globalThis as unknown as { localStorage?: unknown }).localStorage
    }
  })
})

describe('held permission request (structured answers)', () => {
  const plan = { pendingId: 'n-1-1', toolName: 'ExitPlanMode' }
  const question = { pendingId: 'n-2-2', toolName: 'AskUserQuestion' }

  it('is kept on blocked AND on waiting (a held picker is broadcast as waiting), cleared on leaving', () => {
    const s = useAgentStatus.getState()
    const id = nid()
    s.setState(id, 'blocked', 'claude', false, 'n-1-1', true, false, plan)
    expect(useAgentStatus.getState().byId[id].held).toEqual(plan)
    const q = nid()
    s.setState(q, 'waiting', 'claude', false, undefined, true, false, question)
    expect(useAgentStatus.getState().byId[q].held).toEqual(question)
    expect(useAgentStatus.getState().byId[q].pendingId).toBeUndefined() // approve/deny stays off
    s.setState(id, 'working', 'claude', false)
    expect(useAgentStatus.getState().byId[id].held).toBeUndefined()
  })

  it('a NEW held request on a same-state re-assert retargets (breaks the in-place fast path)', () => {
    const s = useAgentStatus.getState()
    const id = nid()
    s.setState(id, 'waiting', 'claude', false, undefined, true, false, question)
    const again = { pendingId: 'n-3-3', toolName: 'AskUserQuestion' }
    s.setState(id, 'waiting', 'claude', false, undefined, true, false, again)
    expect(useAgentStatus.getState().byId[id].held).toEqual(again)
    // A re-assert with no held info keeps the current one.
    s.setState(id, 'waiting', 'claude', false)
    expect(useAgentStatus.getState().byId[id].held).toEqual(again)
  })
})

describe('onHookEvent — a per-node pulse for EVERY hook event, same-state ones included', () => {
  it('a same-state event notifies no zustand subscriber (the in-place fast path) — which is why the pulse exists', () => {
    const id = nid()
    useAgentStatus.getState().setState(id, 'working', 'claude', true)
    const sub = vi.fn()
    const unsub = useAgentStatus.subscribe(sub)
    useAgentStatus.getState().setState(id, 'working', 'claude')
    expect(sub).not.toHaveBeenCalled()
    unsub()
  })

  it('fires for transitions and same-state events of that node only, and unsubscribes', () => {
    const id = nid()
    const other = nid()
    const cb = vi.fn()
    const unsub = useAgentStatus.getState().onHookEvent(id, cb)
    useAgentStatus.getState().setState(id, 'working', 'claude', true)
    useAgentStatus.getState().setState(id, 'working', 'claude')
    useAgentStatus.getState().setState(other, 'working', 'claude', true)
    expect(cb).toHaveBeenCalledTimes(2)
    unsub()
    useAgentStatus.getState().setState(id, 'done', 'claude')
    expect(cb).toHaveBeenCalledTimes(2)
  })

  it('a throwing listener neither aborts setState nor starves the next listener', () => {
    const id = nid()
    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const bad = useAgentStatus.getState().onHookEvent(id, () => {
      throw new Error('boom')
    })
    const good = vi.fn()
    const unsub = useAgentStatus.getState().onHookEvent(id, good)
    expect(() => useAgentStatus.getState().setState(id, 'working', 'claude', true)).not.toThrow()
    expect(good).toHaveBeenCalledOnce()
    expect(useAgentStatus.getState().byId[id]?.state).toBe('working')
    bad()
    unsub()
    warn.mockRestore()
  })

  it('sees the store already updated when it fires', () => {
    const id = nid()
    let seen: string | undefined
    const unsub = useAgentStatus.getState().onHookEvent(id, () => {
      seen = useAgentStatus.getState().byId[id]?.state
    })
    useAgentStatus.getState().setState(id, 'working', 'claude', true)
    expect(seen).toBe('working')
    unsub()
  })
})

describe('same-state fast path — own entries only', () => {
  // The fields the in-place refresh writes, and the objects a bare `byId[id]` lookup answers for a
  // prototype name with no own entry: `Object.prototype`, `Object`, `Object.prototype.toString`.
  const FIELDS = ['stateAt', 'lastSeen', 'stateVerified']
  const targets = (): object[] => [Object.prototype, Object, Object.prototype.toString]
  const polluted = (): string[] =>
    targets().flatMap((t, i) => FIELDS.filter((k) => Object.hasOwn(t, k)).map((k) => `${i}.${k}`))
  afterEach(() => {
    // A regression must fail THIS test, not every later test in the worker.
    for (const t of targets()) for (const k of FIELDS) delete (t as Record<string, unknown>)[k]
  })

  it('a same-state event for an id with no own entry never writes into the prototype', () => {
    const { store } = createAgentStatusSession(undefined)
    for (const id of ['__proto__', 'constructor', 'toString']) {
      // Unknown → unknown with no agent id: same-state by construction, so the in-place path.
      store.getState().setState(id, undefined, undefined)
      store.getState().setState(id, undefined, undefined, undefined, undefined, true)
    }
    expect(polluted()).toEqual([])
    expect(Object.hasOwn(Object.prototype, 'stateAt')).toBe(false)
    expect(Object.hasOwn(Object.prototype, 'lastSeen')).toBe(false)
    expect(Object.hasOwn(Object.prototype, 'stateVerified')).toBe(false)
  })

  it('a real node still refreshes in place (no new table, freshness and evidence move)', () => {
    const { store } = createAgentStatusSession(undefined)
    const id = nid()
    store.getState().setState(id, 'working', 'claude', true, undefined, true)
    const table = store.getState().byId
    const t0 = table[id].stateAt
    vi.advanceTimersByTime(1000)
    store.getState().setState(id, 'working', 'claude')
    expect(store.getState().byId).toBe(table)
    expect(store.getState().byId[id].stateAt).toBe((t0 ?? 0) + 1000)
    expect(store.getState().byId[id].lastSeen?.at).toBe((t0 ?? 0) + 1000)
    expect(store.getState().byId[id].stateVerified).toBe(false)
  })
})