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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { spawn } from 'node:child_process'
import { createInterface } from 'node:readline'
import { createSuperTabTerminal } from './inCore/terminal.js'
import { screen as codexScreen } from '../engines/codex/screen.js'
import type { RegisteredSession } from '../lib/registry.js'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it, vi } from 'vitest'
import type { CoreApi, SuperTabScreen } from '../core/api.js'
import { fakeCore } from '../testing/fakeCore.js'
import { CODEX_MODEL_MIGRATION, CODEX_SIGN_IN, CODEX_TRUST_PROMPT, CODEX_UPDATE_PROMPT } from '../lib/__fixtures__/takeoverScreens.js'
import { capScreen, limitOf, modelFailing, signedOut, TerminalHost, typedKeys } from './terminal.js'
const row = (agentId = 'a1', harnessId = 'h1', over: Record<string, unknown> = {}) => ({ tabId: 'tab', agent: { id: agentId, harnessId, machineId: 'm1' }, ...over })
type Sent = { path: string; body: Record<string, any> }
function setup(options: { live?: string[]; screen?: (harnessId: string) => SuperTabScreen; requests?: unknown[];
refuse?: (command: Record<string, any>) => { status: number; code: string } | null; engine?: string } = {}) {
let clock = 1_000_000
const sent: Sent[] = []
let pending = options.requests ?? []
const backend: CoreApi['account']['backend'] = vi.fn(async (method, path, body) => {
if (path === '/api/super-tabs/hosts/m1/terminal') { const rows = pending; pending = []; return { status: 200, body: { success: true, data: rows } } }
sent.push({ path, body: body as Record<string, any> })
const refused = options.refuse?.((body as Record<string, any>).command)
if (refused) return { status: refused.status, body: { success: false, error: { code: refused.code, message: 'Refused.' } } }
return { status: 200, body: { success: true, data: { result: {} } } }
})
let screen = options.screen ?? (() => ({ ok: true as const, text: '> ', hold: null }))
const core = fakeCore({
account: { backend },
agents: { byAgent: vi.fn((id: string) => (options.live ?? ['h1']).includes(id) ? { agentId: id, engine: options.engine ?? 'claude' } as never : undefined) },
superTabs: { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(),
screen: vi.fn(async (harnessId: string) => screen(harnessId)), input: vi.fn(async () => ({ ok: true as const })), inputIfScreen: vi.fn(async () => ({ ok: true as const })) },
})
const host = new TerminalHost(core, 'm1', { now: () => clock, log: vi.fn() })
return { core, backend, sent, host,
now: () => clock,
wait: (ms: number) => { clock += ms },
request: (...rows: unknown[]) => { pending = rows },
showing: (next: (harnessId: string) => SuperTabScreen) => { screen = next },
polls: () => vi.mocked(backend).mock.calls.filter(([, path]) => path === '/api/super-tabs/hosts/m1/terminal').length,
alerts: () => sent.filter(s => s.body.command.type === 'agent.alert').map(s => s.body.command) }
}
/** A screen as the engine draws it (fixtures/screens). */
const fixture = (name: string) => readFileSync(new URL(`./fixtures/screens/${name}.txt`, import.meta.url), 'utf8')
const screenRequest = (over: Record<string, unknown> = {}) => ({ tabId: 'tab', agentId: 'a1', harnessId: 'h1', request: { id: 'r1', kind: 'screen' }, ...over })
describe('a host serving its Lead\'s terminal requests', () => {
it('reads the screen of its own agent and answers as that agent', async () => {
const t = setup({ requests: [screenRequest({ request: { id: 'r1', kind: 'screen', scrollback: 50 } })],
screen: () => ({ ok: true, text: 'Allow edit? 1. Yes 2. No', hold: 'permission_open' }) })
await t.host.tick([row()])
expect(t.core.superTabs!.screen).toHaveBeenCalledWith('h1', 50)
expect(t.sent).toEqual([{ path: '/api/super-tabs/tab/commands', body: { operationId: 'terminal-r1', asAgentId: 'a1',
command: { type: 'agent.screenResult', requestId: 'r1', ok: true, text: 'Allow edit? 1. Yes 2. No' } } }])
})
it('refuses a request whose harness is not the one running here, and never reads or types for it', async () => {
const t = setup({ requests: [screenRequest({ harnessId: 'h-old' }),
{ tabId: 'tab', agentId: 'a1', harnessId: 'h-old', request: { id: 'r2', kind: 'input', text: 'y' } }] })
await t.host.tick([row()])
// The one read is the alert watch's own.
expect(t.core.superTabs!.screen).toHaveBeenCalledOnce()
expect(t.core.superTabs!.input).not.toHaveBeenCalled()
expect(t.sent.map(s => s.body.command).sort((x, y) => x.requestId.localeCompare(y.requestId))).toEqual([
{ type: 'agent.screenResult', requestId: 'r1', ok: false, error: 'This agent\'s terminal on this machine changed. Ask again.' },
{ type: 'agent.inputResult', requestId: 'r2', ok: false, error: 'This agent\'s terminal on this machine changed. Ask again.' }])
})
it('never answers as another machine\'s agent, and tells at once that a stopping one or one not running here is not running', async () => {
const t = setup({ live: ['h1', 'h3'], requests: [screenRequest({ agentId: 'a9', harnessId: 'h9' }), screenRequest({ agentId: 'a2', harnessId: 'h2' }),
screenRequest({ agentId: 'a3', harnessId: 'h3', request: { id: 'r3', kind: 'screen' } }), screenRequest({ agentId: 'a4', harnessId: 'h4', request: { id: 'r4', kind: 'input', keys: ['Enter'] } })] })
await t.host.tick([row(), { tabId: 'tab', agent: { id: 'a2', harnessId: 'h2', machineId: 'm2' } }, row('a3', 'h3', { stopRequested: true }), row('a4', 'h4')])
expect(vi.mocked(t.core.superTabs!.screen).mock.calls).toEqual([['h1', 0]])
expect(t.core.superTabs!.input).not.toHaveBeenCalled()
expect(t.sent.map(s => [s.body.asAgentId, s.body.command]).sort()).toEqual([
['a3', { type: 'agent.screenResult', requestId: 'r3', ok: false, error: 'This agent is not running on this machine.' }],
['a4', { type: 'agent.inputResult', requestId: 'r4', ok: false, error: 'This agent is not running on this machine.' }]])
})
it('asks for requests while only a stopping agent is here, so its requests are answered', async () => {
const t = setup({ requests: [screenRequest({ agentId: 'a3', harnessId: 'h3' })] })
await t.host.tick([row('a3', 'h3', { stopRequested: true })])
expect(t.sent.map(s => s.body.command.error)).toEqual(['This agent is not running on this machine.'])
})
it('refuses typed text with a newline or another control character: those are keys, sent by name', async () => {
const t = setup({ requests: ['a\nrm -rf x', 'a\u001b[A', 'ok\u007f'].map((text, i) => ({ tabId: 'tab', agentId: 'a1', harnessId: 'h1', request: { id: `r${i}`, kind: 'input', text } })) })
await t.host.tick([row()])
expect(t.core.superTabs!.input).not.toHaveBeenCalled()
expect(t.sent.map(s => s.body.command.error)).toEqual(Array(3).fill('Send Enter and other keys as named keys, not in the text.'))
})
it('caps the screen at 64 KB, keeping its end and never splitting a character', async () => {
expect(capScreen('short')).toBe('short')
const long = `${'x'.repeat(70_000)}é${'y'.repeat(65_535)}`
const capped = capScreen(long)
expect(Buffer.byteLength(capped)).toBeLessThanOrEqual(65_536)
expect(capped).toBe('y'.repeat(65_535))
const t = setup({ requests: [screenRequest()], screen: () => ({ ok: true, text: 'z'.repeat(100_000), hold: null }) })
await t.host.tick([row()])
expect(Buffer.byteLength(t.sent[0].body.command.text)).toBe(65_536)
})
it('types the text and the named keys, mapped to the terminal\'s own key names', async () => {
expect(typedKeys(['Enter', 'Esc', 'Tab', 'Up', 'Down', 'Left', 'Right', 'Ctrl-C', '0', '9'])).toEqual(['Enter', 'Escape', 'Tab', 'Up', 'Down', 'Left', 'Right', 'C-c', '0', '9'])
expect(typedKeys(['esc', 'ctrl-c', 'ENTER'])).toEqual(['Escape', 'C-c', 'Enter'])
expect(typedKeys(['Enter', 'C-d'])).toBe('Unknown key: C-d.')
expect(typedKeys(['F1'])).toBe('Unknown key: F1.')
const t = setup({ requests: [{ tabId: 'tab', agentId: 'a1', harnessId: 'h1', request: { id: 'r1', kind: 'input', text: '2', keys: ['Enter'] } },
{ tabId: 'tab', agentId: 'a1', harnessId: 'h1', request: { id: 'r2', kind: 'input', keys: ['Home'] } }] })
await t.host.tick([row()])
expect(t.core.superTabs!.input).toHaveBeenCalledOnce()
expect(t.core.superTabs!.input).toHaveBeenCalledWith('h1', '2', ['Enter'])
expect(t.sent.map(s => s.body.command).sort((x, y) => x.requestId.localeCompare(y.requestId))).toEqual([{ type: 'agent.inputResult', requestId: 'r1', ok: true },
{ type: 'agent.inputResult', requestId: 'r2', ok: false, error: 'Unknown key: Home.' }])
})
it('passes on why the core could not read the screen', async () => {
const t = setup({ requests: [screenRequest()], screen: () => ({ ok: false, error: 'Could not read the terminal: pane gone' }) })
await t.host.tick([row()])
expect(t.sent[0].body.command).toEqual({ type: 'agent.screenResult', requestId: 'r1', ok: false, error: 'Could not read the terminal: pane gone' })
// The backend takes a reason of at most 500 characters.
t.showing(() => ({ ok: false, error: `Could not read the terminal: ${'x'.repeat(600)}` }))
t.request(screenRequest({ request: { id: 'r2', kind: 'screen' } }))
t.wait(3_000); await t.host.tick([row()])
expect(t.sent[1].body.command.error).toHaveLength(500)
})
it('asks for requests every 3 seconds, and not at all without a Swarm agent here', async () => {
const t = setup()
await t.host.tick([])
await t.host.tick([{ tabId: 'tab', agent: { id: 'a2', harnessId: 'h2', machineId: 'm2' } }])
expect(t.polls()).toBe(0)
await t.host.tick([row()])
expect(t.polls()).toBe(1)
t.wait(2_000)
await t.host.tick([row()])
expect(t.polls()).toBe(1)
t.wait(1_000)
await t.host.tick([row()])
expect(t.polls()).toBe(2)
})
})
// Spec 2026-11-02-poll-cost Part 4.2: every host of a Swarm agent asked every 3 s, almost always for nothing (prod 2026-11-02:
// 305 a minute, each a transaction). A server that pushes deliveries also says when a terminal request waits for this
// machine (`__terminal_waiting`). Task #2800: the 8 s fallback that followed was still almost all empty; the sender's wait now
// tells the machine again at each re-check while the request waits (backend store.ts terminalResult), inside the 10 s pickup,
// so with the push lease the host asks only when told.
describe('terminal requests the server pushes', () => {
it('with the push lease, asks only when told, and at once on __terminal_waiting', async () => {
let pushing = true
const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => pushing })
for (let second = 0; second < 60; second++) { await host.tick([row()]); t.wait(1_000) }
expect(t.polls()).toBe(0)
// Told a request waits: answered now, before the backend's 10 s are out.
t.request(screenRequest())
await host.waiting()
expect(t.polls()).toBe(1)
expect(t.sent.map(s => s.body.command.type)).toEqual(['agent.screenResult'])
for (let second = 0; second < 60; second++) { t.wait(1_000); await host.tick([row()]) }
expect(t.polls()).toBe(1)
// The lease lapses: every 3 s again.
pushing = false
t.wait(3_000); await host.tick([row()])
expect(t.polls()).toBe(2)
})
it('without it, polls every 3 s', async () => {
const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => false })
for (let second = 0; second < 9; second++) { await host.tick([row()]); t.wait(1_000) }
expect(t.polls()).toBe(3)
})
it('picks up nothing on a push before the host has read its roster, or with no Swarm agent here', async () => {
const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => true })
await host.waiting()
await host.tick([])
await host.waiting()
expect(t.polls()).toBe(0)
})
it('picks up once more after a push that came during a pickup', async () => {
const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => true })
await host.tick([row()])
const first = host.waiting()
const pushed = host.waiting()
await first; await pushed
await vi.waitFor(() => expect(t.polls()).toBe(2))
})
})
describe('the stuck and usage-limit alerts', () => {
const prompt = (): SuperTabScreen => ({ ok: true, text: 'Do you want to proceed?\n❯ 1. Yes\n 2. No', hold: 'permission_open' })
const idle = (): SuperTabScreen => ({ ok: true, text: '> ', hold: null })
// Ken's prod scan (11-04): 116 agent.alert refusals in 32 minutes, AGENT_UNAVAILABLE: an alert the Swarm will never take
// (its agent gone or to be shared again) was tried again on every 15-second read.
it('does not send again an alert the Swarm refused for good (#2675)', async () => {
const t = setup({ screen: prompt, refuse: command => command.type === 'agent.alert' ? { status: 400, code: 'AGENT_UNAVAILABLE' } : null })
await t.host.tick([row()])
t.wait(180_000); await t.host.tick([row()])
expect(t.alerts()).toHaveLength(1)
for (let i = 0; i < 20; i++) { t.wait(15_000); await t.host.tick([row()]) }
expect(t.alerts()).toHaveLength(1)
})
it('backs off an alert the backend could not take for now (#2675)', async () => {
const t = setup({ screen: prompt, refuse: command => command.type === 'agent.alert' ? { status: 503, code: 'BACKEND_UNAVAILABLE' } : null })
await t.host.tick([row()])
t.wait(180_000); await t.host.tick([row()])
// Ten minutes of reads: 40 tries at the old pace.
for (let i = 0; i < 40; i++) { t.wait(15_000); await t.host.tick([row()]) }
expect(t.alerts().length).toBeGreaterThanOrEqual(2)
expect(t.alerts().length).toBeLessThanOrEqual(8)
})
it('alerts once when a prompt has waited 3 minutes, and ends the episode when it is answered', async () => {
const t = setup({ screen: prompt })
await t.host.tick([row()])
t.wait(150_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([])
t.wait(30_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'prompt', active: true }])
for (let i = 0; i < 5; i++) { t.wait(15_000); await t.host.tick([row()]) }
expect(t.alerts()).toHaveLength(1)
t.showing(idle); t.wait(15_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'prompt', active: true }, { type: 'agent.alert', agentId: 'a1', alert: 'prompt', active: false }])
// A new prompt is a new episode, with its own 3 minutes.
t.showing(prompt); t.wait(15_000); await t.host.tick([row()])
t.wait(150_000); await t.host.tick([row()])
expect(t.alerts()).toHaveLength(2)
t.wait(30_000); await t.host.tick([row()])
expect(t.alerts()).toHaveLength(3)
expect(new Set(t.sent.map(s => s.body.operationId)).size).toBe(3)
})
it('never alerts for a prompt answered within 3 minutes, nor ends an episode it never began', async () => {
const t = setup({ screen: prompt })
await t.host.tick([row()])
t.showing(idle); t.wait(120_000); await t.host.tick([row()])
t.showing(prompt); t.wait(120_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([])
})
it('reads the screen only every 15 seconds', async () => {
const t = setup({ screen: idle })
await t.host.tick([row()])
t.wait(5_000); await t.host.tick([row()])
expect(t.core.superTabs!.screen).toHaveBeenCalledOnce()
t.wait(10_000); await t.host.tick([row()])
expect(t.core.superTabs!.screen).toHaveBeenCalledTimes(2)
})
it('alerts once for a usage-limit screen with its reset time, and ends it when the screen moves on', async () => {
const t = setup({ screen: () => ({ ok: true, text: 'Working on it\n\n■ You\'ve hit your usage limit. Upgrade to Pro or try again in 1 hour 30 minutes.\n> ', hold: null }) })
await t.host.tick([row()])
t.wait(15_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'limit', active: true, resetAt: new Date(1_000_000 + 90 * 60_000).toISOString() }])
t.showing(idle); t.wait(15_000); await t.host.tick([row()])
expect(t.alerts()[1]).toEqual({ type: 'agent.alert', agentId: 'a1', alert: 'limit', active: false })
})
it('alerts once its model has failed for 10 minutes, and ends it when answers come again', async () => {
const failing = (): SuperTabScreen => ({ ok: true, text: '✻ Waiting for API response · will retry in 2m 38s · check your network\n❯ ', hold: null })
const t = setup({ screen: failing })
await t.host.tick([row()])
t.wait(540_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([])
t.wait(60_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'model', active: true }])
// Answers coming again end it only once no retry has shown for ten minutes.
t.showing(idle); t.wait(15_000); await t.host.tick([row()])
expect(t.alerts()).toHaveLength(1)
t.wait(585_000); await t.host.tick([row()])
expect(t.alerts()[1]).toEqual({ type: 'agent.alert', agentId: 'a1', alert: 'model', active: false })
})
it('raises nothing for a burst of failures that recovers before ten minutes, so its task is never lost for it', async () => {
// Last night's reviewer failures came and went (429 bursts): nine minutes of retries, then answers for ten.
const failing = (): SuperTabScreen => ({ ok: true, text: '✻ Waiting for API response · will retry in 2m 38s · check your network\n❯ ', hold: null })
const t = setup({ screen: failing })
await t.host.tick([row()])
t.wait(539_000); await t.host.tick([row()])
t.showing(idle)
for (let second = 0; second < 600; second += 15) { t.wait(15_000); await t.host.tick([row()]) }
// A second burst starts its own ten minutes.
t.showing(failing); t.wait(15_000); await t.host.tick([row()])
t.wait(539_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([])
})
it('counts retries with fresh attempts between them as one failing stretch', async () => {
// Claude Code shows its countdown, then a plain spinner for the minutes each new attempt takes.
const failing = (): SuperTabScreen => ({ ok: true, text: '✻ Waiting for API response · will retry in 1m 18s · check your network\n❯ ', hold: null })
const attempt = (): SuperTabScreen => ({ ok: true, text: '✻ Thinking… (4m 12s · esc to interrupt)\n❯ ', hold: null })
const t = setup({ screen: failing })
await t.host.tick([row()])
for (let minute = 0; minute < 10; minute += 2) {
t.showing(attempt); t.wait(60_000); await t.host.tick([row()])
t.showing(failing); t.wait(60_000); await t.host.tick([row()])
}
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'model', active: true }])
})
it.each(['claude-session-limit', 'claude-weekly-limit', 'claude-opus-limit', 'claude-fable-limit', 'codex-usage-limit', 'codex-model-limit'])(
'alerts for the %s screen', async name => {
const t = setup({ screen: () => ({ ok: true, text: fixture(name), hold: null }) })
await t.host.tick([row()])
expect(t.alerts()).toEqual([expect.objectContaining({ type: 'agent.alert', agentId: 'a1', alert: 'limit', active: true })])
})
it('tries an alert the backend did not take again on the next read', async () => {
const t = setup({ screen: () => ({ ok: true, text: 'Claude usage limit reached. Your limit will reset at 3pm.', hold: null }) })
const real = vi.mocked(t.backend).getMockImplementation()!
let failed = false
vi.mocked(t.backend).mockImplementation(async (method, path, body) => {
if (!failed && path.endsWith('/commands')) { failed = true; return { status: 503, body: { success: false } } }
return real(method, path, body)
})
await t.host.tick([row()])
t.wait(15_000); await t.host.tick([row()])
expect(t.alerts()).toHaveLength(1)
})
})
// Task #3301: an agent signed out of its model showed Claude Code's signed-out notice and sat there until a person came
// (Quince, 2026-11-05: "Not logged in · Please run /login"). The watch reads it as a model the agent gets no answer from.
describe('an agent signed out of its model (task #3301)', () => {
const NOT_LOGGED_IN = '⏺ I will run the tests.\n\n ⎿ Not logged in · Please run /login\n\n❯ \n ? for shortcuts'
it('knows Claude Code\'s and Codex\'s own signed-out notices near the prompt', () => {
for (const line of [' ⎿ Not logged in · Please run /login', '⎿ API Error: 401 {"type":"error","error":{"type":"authentication_error"}} · Please run /login',
' ⎿ Invalid API key · Please run /login', ' ⎿ OAuth token has expired · Please run /login', '■ unexpected status 401 Unauthorized: Missing bearer authentication']) {
expect(signedOut(`⏺ work\n\n${line}\n❯ `), line).toBe(true)
}
expect(modelFailing(NOT_LOGGED_IN)).toBe(false)
})
it('never reads the agent\'s own words, a tool\'s output or an old notice far up the screen as signed out', () => {
// An agent working on this very bug writes and prints these lines: restarting it would cost its turn.
expect(signedOut('⏺ Quince showed "Not logged in · Please run /login" after the update.\n❯ ')).toBe(false)
expect(signedOut(' The brief says API Error: 401 is not recovered.\n❯ ')).toBe(false)
expect(signedOut('⏺ Bash(echo "Not logged in · Please run /login")\n ⎿ Not logged in · Please run /login\n❯ ')).toBe(false)
expect(signedOut(` ⎿ Not logged in · Please run /login\n${'line\n'.repeat(30)}❯ `)).toBe(false)
// A reply that starts with the phrase is still the agent's own words, Claude Code's "⏺" or Codex's "•" (security review 2).
expect(signedOut('⏺ Not logged in users are sent to /login, so the server never sees them.\n❯ ')).toBe(false)
expect(signedOut('⏺ API Error: 401 comes from the server when its token is stale.\n❯ ')).toBe(false)
expect(signedOut('• Invalid API key is what Codex prints for a stale token.\n› ')).toBe(false)
})
})
describe('dismissing Codex\'s update screen for a Swarm agent', () => {
const update = (): SuperTabScreen => ({ ok: true, text: CODEX_UPDATE_PROMPT, hold: 'update_prompt_open' })
const idle = (): SuperTabScreen => ({ ok: true, text: '> ', hold: null })
const dismissed = (t: ReturnType<typeof setup>) => vi.mocked(t.core.superTabs!.inputIfScreen).mock.calls
it('sends Esc through the core\'s if-screen door with the screen it read, types nothing itself, and raises no alert', async () => {
const t = setup({ screen: update })
await t.host.tick([row()])
expect(dismissed(t)).toEqual([['h1', ['Escape'], CODEX_UPDATE_PROMPT]])
expect(t.core.superTabs!.input).not.toHaveBeenCalled()
t.showing(idle)
for (let i = 0; i < 14; i++) { t.wait(15_000); await t.host.tick([row()]) }
expect(dismissed(t)).toHaveLength(1)
expect(t.alerts()).toEqual([])
})
it('answers only the agent whose screen shows it, and only a Swarm agent of this machine', async () => {
const t = setup({ screen: harnessId => harnessId === 'h2' ? update() : idle(), live: ['h1', 'h2', 'h3'] })
await t.host.tick([row('a1', 'h1'), row('a2', 'h2'), { tabId: 'tab', agent: { id: 'a3', harnessId: 'h3', machineId: 'other' } }])
expect(dismissed(t)).toEqual([['h2', ['Escape'], CODEX_UPDATE_PROMPT]])
})
it.each([['trust', CODEX_TRUST_PROMPT, 'trust_open'], ['model', CODEX_MODEL_MIGRATION, 'model_prompt_open'],
['sign-in', CODEX_SIGN_IN, 'sign_in_open'], ['permission', 'Allow? 1. Yes', 'permission_open']] as const)('asks for nothing on the %s screen', async (_name, text, hold) => {
const t = setup({ screen: () => ({ ok: true, text, hold }) })
await t.host.tick([row()])
expect(dismissed(t)).toEqual([])
})
it('asks for nothing when the update screen is misread (a Skip row as 0), and alerts as before after 3 minutes', async () => {
const t = setup({ screen: () => ({ ok: true, text: CODEX_UPDATE_PROMPT.replace(' 2. Skip\n', ' 0. Skip\n'), hold: 'update_prompt_open' }) })
await t.host.tick([row()])
t.wait(180_000); await t.host.tick([row()])
expect(dismissed(t)).toEqual([])
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'prompt', active: true }])
})
it('tries three times at most when the screen stays, then leaves it to the 3-minute alert', async () => {
const t = setup({ screen: update })
for (let i = 0; i < 12; i++) { await t.host.tick([row()]); t.wait(15_000) }
await t.host.tick([row()])
expect(dismissed(t)).toHaveLength(3)
expect(t.alerts()).toEqual([{ type: 'agent.alert', agentId: 'a1', alert: 'prompt', active: true }])
})
it('starts the tries again for a new update screen once the old one is gone', async () => {
const t = setup({ screen: update })
await t.host.tick([row()])
t.showing(idle); t.wait(15_000); await t.host.tick([row()])
t.showing(update); t.wait(15_000); await t.host.tick([row()])
expect(dismissed(t)).toHaveLength(2)
})
it('goes on watching when the core refuses, because the screen had changed or the terminal did not take the key', async () => {
const t = setup({ screen: update })
vi.mocked(t.core.superTabs!.inputIfScreen).mockResolvedValueOnce({ ok: false, error: 'The screen changed before the key was sent; nothing was typed.' })
vi.mocked(t.core.superTabs!.inputIfScreen).mockRejectedValueOnce(new Error('core gone'))
await t.host.tick([row()])
t.wait(15_000); await t.host.tick([row()])
t.wait(15_000); await t.host.tick([row()])
expect(dismissed(t)).toHaveLength(3)
})
})
// Nova, the Lead of the Swarm autonomous-harness (2026-10-29): Claude Code's drafted bug report covered its prompt, and every
// message to it came back undelivered until someone pressed a key in its terminal.
describe('dismissing Claude Code\'s feedback popups for a Swarm agent', () => {
const DRAFT = '│ ✻ Bug report drafted: Lead switched Codex model │\n│ 1 to review · 2 to send · 0 to dismiss │\n────\n❯ '
const TURN_OFF = 'Turn off Claude-drafted feedback? 0 to turn off · Esc to keep\n────\n❯ '
const dismissed = (t: ReturnType<typeof setup>) => vi.mocked(t.core.superTabs!.inputIfScreen).mock.calls
it('dismisses the draft with 0, then keeps the setting with Esc, through the if-screen door, and raises no alert', async () => {
const t = setup({ screen: () => ({ ok: true, text: DRAFT, hold: 'prompt_hidden' }) })
await t.host.tick([row()])
t.showing(() => ({ ok: true, text: TURN_OFF, hold: 'prompt_hidden' })); t.wait(15_000); await t.host.tick([row()])
expect(dismissed(t)).toEqual([['h1', ['0'], DRAFT], ['h1', ['Escape'], TURN_OFF]])
expect(t.core.superTabs!.input).not.toHaveBeenCalled()
expect(t.alerts()).toEqual([])
})
})
describe('progress for the machine report', () => {
const showing = (text: string) => (): SuperTabScreen => ({ ok: true, text, hold: null })
it('records when each running agent\'s screen last changed, from the reads the watch already makes', async () => {
const t = setup({ screen: showing('✻ Reading files…\n❯ ') })
await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })
t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })
t.showing(showing('✻ Editing host.ts…\n❯ ')); t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_030_000 })
expect(t.core.superTabs!.screen).toHaveBeenCalledTimes(3)
})
// Task #3397: a crew session whose whole screen, status line and timer too, never changes while its engine works is frozen
// (crew.ts). The watch's own reads tell it, so the crew keeper reads no screen of its own.
it('records when the whole screen last changed, its status line included, from the same reads', async () => {
const t = setup({ screen: showing('✻ Working… (3s · esc to interrupt)\n❯ ') })
await t.host.tick([row()])
expect(t.host.stillSince('h1')).toBe(1_000_000)
t.showing(showing('✻ Working… (18s · esc to interrupt)\n❯ ')); t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })
expect(t.host.stillSince('h1')).toBe(1_015_000)
t.wait(15_000); await t.host.tick([row()])
expect(t.host.stillSince('h1')).toBe(1_015_000)
expect(t.host.stillSince('h2')).toBeUndefined()
expect(t.core.superTabs!.screen).toHaveBeenCalledTimes(3)
})
it('names only running agents, and forgets one once it stops or leaves', async () => {
const t = setup({ live: ['h1', 'h2'] })
await t.host.tick([row(), row('a2', 'h2', { stopRequested: true }), row('a3', 'h3')])
expect(t.host.progressOf(['h1', 'h2', 'h3'])).toEqual({ h1: 1_000_000 })
t.wait(15_000); await t.host.tick([row('a2', 'h2')])
expect(t.host.progressOf(['h1', 'h2'])).toEqual({ h2: 1_015_000 })
await t.host.tick([])
expect(t.host.progressOf(['h1', 'h2'])).toEqual({})
})
it.each(['claude', 'codex'])('does not count %s redrawing only its spinner, elapsed time, token counter or tip, and counts new work', async engine => {
const t = setup({ screen: showing(fixture(`${engine}-working-a`)) })
await t.host.tick([row()])
t.showing(showing(fixture(`${engine}-working-b`))); t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })
t.showing(showing(fixture(`${engine}-working-b`).replace('\n\n', '\n\nEdited cli/src/superTabs/terminal.ts\n\n'))); t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_030_000 })
})
it('does not count a screen that only shows its model retrying, nor one that could not be read', async () => {
const t = setup({ screen: showing('✻ Waiting for API response · will retry in 2m 38s · check your network\n❯ ') })
await t.host.tick([row()])
t.showing(showing('✻ Waiting for API response · will retry in 2m 23s · check your network\n❯ ')); t.wait(15_000); await t.host.tick([row()])
t.showing(() => ({ ok: false, error: 'pane gone' })); t.wait(15_000); await t.host.tick([row()])
expect(t.host.progressOf(['h1'])).toEqual({ h1: 1_000_000 })
})
})
describe('reading a usage limit off a screen', () => {
const now = new Date(2026, 9, 23, 14, 10).getTime()
it.each([
['5-hour limit reached ∙ resets 3pm', new Date(2026, 9, 23, 15, 0)],
['Claude usage limit reached. Your limit will reset at 3pm (Asia/Saigon).', new Date(2026, 9, 23, 15, 0)],
['You\'ve hit your limit · resets 1:30pm (Asia/Saigon)', new Date(2026, 9, 24, 13, 30)],
['Weekly limit reached ∙ resets Oct 25, 9am', new Date(2026, 9, 25, 9, 0)],
['5-hour limit reached ∙ resets 15:00', new Date(2026, 9, 23, 15, 0)],
['5-hour limit reached ∙ resets 0:30', new Date(2026, 9, 24, 0, 30)],
['5-hour limit reached ∙ resets 12pm', new Date(2026, 9, 24, 12, 0)],
['5-hour limit reached ∙ resets 12am', new Date(2026, 9, 24, 0, 0)],
['■ You\'ve hit your usage limit. Try again at 4:05 PM.', new Date(2026, 9, 23, 16, 5)],
['■ You\'ve hit your usage limit. Upgrade to Pro, or try again in 2 days 3 hours 1 minute.', new Date(now + ((2 * 24 + 3) * 60 + 1) * 60_000)],
])('reads %s', (line, reset) => {
expect(limitOf(`some work\n${line}\n> `, now)).toEqual({ resetAt: reset.toISOString() })
})
// Whole screens as Claude Code 2.1.310 and Codex 0.154 draw them, their limit lines in the engines' own words
// (fixtures/screens): Claude Code names the limit hit, and Codex wraps its long line and dates a reset after today.
it.each([
['claude-session-limit', { resetAt: new Date(2026, 9, 23, 15, 0).toISOString() }],
['claude-weekly-limit', { resetAt: new Date(2026, 9, 30, 9, 0).toISOString() }],
['claude-opus-limit', { resetAt: new Date(2026, 9, 30, 9, 0).toISOString() }],
['claude-fable-limit', {}],
// Mid-turn, its notice is a row of its own after a tool's output (review of #2712, Important 1).
['claude-limit-after-tool', { resetAt: new Date(2026, 9, 23, 15, 0).toISOString() }],
['codex-usage-limit', { resetAt: new Date(2026, 9, 27, 15, 5).toISOString() }],
['codex-model-limit', { resetAt: new Date(2026, 9, 23, 16, 5).toISOString() }],
])('reads the %s screen', (name, limit) => {
expect(limitOf(fixture(name), now)).toEqual(limit)
})
// Task #2321 (Ken, 11-03): River was listed limited while it worked, as it had just printed another agent's screen,
// which showed Codex's limit line. Only the engine's own notice marks an agent limited, never text it prints.
it.each([
['claude-printed-codex-limit', 'a screen Claude Code printed, the limit line further down its tool output'],
['claude-printed-limit-first-line', 'the limit line first in its tool output, right above the prompt'],
])('reads no limit off %s: %s', name => {
expect(limitOf(fixture(name), now)).toBeNull()
})
it.each([
'⏺ harness - read_screen (MCP)(harnessId: "h1")',
'⏺ my.server-1 - read_screen.v2 (MCP)(harnessId: "h1")',
])('reads no limit off an MCP reply: %s', header => {
expect(limitOf(`${header}\n ⎿ ■ You've hit your usage limit. Try again at 4:08 PM.\n\n❯ `, now)).toBeNull()
})
it('still reads its own notice after MCP output or a reply with parentheses', () => {
for (const before of [
'⏺ harness - read_screen (MCP)(harnessId: "h1")\n ⎿ Screen read.\n',
'⏺ Checked the agent (it is working).',
]) {
expect(limitOf(`${before}\n ⎿ You've hit your session limit · resets 3pm\n\n❯ `, now))
.toEqual({ resetAt: new Date(2026, 9, 23, 15, 0).toISOString() })
}
})
it('reads no limit off a log a tool printed, quoted or indented, near the prompt', () => {
expect(limitOf('⏺ Read(logs/codex.log)\n ⎿ Read 3 lines\n 5-hour limit reached ∙ resets 3pm\n\n❯ ', now)).toBeNull()
expect(limitOf('• Ran cat codex.log\n └ ■ You\'ve hit your usage limit. Try again at 4:05 PM.\n\n› ', now)).toBeNull()
// A Claude Code screen printed in a tool's output, its header scrolled off: its "⎿" rows sit deeper than the engine's own.
expect(limitOf(' └ Test Files 1 passed (1)\n ⎿ You\'ve hit your session limit · resets 3pm\n\n❯ ', now)).toBeNull()
expect(limitOf('⏺ Update(notes.md)\n ⎿ Added 1 line\n 1 + You\'ve hit your session limit · resets 3pm\n\n❯ ', now)).toBeNull()
})
it('still reads Claude Code\'s limit dialog', () => {
expect(limitOf([
'╭──────────────────────────────────────────────────────────╮',
'│ You\'ve hit your limit · resets 3pm (Asia/Saigon) │',
'│ │',
'│ ❯ 1. Stop and wait for limit to reset │',
'│ 2. Upgrade your plan │',
'╰──────────────────────────────────────────────────────────╯',
].join('\n'), now)).toEqual({ resetAt: new Date(2026, 9, 23, 15, 0).toISOString() })
})
it('knows a limit without a reset time, and ignores the words in an agent\'s own prose or far above the prompt', () => {
expect(limitOf('⎿ API Error: Usage limit reached\n> ', now)).toEqual({})
expect(limitOf('I will add a check for when the usage limit reached message shows.\n> ', now)).toBeNull()
expect(limitOf(`5-hour limit reached ∙ resets 3pm\n${'line\n'.repeat(30)}> `, now)).toBeNull()
expect(limitOf('> ', now)).toBeNull()
// A full context is not a usage limit; a workspace out of credits is one.
expect(limitOf(' ⎿ Context limit reached · /compact or /clear to continue\n> ', now)).toBeNull()
// A notice under Claude Code's reply whose start has scrolled off the screen is still its own.
expect(limitOf(' ⎿ You\'ve hit your session limit · resets 3pm\n\n❯ ', now)).toEqual({ resetAt: new Date(2026, 9, 23, 15, 0).toISOString() })
expect(limitOf('■ You\'ve reached your workspace credit limit\n› ', now)).toEqual({})
})
})
describe('reading a model that keeps failing off a screen', () => {
it('knows the engines\' retry lines near the prompt, and nothing far up or in the agent\'s own words', () => {
for (const line of ['✻ Waiting for API response · will retry in 2m 38s · check your network', ' ⎿ API Error: 503 upstream unavailable',
'API Error: Request timed out.', 'API Error: Connection error.', '⚠ stream disconnected - retrying turn (3/5 in 1.2s)…', 'Reconnecting... 2/5']) {
expect(modelFailing(`work\n${line}\n> `)).toBe(true)
}
expect(modelFailing('I will handle the case where the API response is slow.\n> ')).toBe(false)
expect(modelFailing(`Waiting for API response\n${'line\n'.repeat(30)}> `)).toBe(false)
})
it('knows a connection that is gone: Claude Code\'s connection lines and Codex\'s reconnect', () => {
// Claude Code 2.1 names the connection's failure in place of "Connection error." (Pro-10's Team agent, 2026-11-03).
for (const line of ['⎿ API Error: Unable to connect to API (ECONNREFUSED)', ' ⎿ Unable to connect to API (ECONNREFUSED) · Retrying in 4s · attempt 3/10',
'⎿ API Error: No internet route — check your connection or VPN (ENETUNREACH)']) {
expect(modelFailing(`work\n${line}\n> `)).toBe(true)
}
// Pro-9's Team Codex agents, four hours after the update.
expect(modelFailing('• Reconnecting... waiting for network (4h 21m 27s • esc to interrupt)\n └ Connection failed: error sending request\n› Ask Codex to do anything')).toBe(true)
expect(modelFailing('work\n └ Connection failed: error sending request\n› ')).toBe(true)
expect(modelFailing(`I will make the client say "Unable to connect to API" when the relay is down.\n${'line\n'.repeat(30)}> `)).toBe(false)
})
})
// #3904: a resumed Swarm Codex already has an identity, so startup settlement never sees its folder prompt.
describe.each([
{ version: '0165', secondRow: 'Quit' },
{ version: '0166', secondRow: 'Back to Agent Command Center' },
])('opening a Swarm Codex folder restricted after start or resume ($version)', ({ version, secondRow }) => {
const restricted = fixture(`codex-${version}-open-restricted`)
it.each(['start', 'resume'])('continues a fake Codex %s without granting trust', async (mode) => {
const home = mkdtempSync(join(tmpdir(), 'codex-restricted-'))
const config = join(home, 'config.toml')
const savedConfig = '[projects."/worktree"]\ntrust_level = "untrusted"\n'
writeFileSync(config, savedConfig)
// A separate fake engine waits on input on both startup paths, reading only its disposable home.
const child = spawn(process.execPath, ['--input-type=module', '-e', `
import { readFileSync } from 'node:fs';
import { createInterface } from 'node:readline';
const [mode, config, prompt] = process.argv.slice(1);
if (!['start', 'resume'].includes(mode) || !readFileSync(config, 'utf8').includes('"untrusted"')) process.exit(1);
console.log(JSON.stringify(prompt));
createInterface({ input: process.stdin }).on('line', key => {
if (key === 'Enter') console.log(JSON.stringify('› Ask Codex to do anything'));
});
`, mode, config, restricted], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
const lines = createInterface({ input: child.stdout })[Symbol.asyncIterator]()
const nextScreen = async () => {
let timer: ReturnType<typeof setTimeout> | undefined
try {
const line = await Promise.race([lines.next(), new Promise<never>((_, reject) => {
timer = setTimeout(() => reject(new Error('Fake Codex did not draw its next screen')), 2_000)
})])
if (line.done) throw new Error('Fake Codex exited before drawing its screen')
return JSON.parse(line.value) as string
} finally { clearTimeout(timer) }
}
try {
let capture = await nextScreen()
const t = setup({ engine: 'codex' })
const terminal = createSuperTabTerminal({
resolve: id => id === 'h1' ? { agentId: id, engine: 'codex' } as RegisteredSession : undefined,
capture: async () => ({ state: 'succeeded', value: capture }),
read: async (_session, text) => codexScreen.inspect(text ?? ''),
type: async () => false,
key: async (_id, key) => { child.stdin.write(`${key}\n`); capture = await nextScreen(); return true },
locked: async (_id, write) => write(),
})
Object.assign(t.core.superTabs!, terminal)
await t.host.tick([row()])
expect(capture).toBe('› Ask Codex to do anything')
expect(readFileSync(config, 'utf8')).toBe(savedConfig)
t.wait(180_000); await t.host.tick([row()])
expect(t.alerts()).toEqual([])
} finally {
child.kill()
rmSync(home, { recursive: true, force: true })
}
})
it.each([
['trust grant', CODEX_TRUST_PROMPT, 'codex', [row()]],
['another engine', restricted, 'claude', [row()]],
['personal session outside the roster', restricted, 'codex', []],
['the second row highlighted', restricted.replace('› 1. Open restricted', ' 1. Open restricted').replace(` 2. ${secondRow}`, `› 2. ${secondRow}`), 'codex', [row()]],
])('never types on %s', async (_name, text, engine, rows) => {
const t = setup({ engine, screen: () => ({ ok: true, text, hold: 'trust_open' }) })
await t.host.tick(rows)
expect(t.core.superTabs!.inputIfScreen).not.toHaveBeenCalled()
})
it('bounds failed conditional inputs and alerts when the prompt persists', async () => {
const t = setup({ engine: 'codex', screen: () => ({ ok: true, text: restricted, hold: 'trust_open' }) })
vi.mocked(t.core.superTabs!.inputIfScreen).mockResolvedValue({ ok: false, error: 'Screen changed.' })
for (let i = 0; i < 5; i++) { await t.host.tick([row()]); t.wait(15_000) }
expect(t.core.superTabs!.inputIfScreen).toHaveBeenCalledTimes(3)
expect(t.core.superTabs!.inputIfScreen).toHaveBeenCalledWith('h1', ['Enter'], restricted)
t.wait(180_000); await t.host.tick([row()])
expect(t.alerts()).toContainEqual(expect.objectContaining({ alert: 'prompt', active: true }))
})
})