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 { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { sanitizeCheckForTest as sanitize, sanitizeLimitsForTest as sanitizeLimits } from './check'
import { fakePlatform } from './platform-fake'
// The server states the open-project limit by the PRESENCE of `limits` in a successful reply. The
// latch that consumes this reads `off` as "clear", so only a missing key in a CHECK-SHAPED reply
// (`messages` array + `update` object — every 2xx the route sends) is an off. Anything else — a
// malformed `limits`, or JSON that is not a check reply at all — is `unknown`, which changes nothing.
describe('/v1/check sanitize — limits', () => {
const reply = (extra: Record<string, unknown> = {}) => ({
messages: [],
update: { minSupported: null, mandatory: false },
...extra
})
it('reads a check reply without limits as off', () => {
expect(sanitizeLimits(reply())).toEqual({ kind: 'off' })
expect(sanitizeLimits({ messages: [{ id: 'a', title: 'A' }], update: {} })).toEqual({ kind: 'off' })
})
it('reads a well-formed project limit as on, and nothing else from it', () => {
expect(sanitizeLimits(reply({ limits: { projects: { free: 5, epoch: 1 } } }))).toEqual({
kind: 'on',
free: 5,
epoch: 1
})
expect(sanitizeLimits(reply({ limits: { projects: { free: 1, epoch: 7, extra: 'x' }, other: 1 } }))).toEqual({
kind: 'on',
free: 1,
epoch: 7
})
expect(sanitizeLimits(reply({ limits: { projects: { free: 1000, epoch: 2 } } }))).toEqual({
kind: 'on',
free: 1000,
epoch: 2
})
})
it('reads a present but malformed limits value as unknown', () => {
const malformed: unknown[] = [
null,
true,
'on',
5,
[],
{},
{ projects: null },
{ projects: [] },
{ projects: 'on' },
{ projects: { epoch: 1 } },
{ projects: { free: 5 } },
{ projects: { free: 0, epoch: 1 } },
{ projects: { free: 1001, epoch: 1 } },
{ projects: { free: 2.5, epoch: 1 } },
{ projects: { free: '5', epoch: 1 } },
{ projects: { free: 5, epoch: 0 } },
{ projects: { free: 5, epoch: -1 } },
{ projects: { free: 5, epoch: 1.5 } },
{ projects: { free: 5, epoch: '1' } },
{ projects: { free: 5, epoch: 2 ** 53 } }
]
for (const limits of malformed) {
expect(sanitizeLimits(reply({ limits })), JSON.stringify(limits)).toEqual({ kind: 'unknown' })
}
})
// A 200 with `{"status":"ok"}`, an error object, or a proxy's JSON page behind a followed redirect
// carries no `limits` either — read past its shape, each would be a misfired off.
it('reads a body that is not a check reply as unknown, never off', () => {
const notAReply: unknown[] = [
null,
undefined,
'ok',
3,
true,
[],
[{ limits: null }],
{},
{ status: 'ok' },
{ error: 'internal' },
{ messages: [] },
{ update: {} },
{ messages: {}, update: {} },
{ messages: [], update: null },
{ messages: [], update: [] },
{ limits: { projects: { free: 5, epoch: 1 } } }
]
for (const body of notAReply) {
expect(sanitizeLimits(body), JSON.stringify(body)).toEqual({ kind: 'unknown' })
}
})
})
describe('/v1/check sanitize — update notes', () => {
it('carries notes only together with the version they describe', () => {
expect(sanitize({ update: { mandatory: false, notes: '- a', latestVersion: '1.2.0' } }).update).toEqual({
minSupported: null,
mandatory: false,
notes: '- a',
latestVersion: '1.2.0'
})
expect(sanitize({ update: { notes: '- a' } }).update).toEqual({ minSupported: null, mandatory: false })
expect(sanitize({ update: { notes: 3, latestVersion: '1.2.0' } }).update).toEqual({
minSupported: null,
mandatory: false
})
})
it('keeps the policy shape when the feed sends nothing', () => {
expect(sanitize(null).update).toEqual({ minSupported: null, mandatory: false })
expect(sanitize({ update: { minSupported: '0.5.0', mandatory: true } }).update).toEqual({
minSupported: '0.5.0',
mandatory: true
})
})
it('caps the notes', () => {
expect(sanitize({ update: { notes: 'x'.repeat(50_000), latestVersion: '1' } }).update.notes!.length).toBe(16 * 1024)
})
})
// Popups ride their own key, so a build that reads only `messages` never gets one as a banner. The
// sanitizer is their whole contract: a closed action set, a clamped label, the banner's url rule.
describe('/v1/check sanitize — popups', () => {
it('reads popups apart from the banners, with their button', () => {
const r = sanitize({
messages: [{ id: 'b', title: 'Banner' }],
popups: [
{ id: 'p', title: 'Popup', body: 'a\nb', url: 'https://nodeterm.dev/pro', level: 'success', ctaLabel: ' See Pro ', action: 'upgrade' }
],
update: {}
})
expect(r.messages.map((m) => m.id)).toEqual(['b'])
expect(r.popups).toEqual([
{ id: 'p', title: 'Popup', body: 'a\nb', url: 'https://nodeterm.dev/pro', level: 'success', ctaLabel: 'See Pro', action: 'upgrade' }
])
})
it('keeps a picture only as a hash: the feed names no URL', () => {
const hash = 'a'.repeat(64)
const r = sanitize({
popups: [
{ id: 'ok', title: 'A', image: hash },
{ id: 'url', title: 'B', image: `https://evil.test/${hash}` },
{ id: 'path', title: 'C', image: `../${hash}` },
{ id: 'num', title: 'D', image: 7 }
],
update: {}
})
expect(r.popups.map((p) => p.image)).toEqual([hash, undefined, undefined, undefined])
expect(r.popups.slice(1).every((p) => !('image' in p))).toBe(true)
})
it('drops what it cannot show and never guesses an action', () => {
const r = sanitize({
popups: [
null,
'x',
{ title: 'no id' },
{ id: 'p1', title: 'P1', action: 'checkout', url: 'javascript:alert(1)', ctaLabel: ' ' },
{ id: 'p2', title: 'P2', ctaLabel: 'L'.repeat(200), level: 'danger' }
]
})
expect(r.popups.map((p) => p.id)).toEqual(['p1', 'p2'])
expect(r.popups[0]).toEqual({ id: 'p1', title: 'P1', body: undefined, url: undefined, level: 'info' })
expect(r.popups[1].ctaLabel).toHaveLength(40)
expect(r.popups[1].level).toBe('info')
})
it('is an empty list when the feed sends none (every server before popups)', () => {
expect(sanitize({ messages: [], update: {} }).popups).toEqual([])
expect(sanitize({ popups: {} }).popups).toEqual([])
expect(sanitize(null).popups).toEqual([])
})
})
// The feed is anonymous, so the backend can aim a message at paid or free users only by the plan
// the client states. Read per request and part of the cache key: an "upgrade to Pro" message
// cached as a free user must not be served for five more minutes to the same user once they pay.
describe('fetchCheck — reports the plan', () => {
const premium = { value: false }
let fetchMock: ReturnType<typeof vi.fn>
const feed = (title: string, minSupported: string | null = null) =>
new Response(JSON.stringify({ messages: [{ id: title, title }], update: { minSupported, mandatory: false } }), {
status: 200,
headers: { 'content-type': 'application/json' }
})
const paramsOf = (call: number) => new URL(String(fetchMock.mock.calls[call][0])).searchParams
const param = (call: number, key: string) => paramsOf(call).get(key)
const planOf = (call: number) => param(call, 'plan')
// A fresh module graph per load (the cache is module state), so the platform must be set on the
// SAME instance check.ts will import.
const loadCheck = async () => {
vi.resetModules()
;(await import('./platform')).initPlatform(fakePlatform())
return import('./check')
}
beforeEach(() => {
vi.doMock('./license', () => ({ isPremium: () => premium.value }))
vi.doMock('./device-id', () => ({ getDeviceId: () => '33333333-3333-3333-3333-333333333333' }))
vi.stubEnv('NODETERM_API_BASE', 'http://api.test')
vi.stubEnv('DO_NOT_TRACK', '')
vi.stubEnv('NODETERM_TELEMETRY_DISABLED', '')
premium.value = false
fetchMock = vi.fn()
vi.stubGlobal('fetch', fetchMock)
})
afterEach(() => {
vi.unstubAllGlobals()
vi.unstubAllEnvs()
vi.doUnmock('./license')
vi.doUnmock('./device-id')
})
it('sends plan=pro for a Pro install and plan=free otherwise', async () => {
fetchMock.mockResolvedValue(feed('x'))
premium.value = true
await (await loadCheck()).fetchCheck()
expect(planOf(0)).toBe('pro')
premium.value = false
await (await loadCheck()).fetchCheck()
expect(planOf(1)).toBe('free')
})
it('does not answer a plan change from the other plan’s cache', async () => {
const { fetchCheck } = await loadCheck()
fetchMock.mockResolvedValueOnce(feed('Try Pro')).mockResolvedValueOnce(feed('Thanks'))
expect((await fetchCheck()).messages.map((m) => m.title)).toEqual(['Try Pro'])
expect((await fetchCheck()).messages.map((m) => m.title)).toEqual(['Try Pro'])
expect(fetchMock).toHaveBeenCalledTimes(1)
premium.value = true
expect((await fetchCheck()).messages.map((m) => m.title)).toEqual(['Thanks'])
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(planOf(1)).toBe('pro')
})
it('a failed read after a plan change keeps the update policy but not the old plan’s messages', async () => {
const { fetchCheck } = await loadCheck()
fetchMock.mockResolvedValueOnce(feed('Try Pro', '0.5.0')).mockRejectedValueOnce(new Error('offline'))
await fetchCheck()
premium.value = true
expect(await fetchCheck()).toEqual({ messages: [], popups: [], update: { minSupported: '0.5.0', mandatory: false } })
})
it('a failed read after a plan change drops the old plan’s popups too', async () => {
const { fetchCheck } = await loadCheck()
const body = { messages: [], popups: [{ id: 'p', title: 'Try Pro' }], update: { minSupported: null, mandatory: false } }
fetchMock
.mockResolvedValueOnce(new Response(JSON.stringify(body), { status: 200, headers: { 'content-type': 'application/json' } }))
.mockRejectedValueOnce(new Error('offline'))
expect((await fetchCheck()).popups.map((p) => p.id)).toEqual(['p'])
premium.value = true
expect((await fetchCheck()).popups).toEqual([])
})
// The open-project count rides the same call, but — unlike the install count above — only while
// the Settings → Privacy telemetry toggle is on, and only as a bare number. Its server side keeps
// the per-install maximum (the data the project-limit allowance is computed from).
describe('openProjects', () => {
beforeEach(() => fetchMock.mockResolvedValue(feed('x')))
it('sends openProjects when telemetry is on and the count is known', async () => {
const m = await loadCheck()
m.configureCheck({ openProjects: () => 7, telemetryEnabled: () => true })
await m.fetchCheck()
expect(param(0, 'openProjects')).toBe('7')
})
it('omits it when telemetry is off', async () => {
const m = await loadCheck()
m.configureCheck({ openProjects: () => 7, telemetryEnabled: () => false })
await m.fetchCheck()
expect(param(0, 'openProjects')).toBeNull()
})
it('omits it before the index is loaded', async () => {
const m = await loadCheck()
m.configureCheck({ openProjects: () => undefined, telemetryEnabled: () => true })
await m.fetchCheck()
expect(param(0, 'openProjects')).toBeNull()
})
it('omits it when never configured', async () => {
const m = await loadCheck()
await m.fetchCheck()
expect(param(0, 'openProjects')).toBeNull()
})
it('omits a count that is not a non-negative integer', async () => {
for (const n of [-1, 2.5, Number.NaN, Number.POSITIVE_INFINITY]) {
fetchMock.mockClear()
const m = await loadCheck()
m.configureCheck({ openProjects: () => n, telemetryEnabled: () => true })
await m.fetchCheck()
expect(param(0, 'openProjects')).toBeNull()
}
})
it('sends a count of zero', async () => {
const m = await loadCheck()
m.configureCheck({ openProjects: () => 0, telemetryEnabled: () => true })
await m.fetchCheck()
expect(param(0, 'openProjects')).toBe('0')
})
it('sends nothing else new', async () => {
const m = await loadCheck()
m.configureCheck({ openProjects: () => 7, telemetryEnabled: () => true })
await m.fetchCheck()
expect([...paramsOf(0).keys()].sort()).toEqual([
'arch',
'channel',
'deviceId',
'openProjects',
'os',
'plan',
'version'
])
})
// At boot the first reads can run before the workspace index has loaded, so they go out with
// no count. Served from the cache, that reply would keep the count off the wire for 5 minutes
// and — the next read being the 6 h tick — for the whole of a short session.
describe('a reply fetched while the count was still unknown', () => {
const titles = async (m: Awaited<ReturnType<typeof loadCheck>>) =>
(await m.fetchCheck()).messages.map((x) => x.title)
beforeEach(() => {
let n = 0
fetchMock.mockImplementation(async () => feed(`read ${++n}`))
})
it('does not stand in for a read that can carry it: that read refetches and replaces the cache', async () => {
const m = await loadCheck()
let count: number | undefined
m.configureCheck({ openProjects: () => count, telemetryEnabled: () => true })
expect(await titles(m)).toEqual(['read 1'])
expect(param(0, 'openProjects')).toBeNull()
count = 4
expect(await titles(m)).toEqual(['read 2'])
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(param(1, 'openProjects')).toBe('4')
// The reply that carried the count is an ordinary cache entry again.
count = 5
expect(await titles(m)).toEqual(['read 2'])
expect(fetchMock).toHaveBeenCalledTimes(2)
})
it('is reused while the count is still unknown, or no longer wanted', async () => {
const m = await loadCheck()
let count: number | undefined
let telemetry = true
m.configureCheck({ openProjects: () => count, telemetryEnabled: () => telemetry })
await m.fetchCheck()
expect(await titles(m)).toEqual(['read 1'])
telemetry = false
count = 4
expect(await titles(m)).toEqual(['read 1'])
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it('a failed refetch falls back to it and the next read tries again', async () => {
const m = await loadCheck()
let count: number | undefined
m.configureCheck({ openProjects: () => count, telemetryEnabled: () => true })
await m.fetchCheck()
count = 4
fetchMock.mockRejectedValueOnce(new Error('offline'))
expect(await titles(m)).toEqual(['read 1'])
expect(await titles(m)).toEqual(['read 2'])
expect(param(2, 'openProjects')).toBe('4')
})
})
it('a reply fetched with the count is reused within 5 minutes, whatever the count becomes', async () => {
let n = 0
fetchMock.mockImplementation(async () => feed(`read ${++n}`))
const m = await loadCheck()
let count = 4
m.configureCheck({ openProjects: () => count, telemetryEnabled: () => true })
await m.fetchCheck()
count = 9
expect((await m.fetchCheck()).messages.map((x) => x.title)).toEqual(['read 1'])
expect(fetchMock).toHaveBeenCalledTimes(1)
})
it('a reply fetched with telemetry off is reused within 5 minutes, even once the count is wanted and known', async () => {
let n = 0
fetchMock.mockImplementation(async () => feed(`read ${++n}`))
const m = await loadCheck()
let count: number | undefined
let telemetry = false
m.configureCheck({ openProjects: () => count, telemetryEnabled: () => telemetry })
await m.fetchCheck()
telemetry = true
count = 4
expect((await m.fetchCheck()).messages.map((x) => x.title)).toEqual(['read 1'])
expect(fetchMock).toHaveBeenCalledTimes(1)
})
})
// The project-limit latch (core/project-limit.ts) clears on `off`, so an answer may come only from
// a read the server actually made: a blocked network, a rate limit or a captive portal must never
// be able to say "off". The failure bodies below are JSON WITHOUT `limits` on purpose — read past
// their status, each would be exactly that misfired off.
describe('onCheckAnswer', () => {
const json = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } })
const limitsFeed = (free: number, epoch: number) =>
json({ messages: [], update: { minSupported: null, mandatory: false }, limits: { projects: { free, epoch } } })
const T0 = Date.UTC(2026, 9, 30, 12)
beforeEach(() => {
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(T0)
})
afterEach(() => vi.useRealTimers())
it('answers only on a 2xx JSON read', async () => {
// [label, response, the calls the listener may see]. A 2xx JSON object that is not a check
// reply is still a read, but its answer is `unknown` — the one thing it must never say is off.
const cases: Array<[string, () => Promise<Response>, unknown[][]]> = [
['500', async () => json({ error: 'internal' }, 500), []],
['429', async () => json({ error: 'rate_limited' }, 429), []],
['200 json, not a check reply', async () => json({ status: 'ok' }), [[{ kind: 'unknown' }]]],
['thrown fetch', async () => Promise.reject(new TypeError('fetch failed')), []],
[
'200 text/html',
async () =>
new Response('<html><body>Sign in to the network</body></html>', {
status: 200,
headers: { 'content-type': 'text/html' }
}),
[]
]
]
for (const [label, respond, calls] of cases) {
fetchMock.mockReset().mockImplementation(respond)
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
expect(await m.fetchCheck(), label).toEqual({
messages: [],
popups: [],
update: { minSupported: null, mandatory: false }
})
expect(fetchMock, label).toHaveBeenCalledTimes(1)
expect(listener.mock.calls, label).toEqual(calls)
}
})
it('does not answer from the failure fallback of an earlier good read', async () => {
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
fetchMock.mockResolvedValueOnce(limitsFeed(5, 1)).mockResolvedValueOnce(json({ error: 'internal' }, 500))
await m.fetchCheck()
expect(listener).toHaveBeenCalledTimes(1)
vi.setSystemTime(T0 + 6 * 60 * 1000)
await m.fetchCheck()
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(listener).toHaveBeenCalledTimes(1)
})
it('a 2xx without limits answers off once', async () => {
// `feed` is a real check reply (`messages` array + `update` object): only that shape can say off.
fetchMock.mockResolvedValue(feed('x'))
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
await m.fetchCheck()
expect(listener.mock.calls).toEqual([[{ kind: 'off' }]])
})
it('a 2xx with limits answers on, and the limits never reach fetchCheck’s result', async () => {
fetchMock.mockResolvedValue(limitsFeed(5, 3))
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
expect(await m.fetchCheck()).toEqual({ messages: [], popups: [], update: { minSupported: null, mandatory: false } })
expect(listener.mock.calls).toEqual([[{ kind: 'on', free: 5, epoch: 3 }]])
})
it('a 2xx with a malformed limits value answers unknown', async () => {
fetchMock.mockResolvedValue(json({ messages: [], update: {}, limits: { projects: { free: 0, epoch: 1 } } }))
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
await m.fetchCheck()
expect(listener.mock.calls).toEqual([[{ kind: 'unknown' }]])
})
it('a cache hit within 5 min does not answer again; the next network read does', async () => {
fetchMock.mockImplementation(async () => limitsFeed(5, 1))
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
await m.fetchCheck()
vi.setSystemTime(T0 + 4 * 60 * 1000)
await m.fetchCheck()
expect(fetchMock).toHaveBeenCalledTimes(1)
expect(listener).toHaveBeenCalledTimes(1)
vi.setSystemTime(T0 + 6 * 60 * 1000)
await m.fetchCheck()
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(listener).toHaveBeenCalledTimes(2)
})
it('does not answer when the feed is not allowed to run', async () => {
vi.stubEnv('DO_NOT_TRACK', '1')
const m = await loadCheck()
const listener = vi.fn()
m.onCheckAnswer(listener)
await m.fetchCheck()
expect(fetchMock).not.toHaveBeenCalled()
expect(listener).not.toHaveBeenCalled()
})
it('a listener that throws does not break fetchCheck or the other listeners', async () => {
fetchMock.mockResolvedValue(feed('x'))
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
try {
const m = await loadCheck()
const after = vi.fn()
m.onCheckAnswer(() => {
throw new Error('listener bug')
})
m.onCheckAnswer(after)
expect((await m.fetchCheck()).messages.map((x) => x.title)).toEqual(['x'])
expect(after.mock.calls).toEqual([[{ kind: 'off' }]])
expect(warn).toHaveBeenCalledWith('[check] answer listener failed', expect.any(Error))
// The read was good: it is cached like any other, not retried as a failure.
await m.fetchCheck()
expect(fetchMock).toHaveBeenCalledTimes(1)
} finally {
warn.mockRestore()
}
})
it('stops answering a listener once unsubscribed', async () => {
fetchMock.mockImplementation(async () => feed('x'))
const m = await loadCheck()
const listener = vi.fn()
const off = m.onCheckAnswer(listener)
await m.fetchCheck()
off()
vi.setSystemTime(T0 + 6 * 60 * 1000)
await m.fetchCheck()
expect(fetchMock).toHaveBeenCalledTimes(2)
expect(listener).toHaveBeenCalledTimes(1)
})
})
})