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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
import { describe, it, expect, vi } from 'vitest'
import type { PendingLaunch } from '@shared/types'
import {
firstOpenInFlight,
launchesToFire,
queueControlLaunch,
controlLaunchState,
deliveriesToRetire,
launchTooltip,
unmetDeps,
LAUNCH_STALL_MS,
withPrHold,
withSuccessHold,
successDepFacts,
withLaunchBrief,
launchBriefPresent,
handedOverDeps,
type ArmedNode,
type StatusById
} from './pendingLaunch'
const armed = (id: string, after: string[], command = `echo ${id}`): ArmedNode => ({
id,
data: { pendingLaunch: { after, command } }
})
const plain = (id: string): ArmedNode => ({ id, data: {} })
describe('launchesToFire', () => {
it('leaves server-owned launches to the headless scheduler', () => {
const node: ArmedNode = {
id: 'c',
data: { pendingLaunch: { after: [], command: 'echo c', executor: 'server' } }
}
expect(launchesToFire([node], {}, new Set(['c']))).toEqual([])
})
const live = new Set(['a', 'b', 'c'])
it('fires when every dep has reported done', () => {
const status: StatusById = { a: { state: 'done' }, b: { state: 'done' } }
expect(launchesToFire([armed('c', ['a', 'b'])], status, live)).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('does NOT fire while a dep is still working', () => {
const status: StatusById = { a: { state: 'done' }, b: { state: 'working' } }
expect(launchesToFire([armed('c', ['a', 'b'])], status, live)).toEqual([])
})
it('does NOT fire on an unknown state — "no news" is not "finished"', () => {
// The whole point: right after a fan-out the upstream stations have emitted nothing yet.
expect(launchesToFire([armed('c', ['a'])], {}, live)).toEqual([])
})
it('treats waiting/blocked as not satisfied — the station still needs its user', () => {
expect(launchesToFire([armed('c', ['a'])], { a: { state: 'waiting' } }, live)).toEqual([])
expect(launchesToFire([armed('c', ['a'])], { a: { state: 'blocked' } }, live)).toEqual([])
})
it('treats a dep that is no longer on the canvas as satisfied', () => {
// A deleted node can never report; waiting on it would strand the dependent forever.
const status: StatusById = { a: { state: 'done' } }
expect(launchesToFire([armed('c', ['a', 'ghost'])], status, new Set(['a', 'c']))).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('ignores nodes that are not armed, and armed nodes with an empty command', () => {
const status: StatusById = { a: { state: 'done' } }
expect(launchesToFire([plain('c'), armed('d', ['a'], '')], status, live)).toEqual([])
})
it('fires immediately when there are no deps left to wait on', () => {
expect(launchesToFire([armed('c', [])], {}, live)).toEqual([{ id: 'c', command: 'echo c' }])
})
it('walks a chain A → B → C one station at a time', () => {
const chain = [armed('b', ['a']), armed('c', ['b'])]
// Nothing has reported: nothing fires.
expect(launchesToFire(chain, {}, live)).toEqual([])
// A done releases B only — C waits on B, which has not even started.
expect(launchesToFire(chain, { a: { state: 'done' } }, live)).toEqual([{ id: 'b', command: 'echo b' }])
// B running is still not B done.
expect(launchesToFire(chain, { a: { state: 'done' }, b: { state: 'working' } }, live)).toEqual([
{ id: 'b', command: 'echo b' }
])
// B done releases C. (B is still listed here because the caller, not this function, retires a
// delivered launch by clearing its pendingLaunch — exactly-once lives in `launchInFlight`.)
expect(launchesToFire(chain, { a: { state: 'done' }, b: { state: 'done' } }, live)).toEqual([
{ id: 'b', command: 'echo b' },
{ id: 'c', command: 'echo c' }
])
})
it('after a restart (empty status map) a persisted arming holds — nothing will report, ▶ is the escape', () => {
// Agent state is transient; a live dep that reported `done` before the restart is unknown now,
// and unknown is NOT satisfied. The manual run-now on the badge exists for exactly this.
expect(launchesToFire([armed('c', ['a'])], {}, live)).toEqual([])
expect(unmetDeps(armed('c', ['a']), {}, live)).toEqual(['a'])
})
it('a dep deleted mid-chain releases what waited on it, but not what waits further down', () => {
const chain = [armed('b', ['a']), armed('c', ['b'])]
const liveWithoutA = new Set(['b', 'c'])
expect(launchesToFire(chain, {}, liveWithoutA)).toEqual([{ id: 'b', command: 'echo b' }])
})
})
describe('launchesToFire — awaitSetupGroup (a worktree whose setup script must land first)', () => {
const live = new Set(['a', 'c'])
const armedForSetup = (id: string, groupId: string, after: string[] = []): ArmedNode => ({
id,
data: { pendingLaunch: { after, command: `echo ${id}`, awaitSetupGroup: groupId } }
})
it('holds the launch while the group’s setup run is not done', () => {
expect(launchesToFire([armedForSetup('c', 'g1')], {}, live, () => false)).toEqual([])
})
it('fires once the group’s setup run is done', () => {
expect(launchesToFire([armedForSetup('c', 'g1')], {}, live, () => true)).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('with no setupDone probe at all, the gate is open — an absent probe never strands a node', () => {
// Reached after an app restart: the run store is empty, and a node armed before the restart
// would otherwise wait forever for a run nobody is going to report on again.
expect(launchesToFire([armedForSetup('c', 'g1')], {}, live)).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('asks the probe about THIS node’s group', () => {
const asked: string[] = []
launchesToFire([armedForSetup('c', 'g-seven')], {}, live, (g) => {
asked.push(g)
return true
})
expect(asked).toEqual(['g-seven'])
})
it('needs BOTH gates: setup done AND every `after` dep satisfied', () => {
const node = [armedForSetup('c', 'g1', ['a'])]
// setup done, dep still working
expect(launchesToFire(node, { a: { state: 'working' } }, live, () => true)).toEqual([])
// dep done, setup still running
expect(launchesToFire(node, { a: { state: 'done' } }, live, () => false)).toEqual([])
// both
expect(launchesToFire(node, { a: { state: 'done' } }, live, () => true)).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('leaves a node with no awaitSetupGroup alone even while some setup is running', () => {
expect(launchesToFire([armed('c', [])], {}, live, () => false)).toEqual([
{ id: 'c', command: 'echo c' }
])
})
})
describe('unmetDeps', () => {
it('reports only the deps still outstanding', () => {
const live = new Set(['a', 'b', 'c'])
const status: StatusById = { a: { state: 'done' }, b: { state: 'working' } }
expect(unmetDeps(armed('c', ['a', 'b']), status, live)).toEqual(['b'])
})
it('is empty for a node that is not armed', () => {
expect(unmetDeps(plain('c'), {}, new Set(['c']))).toEqual([])
})
})
/**
* Issue #569 item 1 — the delivery policy behind an armed node's held launch.
*
* The bug these pin: delivery used to be a flat 5 × 400 ms = 2 s budget started when the CANVAS
* decided a node was ready to launch, not when the node's terminal existed. A cold project switch
* spends that budget on loading the canvas, mounting the node and spawning tmux, so the launch was
* abandoned before there was anything to deliver into — and abandoned into a `console.warn`, which
* left a node reading QUEUED forever with no way to tell it apart from one still waiting on a
* dependency.
*/
describe('launch delivery policy (#569 item 1)', () => {
it('the stall warning waits longer than a cold project switch could plausibly take', () => {
expect(LAUNCH_STALL_MS).toBeGreaterThanOrEqual(30_000)
})
})
describe('launchTooltip — the QUEUED badge never goes silent (#569 item 1)', () => {
const cmd = 'claude "review the diff"'
it('with nothing to report it names the dependencies, exactly as before', () => {
const t = launchTooltip(undefined, 'Builder, Tests', cmd)
expect(t).toContain('Waiting for Builder, Tests to finish')
expect(t).toContain(cmd)
expect(t).not.toContain('▶')
})
it('a stalled launch says it is still held, and does NOT claim a cause it never measured', () => {
const t = launchTooltip({ kind: 'stalled', since: 1 }, 'Builder', cmd)
expect(t).toContain('has not started yet')
expect(t).toContain('still held')
expect(t).toContain('▶')
// We know the terminal is not up; we do not know why. Naming a cause here would be the
// misleading-error failure this feature exists to avoid.
expect(t.toLowerCase()).not.toMatch(/ssh|host is down|crash/)
})
it('a failed launch reports uncertainty and requires explicit recovery', () => {
const t = launchTooltip({ kind: 'failed', attempts: 5, at: 1 }, 'Builder', cmd)
expect(t).toContain('unconfirmed')
expect(t).toContain('automatic retry is stopped')
expect(t).toContain('▶')
expect(t).toContain(cmd)
})
it('a manual refusal instructs the user to inspect the terminal', () => {
expect(launchTooltip({ kind: 'failed', attempts: 1, at: 1 }, 'Builder', cmd)).toContain(
'Inspect the terminal'
)
})
it('failed outranks the dependency sentence — the warning is never buried', () => {
const t = launchTooltip({ kind: 'failed', attempts: 5, at: 1 }, 'Builder', cmd)
expect(t).not.toContain('Waiting for Builder')
})
it('launchTooltip explains a background start (#925)', () => {
expect(launchTooltip({ kind: 'starting', since: 0 }, '', 'claude', undefined, false)).toMatch(
/starting in the background/i
)
})
it('a background start outranks every other sentence — none of them may offer ▶ mid-start (#925)', () => {
for (const t of [
launchTooltip({ kind: 'starting', since: 0 }, 'Builder', cmd, 'Builder'),
launchTooltip({ kind: 'starting', since: 0 }, 'Builder', cmd, undefined, true)
]) {
expect(t).toMatch(/starting in the background/i)
expect(t).not.toContain('▶')
expect(t).not.toContain('Waiting for Builder')
}
})
})
describe('control opens retain an unacknowledged launch (#827/#811)', () => {
it.each(['claude', 'codex'])('queues %s even on a visible canvas with no dependencies', (agent) => {
const original = { id: 'new', data: { initialCommand: `${agent} brief`, pendingLaunch: undefined } }
const node = queueControlLaunch(original)
expect(node.data.initialCommand).toBeUndefined()
expect(node.data.pendingLaunch).toEqual({ after: [], command: `${agent} brief`, attempted: false })
expect(controlLaunchState(!!node.data.pendingLaunch, undefined)).toBe('queued')
// Simulate a project save/view: only durable data survives; the command must still fire.
const restored = JSON.parse(JSON.stringify(node))
expect(launchesToFire([restored], {}, new Set(['new']))).toEqual([{ id: 'new', command: `${agent} brief` }])
expect(original.data.initialCommand).toBe(`${agent} brief`)
})
it('preserves dependency and setup gates until delivery, including already-done dependencies', () => {
const node = queueControlLaunch({ id: 'new', data: { initialCommand: 'claude brief' } }, ['upstream'], 'setup')
const live = new Set(['new', 'upstream'])
expect(launchesToFire([node], {}, live, () => true)).toEqual([])
expect(launchesToFire([node], { upstream: { state: 'done' } }, live, () => false)).toEqual([])
expect(launchesToFire([node], { upstream: { state: 'done' } }, live, () => true)).toEqual([{ id: 'new', command: 'claude brief' }])
})
it('does not invent a launch for a plain shell or overwrite an existing hold', () => {
const node = armed('held', ['upstream'])
expect(queueControlLaunch(node)).toBe(node)
const shell = { data: {} }
expect(queueControlLaunch(shell)).toBe(shell)
})
it('does not infer running from delivery, idle, or absence of errors', () => {
expect(controlLaunchState(false, undefined)).toBeUndefined()
expect(controlLaunchState(false, undefined, { state: 'done' })).toBeUndefined()
expect(controlLaunchState(false, undefined, { state: 'working' })).toBe('working')
expect(controlLaunchState(false, undefined, { state: 'working', dropped: true })).toBe('dropped')
expect(controlLaunchState(true, { kind: 'failed', attempts: 5, at: 1 })).toBe('failed')
expect(controlLaunchState(true, { kind: 'stalled', since: 1 })).toBe('stalled')
expect(controlLaunchState(true, { kind: 'starting', since: 1 })).toBe('starting')
})
})
it('a dependency-free launch tooltip names delivery rather than an empty dependency', () => {
expect(launchTooltip(undefined, '', 'codex')).toBe('Queued; waiting for launch delivery.\nRuns:\ncodex')
})
it('an exhausted delivery stays held on rerender; a stalled terminal may still become ready', () => {
const node = armed('new', [])
const live = new Set(['new'])
expect(launchesToFire([node], {}, live, undefined, { new: { kind: 'failed', attempts: 5, at: 1 } })).toEqual([])
expect(node.data.pendingLaunch?.command).toBe('echo new')
expect(launchesToFire([node], {}, live, undefined, { new: { kind: 'stalled', since: 1 } })).toEqual([{ id: 'new', command: 'echo new' }])
})
it('a background start holds the canvas delivery too — core is typing into that pane (#925)', () => {
// The headless claim normally makes the node manualOnly first; this is the guard for a live
// copy that has not caught up with the claim yet, when the store already says `starting`.
const node = armed('new', [])
expect(launchesToFire([node], {}, new Set(['new']), undefined, { new: { kind: 'starting', since: 1 } })).toEqual([])
})
describe('deliveriesToRetire — the Canvas sweep (#925)', () => {
const byId = {
delivered: { kind: 'failed' as const, attempts: 1, at: 1 },
elsewhere: { kind: 'stalled' as const, since: 1 },
starting: { kind: 'starting' as const, since: 1 },
armed: { kind: 'stalled' as const, since: 1 }
}
it('retires every record whose node is not an armed node on the active canvas', () => {
expect(deliveriesToRetire(byId, (id) => id === 'armed')).toEqual(['delivered', 'elsewhere'])
})
it('never retires a start in flight: it runs for a node that is NOT on the active canvas', () => {
// Dropping it would re-enable ▶ the moment the user switches to that project, because the
// manualOnly claim alone reads as a failed launch.
expect(deliveriesToRetire({ starting: byId.starting }, () => false)).toEqual([])
})
})
it('a durable manual-only launch stays held after a reload and unrelated successful hooks', () => {
const node = armed('new', [])
node.data.pendingLaunch!.manualOnly = true
const restored = JSON.parse(JSON.stringify(node))
expect(launchesToFire([restored], { other: { state: 'done' } }, new Set(['new', 'other']))).toEqual([])
expect(restored.data.pendingLaunch.command).toBe('echo new')
})
it('manual recovery does not promise that retrying an errored dependency will automatically release it', () => {
const tooltip = launchTooltip({ kind: 'failed', attempts: 1, at: 0 }, 'upstream', 'claude brief', 'upstream')
expect(tooltip).toContain('automatic retry is stopped')
expect(tooltip).not.toContain('successful turn releases')
})
it('a refused relay launch explains host recovery rather than promising a working retry', () => {
const text = launchTooltip({ kind: 'failed', attempts: 1, at: 0 }, '', 'claude brief', undefined, true)
expect(text).toContain('Open the host to run this command')
expect(text).toContain('claude brief')
expect(text).not.toContain('press ▶')
})
describe('--after-pr: a PR wait is a third gate, ANDed with the deps and the setup script', () => {
const NOW = 5_000_000
const hold = (deadlineAt = NOW + 60_000) => ({
repository: 'o/r',
waits: [{ number: 7, until: 'merged' as const }],
deadlineAt,
armedAt: 0
})
const prNode = (after: string[], deadlineAt?: number): ArmedNode => ({
id: 'c',
data: { pendingLaunch: { after, command: 'echo c', afterPr: hold(deadlineAt) } }
})
const pull = (lifecycle: 'open' | 'merged') => ({
number: 7, lifecycle, headRefName: 'b', closes: [] as number[]
})
const board = (lifecycle: 'open' | 'merged') => ({
repository: 'o/r',
pulls: [pull(lifecycle)],
stale: false,
access: { ci: true, merge: true },
undecided: false,
truncated: false
})
const live = new Set(['a', 'c'])
const done: StatusById = { a: { state: 'done' } }
it('fires once the deps are done AND the PR has merged', () => {
expect(launchesToFire([prNode(['a'])], done, live, undefined, undefined, { board: board('merged'), now: NOW })).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('holds while the PR is open, however done the deps are', () => {
expect(launchesToFire([prNode(['a'])], done, live, undefined, undefined, { board: board('open'), now: NOW })).toEqual([])
})
it('holds while the deps are working, however merged the PR is', () => {
expect(
launchesToFire([prNode(['a'])], { a: { state: 'working' } }, live, undefined, undefined, { board: board('merged'), now: NOW })
).toEqual([])
})
it('a caller that passes no PR context never releases a PR hold — unknown is not satisfied', () => {
expect(launchesToFire([prNode([])], {}, live)).toEqual([])
})
it('never fires past the deadline', () => {
expect(
launchesToFire([prNode([], NOW)], {}, live, undefined, undefined, { board: board('merged'), now: NOW })
).toEqual([])
})
it('a node with no PR wait is unaffected by the PR context', () => {
expect(launchesToFire([armed('c', ['a'])], done, live, undefined, undefined, { board: undefined, now: NOW })).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('the list row says EXPIRED once the deadline passes (a delivery record still wins)', () => {
expect(controlLaunchState(true, undefined, undefined, true)).toBe('expired')
expect(controlLaunchState(true, undefined, undefined, false)).toBe('queued')
expect(controlLaunchState(true, { kind: 'failed', attempts: 1, at: 0 }, undefined, true)).toBe('failed')
})
it('the tooltip names the PR it waits on, beside any station', () => {
const pr = { expired: false, summary: 'PR #7 merged (open, not merged)', deadline: '18:00' }
expect(launchTooltip(undefined, 'Builder', 'claude', undefined, false, pr)).toBe(
'Waiting for Builder to finish and for PR #7 merged (open, not merged), until 18:00, then runs:\nclaude'
)
expect(launchTooltip(undefined, '', 'claude', undefined, false, pr)).toBe(
'Waiting for PR #7 merged (open, not merged), until 18:00, then runs:\nclaude'
)
})
it('an expired wait says it will not start on its own and offers ▶', () => {
const t = launchTooltip(undefined, 'Builder', 'claude', undefined, false, {
expired: true,
summary: 'PR #7 merged (open, not merged)',
deadline: '18:00'
})
expect(t).toMatch(/passed its deadline/)
expect(t).toMatch(/will not start on its own/)
expect(t).toMatch(/▶/)
})
it('without a PR wait the existing sentences are byte-identical', () => {
expect(launchTooltip(undefined, 'Builder', 'claude')).toBe('Waiting for Builder to finish, then runs:\nclaude')
})
})
describe('--after-success: a success wait is a fourth gate — the turn ending is not enough', () => {
const NOW = 5_000_000
// As every open path builds it: the station is in `after` too (a success wait is `--after` plus
// the report).
const successNode = (deps: string[], deadlineAt = NOW + 60_000, after = deps): ArmedNode => ({
id: 'c',
data: { pendingLaunch: { after, command: 'echo c', afterSuccess: { deps, deadlineAt } } }
})
const live = new Set(['a', 'b', 'c'])
const done: StatusById = { a: { state: 'done' }, b: { state: 'done' } }
const rec = (nodeId: string, outcome: 'succeeded' | 'failed') => ({ nodeId, outcome, at: 1 })
const ctx = (...records: ReturnType<typeof rec>[]) => ({
outcomes: Object.fromEntries(records.map((r) => [r.nodeId, r])),
now: NOW
})
const fire = (node: ArmedNode, status: StatusById, c?: ReturnType<typeof ctx>, l = live) =>
launchesToFire([node], status, l, undefined, undefined, undefined, c)
it('a reported success, turn over: fires', () => {
expect(fire(successNode(['a']), done, ctx(rec('a', 'succeeded')))).toEqual([{ id: 'c', command: 'echo c' }])
})
it('a reported FAILURE blocks — the dependent never starts on it', () => {
expect(fire(successNode(['a']), done, ctx(rec('a', 'failed')))).toEqual([])
})
it('no report yet holds, even though the turn is over (the whole point: done is not success)', () => {
expect(fire(successNode(['a']), done, ctx())).toEqual([])
})
it('a reported success mid-turn waits for the turn to end', () => {
expect(fire(successNode(['a']), { a: { state: 'working' } }, ctx(rec('a', 'succeeded')))).toEqual([])
})
it('an errored last turn holds even after a success report (#521 stands)', () => {
expect(
fire(successNode(['a']), { a: { state: 'done', lastTurnError: { at: 1 } } }, ctx(rec('a', 'succeeded')))
).toEqual([])
})
it('needs every station: one success is not enough', () => {
expect(fire(successNode(['a', 'b']), done, ctx(rec('a', 'succeeded')))).toEqual([])
expect(fire(successNode(['a', 'b']), done, ctx(rec('a', 'succeeded'), rec('b', 'succeeded')))).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('is ANDed with a plain --after on another station', () => {
const node = successNode(['a'], NOW + 60_000, ['a', 'b'])
expect(fire(node, { a: { state: 'done' }, b: { state: 'working' } }, ctx(rec('a', 'succeeded')))).toEqual([])
expect(fire(node, done, ctx(rec('a', 'succeeded')))).toEqual([{ id: 'c', command: 'echo c' }])
})
it('never fires past the deadline, whatever was reported', () => {
expect(fire(successNode(['a'], NOW), done, ctx(rec('a', 'succeeded')))).toEqual([])
})
it('a caller that passes no success context never releases a success hold', () => {
expect(fire(successNode(['a']), done, undefined)).toEqual([])
})
it('a CLOSED station releases only if it reported success before it went', () => {
const gone = new Set(['c'])
expect(fire(successNode(['a']), {}, ctx(rec('a', 'succeeded')), gone)).toEqual([{ id: 'c', command: 'echo c' }])
// For plain `--after` a deleted station is satisfied; for a success wait it is not — closing a
// station is exactly how an orchestrator abandons a failed attempt.
expect(fire(successNode(['a']), {}, ctx(), gone)).toEqual([])
expect(fire(successNode(['a']), {}, ctx(rec('a', 'failed')), gone)).toEqual([])
})
it('a hostile persisted hold never throws and never fires', () => {
for (const bad of ['a', ['a'], { deps: 'a', deadlineAt: NOW + 1 }, { deps: [42], deadlineAt: NOW + 1 }, 7]) {
const node = {
id: 'c',
data: { pendingLaunch: { after: ['a'], command: 'echo c', afterSuccess: bad } }
} as unknown as ArmedNode
expect(() => fire(node, done, ctx(rec('a', 'succeeded')))).not.toThrow()
expect(fire(node, done, ctx(rec('a', 'succeeded')))).toEqual([])
}
})
it('successDepFacts reads the --after rule for the turn and an OWN record only', () => {
expect(successDepFacts('a', done, live, {})).toEqual({ exists: true, turnDone: true })
expect(successDepFacts('constructor', {}, new Set(), {})).toEqual({ exists: false, turnDone: false })
})
it('the list row names the wait: waiting, blocked, expired — a delivery record still wins', () => {
expect(controlLaunchState(true, undefined, undefined, false, 'waiting')).toBe('waiting-success')
expect(controlLaunchState(true, undefined, undefined, false, 'blocked')).toBe('blocked-failure')
expect(controlLaunchState(true, undefined, undefined, false, 'expired')).toBe('success-expired')
expect(controlLaunchState(true, undefined, undefined, false, 'met')).toBe('queued')
expect(controlLaunchState(true, { kind: 'failed', attempts: 1, at: 0 }, undefined, false, 'blocked')).toBe('failed')
})
it('the tooltip says why it waits, why it is blocked, and that an expired wait needs ▶', () => {
const waiting = launchTooltip(undefined, 'Linter', 'claude', undefined, false, undefined, {
status: 'waiting',
summary: 'Builder (no outcome reported yet)',
deadline: '18:00'
})
expect(waiting).toBe(
'Waiting for Linter to finish and for a reported success from Builder (no outcome reported yet), until 18:00, then runs:\nclaude'
)
const blocked = launchTooltip(undefined, '', 'claude', undefined, false, undefined, {
status: 'blocked',
summary: 'Builder (reported failure: "red")',
deadline: '18:00'
})
expect(blocked).toContain('Held on Builder (reported failure: "red")')
expect(blocked).toContain('▶')
const expired = launchTooltip(undefined, '', 'claude', undefined, false, undefined, {
status: 'expired',
summary: '',
deadline: '18:00'
})
expect(expired).toMatch(/passed its deadline \(18:00\)/)
expect(expired).toMatch(/will not start on its own/)
})
})
describe('plain --after on a station handed new work (core/station-handover.ts)', () => {
const live = new Set(['a', 'b', 'c'])
const status: StatusById = { a: { state: 'done' }, b: { state: 'done' } }
const handovers = { a: { nodeId: 'a', since: 10 } }
it('a handed-over station is never a satisfied dep, whatever its state reads', () => {
expect(launchesToFire([armed('c', ['a', 'b'])], status, live, undefined, undefined, undefined, undefined, handovers)).toEqual([])
expect(unmetDeps(armed('c', ['a', 'b']), status, live, handovers)).toEqual(['a'])
expect(handedOverDeps(armed('c', ['a', 'b']), live, handovers)).toEqual(['a'])
})
it('without a hand-over the same state fires as before', () => {
expect(launchesToFire([armed('c', ['a', 'b'])], status, live, undefined, undefined, undefined, undefined, {})).toEqual([
{ id: 'c', command: 'echo c' }
])
})
it('a deleted station still counts as satisfied, hand-over or not', () => {
expect(launchesToFire([armed('c', ['a'])], {}, new Set(['c']), undefined, undefined, undefined, undefined, handovers)).toEqual([
{ id: 'c', command: 'echo c' }
])
expect(handedOverDeps(armed('c', ['a']), new Set(['c']), handovers)).toEqual([])
})
it('a success wait on a handed-over station holds: its turn is not over', () => {
expect(successDepFacts('a', status, live, {}, handovers).turnDone).toBe(false)
expect(successDepFacts('a', status, live, {}).turnDone).toBe(true)
})
it('a prototype key is not a hand-over', () => {
const bare = Object.create(null) as Record<string, undefined>
expect(handedOverDeps(armed('c', ['constructor', '__proto__']), new Set(['constructor', '__proto__']), bare)).toEqual([])
expect(handedOverDeps(armed('c', ['constructor']), new Set(['constructor']), {})).toEqual([])
})
it('the tooltip says what the wait is for, not "waiting for X to finish" about an idle X', () => {
const text = launchTooltip(undefined, 'Builder, Tester', 'claude go', undefined, false, undefined, undefined, undefined, 'Builder')
expect(text).toBe(
'Waiting for Builder to finish — a turn that ended before that work was done does not count ' +
'(all waits: Builder, Tester), then runs:\nclaude go'
)
// An errored upstream is still named first: it will not end on its own.
expect(launchTooltip(undefined, 'Builder', 'claude go', 'Tester', false, undefined, undefined, 'Builder')).toMatch(/^Tester ended/)
})
})
describe('withSuccessHold — the sibling of withPrHold', () => {
const hold = { deps: ['a'], deadlineAt: 9 }
it('adds the hold to a node that already holds its launch, and only then', () => {
const node = { id: 'n', data: { pendingLaunch: { after: ['a'], command: 'c' } } }
expect(withSuccessHold(node, hold).data.pendingLaunch).toEqual({ after: ['a'], command: 'c', afterSuccess: hold })
expect(withSuccessHold(node, undefined)).toBe(node)
const bare = { id: 'n', data: {} as { pendingLaunch?: PendingLaunch } }
expect(withSuccessHold(bare, hold)).toBe(bare)
})
})
describe('withPrHold — one way every open path attaches a PR wait', () => {
const hold = { repository: 'o/r', waits: [{ number: 7, until: 'merged' as const }], deadlineAt: 9, armedAt: 0 }
it('adds the hold to a node that already holds its launch', () => {
const node = { id: 'n', data: { pendingLaunch: { after: ['a'], command: 'c', attempted: false } } }
expect(withPrHold(node, hold).data.pendingLaunch).toEqual({ after: ['a'], command: 'c', attempted: false, afterPr: hold })
})
it('leaves a node alone when there is no hold, or nothing is held to attach it to', () => {
const held = { id: 'n', data: { pendingLaunch: { after: [], command: 'c' } } }
expect(withPrHold(held, undefined)).toBe(held)
const bare = { id: 'n', data: {} as { pendingLaunch?: PendingLaunch } }
expect(withPrHold(bare, hold)).toBe(bare)
})
})
describe('the launch brief file is verified at DELIVERY, not only at open (#1014 review)', () => {
const node = { id: 'n', data: { pendingLaunch: { after: [], command: 'claude "$(cat \'/x/p.txt\')"' } } }
it('withLaunchBrief records the file the command reads; nothing held, nothing recorded', () => {
expect(withLaunchBrief(node, '/x/p.txt').data.pendingLaunch).toMatchObject({ promptFile: '/x/p.txt' })
expect(withLaunchBrief(node, undefined)).toBe(node)
const bare = { id: 'b', data: {} as { pendingLaunch?: { after: string[]; command: string } } }
expect(withLaunchBrief(bare, '/x/p.txt')).toBe(bare)
})
it('launchesToFire hands the file to the loop, which checks it before typing', () => {
const armedWithBrief = withLaunchBrief(node, '/x/p.txt')
expect(launchesToFire([armedWithBrief], {}, new Set(['n']))).toEqual([
{ id: 'n', command: armedWithBrief.data.pendingLaunch.command, briefFile: '/x/p.txt' }
])
})
it('a missing brief is a named, manual hold — never an agent started with no brief', () => {
const t = launchTooltip({ kind: 'brief-missing', path: '/x/p.txt', at: 1 }, '', 'claude')
expect(t).toContain('/x/p.txt')
expect(t).toMatch(/no longer exists/)
expect(t).toMatch(/no brief/)
expect(t).toMatch(/▶/)
expect(controlLaunchState(true, { kind: 'brief-missing', path: '/x/p.txt', at: 1 })).toBe('brief-missing')
})
})
describe('launchBriefPresent — only a definite "not there" holds a launch', () => {
const local = { id: 'p' }
it('no file to check is present', async () => {
const exists = vi.fn(async () => false)
expect(await launchBriefPresent(undefined, local, exists)).toBe(true)
expect(exists).not.toHaveBeenCalled()
})
it('a local file that is gone is absent; one that is there is present', async () => {
expect(await launchBriefPresent('/x', local, async () => false)).toBe(false)
expect(await launchBriefPresent('/x', local, async () => true)).toBe(true)
})
it('a check that fails answers present — the open-time check fails open the same way', async () => {
expect(await launchBriefPresent('/x', local, async () => { throw new Error('EIO') })).toBe(true)
expect(await launchBriefPresent('/x', local, () => { throw new Error('sync') })).toBe(true)
})
it('an SSH or relay project is never judged from here (a false there is not evidence of absence)', async () => {
const exists = vi.fn(async () => false)
expect(await launchBriefPresent('/x', { id: 'p', ssh: {} }, exists)).toBe(true)
expect(await launchBriefPresent('/x', { id: 'p', remote: true }, exists)).toBe(true)
expect(await launchBriefPresent('/x', undefined, exists)).toBe(true)
expect(exists).not.toHaveBeenCalled()
})
})
describe('firstOpenInFlight (one rule for the canvas node and the board card)', () => {
const plain: PendingLaunch = { after: [], command: 'claude', manualOnly: true }
it('is in flight only with the initialCommand alias, no reported delivery and no hold', () => {
expect(firstOpenInFlight(true, plain, undefined)).toBe(true)
expect(firstOpenInFlight(false, plain, undefined)).toBe(false)
})
it('a reported delivery (failed, stalled, starting) is no longer "in flight"', () => {
expect(firstOpenInFlight(true, plain, { kind: 'failed', attempts: 1, at: 0 })).toBe(false)
})
it('a real hold always shows', () => {
expect(firstOpenInFlight(true, { ...plain, after: ['a1'] }, undefined)).toBe(false)
expect(firstOpenInFlight(true, { ...plain, awaitSetupGroup: 'g1' }, undefined)).toBe(false)
})
})