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
/**
* The free-tier open-project limit, desktop core (docs/project-limit.md). It decides whether the
* limit is on for this install and what its allowance is, and it makes the claim. The renderer's gate asks for that state (`decideOpen` in shared/project-limit.ts)
* and claims only when it has to. Desktop only: the Server Edition never calls `initProjectLimit`
* (its bridge answers `INACTIVE_PROJECT_LIMIT`).
*
* ON OR OFF. `active` = a packaged build AND an allowance key AND (the latch OR the embedded deadline
* has passed by the clock anchor, with no server "off" in the last `OFF_TRUST_MS`). Dev builds are
* never active; nor is a build without the key (before O1): it could verify no allowance, holding
* every install at FREE, so it stays unlimited like a build from before the limit.
* - The latch is the server's word. A check answer with `limits` sets it, and so does a successful
* claim (a 200 whose token verifies — the token is stored with it); a successful check without
* `limits`, or a claim answering `not_active`, clears it. Nothing else does: a failed check gives
* no answer at all (check.ts `onCheckAnswer`), so being unreachable never turns it off. A
* DO_NOT_TRACK install hears no check at all, which is why the renderer's gate claims once more at
* its known allowance (lib/projectLimitGate.ts `reclaimsAtBlock`): that claim is how an undo
* reaches a latched one.
* - The deadline is compared against `clockAnchorMs()` (license.ts: the later of the wall clock and
* the largest instant this install has observed), so rolling the clock back cannot move an install
* from past the deadline to before it.
* - An "off" (`offAt`) suppresses the deadline for 24 h. A check that keeps saying off refreshes it.
*
* THE ALLOWANCE comes from a server-signed token, verified offline on every `state()`: signature
* (the separate allowance key), `typ`, deviceId, epoch, and the MACHINE hash. The machine is judged
* only against a hash that came from a SUCCESSFUL OS read (machine-id.ts `fromOs`), which `state()`
* cannot wait for. So when a token is stored (only after the limit was on; an undo via the check
* feed keeps it) init starts that read in the background; until it lands, or if the OS read fails
* and only the hostname fallback is known, the token is trusted provisionally on everything but the
* machine. A slow or failed boot-time read must never drop a legacy user to FREE and push them into
* a claim (which could rebind their allowance to the wrong hash). Once an OS hash is known the
* machine check applies. A successful claim also caches the hash it sent, if it came from the OS.
*
* CLAIMS are lazy and never reject: one request shared by concurrent callers, an 8 s timeout over
* the whole request including the body (the machine read before it is bounded by machine-id.ts's
* own per-attempt timeout), and every failure folded into a `ClaimError`. While the limit is off a
* claim asks nobody (no request, no machine read), whoever calls it.
*
* `projectLimit:changed` goes to THIS machine's windows only, through the shell's `notify`. Never
* `platform().broadcast`: on the desktop that fans out to every relay peer, and this state carries
* the host's Pro and DO_NOT_TRACK facts (see HOST_ONLY_CHANNEL_PREFIXES for the inbound half).
* It is pushed whenever the state differs from the last one sent: after a server word, and on the
* 6 h tick for what time alone changes (the deadline passing, an "off" going stale, Pro's grace
* lapsing) — otherwise a long-running app would stay dormant past the deadline until a restart.
*
* PERSISTENCE: `<userData>/project-limit.json`, written through `writeFileAtomic`, only when
* something changed. A missing, unparsable or hand-edited file never throws: each wrong-typed
* field is dropped on its own.
*/
import { readFileSync } from 'fs'
import path from 'path'
import { platform } from './platform'
import { IPC } from '../shared/ipc'
import {
PROJECT_LIMIT_DEADLINE_MS,
PROJECT_LIMIT_DEFAULT_FREE,
type ClaimError,
type ClaimResult,
type ProjectLimitState
} from '../shared/project-limit'
import { clockAnchorMs, isDntEnv, licenseNetworkGate, proForProjectLimit } from './license'
import { getDeviceId } from './device-id'
import { fetchCheck, onCheckAnswer, type LimitsAnswer } from './check'
import { verifyAllowanceToken } from './project-allowance-token'
import { PROJECT_ALLOWANCE_PUBLIC_KEY } from './project-allowance-key'
import { writeFileAtomic } from './fs-atomic'
import type { MachineHashResult } from './machine-id'
// The same base license.ts and check.ts use (a local server via NODETERM_API_BASE in development).
const API_BASE = process.env.NODETERM_API_BASE || 'https://api.nodeterm.dev'
/** How long a server "off" keeps the embedded deadline from switching the limit on. */
export const OFF_TRUST_MS = 24 * 60 * 60 * 1000
/** The whole claim request, body included (see license.ts REQUEST_TIMEOUT_MS for why the body). */
const CLAIM_TIMEOUT_MS = 8000
/** The check feed is re-read on this cadence, through check.ts's 5-minute cache. */
const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000
/** The server's own bounds: FREE in 1..1000 (check.ts), a first-launch count in 0..10000 (claim
* route — anything larger is a 400, which would fail every claim). */
const FREE_MAX = 1000
const COUNT_MAX = 10_000
/** `<userData>/project-limit.json`. Every field is optional; see `load` for how each is read. */
interface Stored {
latched?: boolean
offAt?: number
free?: number
epoch?: number
token?: string
firstLaunchOpenCount?: number
}
export interface ProjectLimitDeps {
/** `WorkspaceStore.openProjectCount` — undefined = unknown, never recorded or sent as 0. */
openProjects: () => number | undefined
/** `readMachineHashResult` (machine-id.ts). Read lazily: only by a claim, or at init when a
* token is already stored. */
machineHash: () => Promise<MachineHashResult>
/** The allowance public key; defaults to the shipped one ('' = none: never active). */
publicKeyPem?: string
/** Deliver the new state to this machine's own windows — never to relay peers. */
notify: (s: ProjectLimitState) => void
/** Settles once `openProjects` can answer (main: the boot workspace load). The init check read
* waits for it, settled either way: read before it, the count is still unknown and that read
* goes out without it. Absent = read at once. */
ready?: Promise<unknown>
}
export interface ProjectLimitHandle {
/** The current state. Synchronous and offline. */
state(): ProjectLimitState
/** Ask the server for this device's allowance. Never rejects. */
claim(): Promise<ClaimResult>
/** Re-send the state, unconditionally. */
refresh(): void
/** Send the state only if it differs from the last one sent — what a license or settings change
* calls (either can alter it with nothing here noticing, and settings change on every save). */
pushIfChanged(): void
}
const isInt = (v: unknown): v is number => Number.isSafeInteger(v)
const isCount = (v: unknown): v is number => isInt(v) && v >= 0
const isFree = (v: unknown): v is number => isInt(v) && v >= 1 && v <= FREE_MAX
const isEpoch = (v: unknown): v is number => isInt(v) && v >= 1
const isRecord = (v: unknown): v is Record<string, unknown> =>
typeof v === 'object' && v !== null && !Array.isArray(v)
let deps: ProjectLimitDeps
let stored: Stored = {}
/** The machine hash from a successful OS read; null = none yet (provisional trust, see header). */
let osMachine: string | null = null
let claimInFlight: Promise<ClaimResult> | null = null
/** The JSON of the last state sent to the windows (seeded at init: the renderer reads it then). */
let lastSent: string | null = null
let writes: Promise<void> = Promise.resolve()
/** Background reads and writes, so tests can wait for them (`__projectLimitIdleForTests`). */
const pending = new Set<Promise<unknown>>()
function track<T>(p: Promise<T>): Promise<T> {
pending.add(p)
const done = (): void => {
pending.delete(p)
}
p.then(done, done)
return p
}
function file(): string {
return path.join(platform().userDataDir, 'project-limit.json')
}
function load(): Stored {
let raw: unknown
try {
raw = JSON.parse(readFileSync(file(), 'utf-8'))
} catch {
return {}
}
if (!isRecord(raw)) return {}
const s: Stored = {}
if (typeof raw.latched === 'boolean') s.latched = raw.latched
if (isCount(raw.offAt)) s.offAt = raw.offAt
if (isFree(raw.free)) s.free = raw.free
if (isEpoch(raw.epoch)) s.epoch = raw.epoch
if (typeof raw.token === 'string' && raw.token) s.token = raw.token
if (isCount(raw.firstLaunchOpenCount)) s.firstLaunchOpenCount = raw.firstLaunchOpenCount
return s
}
/** Queue a write of the CURRENT record: the writes run in order and each serializes `stored` when
* it runs, so the last one to land always carries the newest state. A failed write is logged and
* the in-memory state stands. */
function persist(): Promise<void> {
writes = writes
.then(() => writeFileAtomic(file(), JSON.stringify(stored)))
.catch((err) => console.warn('[project-limit] save failed', err instanceof Error ? err.message : String(err)))
return track(writes)
}
/** The key allowance tokens are verified with; '' = none (before O1) = never active. */
const allowanceKey = (): string => deps.publicKeyPem ?? PROJECT_ALLOWANCE_PUBLIC_KEY
function isActive(): boolean {
if (!platform().isPackaged || !allowanceKey()) return false
if (stored.latched) return true
const anchor = clockAnchorMs()
return anchor >= PROJECT_LIMIT_DEADLINE_MS && !(stored.offAt !== undefined && anchor - stored.offAt < OFF_TRUST_MS)
}
function allowance(): number | null {
if (!stored.token) return null
const v = verifyAllowanceToken(
stored.token,
{ deviceId: getDeviceId(), machine: osMachine, epoch: stored.epoch },
allowanceKey()
)
return v ? v.allowance : null
}
function compute(): ProjectLimitState {
return {
active: isActive(),
pro: proForProjectLimit(),
free: stored.free ?? PROJECT_LIMIT_DEFAULT_FREE,
allowance: allowance(),
dnt: isDntEnv()
}
}
/** The count at the first launch of a limit-capable build (the late-updater basis,
* docs/project-limit.md): the first number `openProjects()` gives, kept for good. */
function recordFirstLaunchOpenCount(): void {
if (stored.firstLaunchOpenCount !== undefined) return
let n: number | undefined
try {
n = deps.openProjects()
} catch {
return
}
if (!isCount(n)) return
stored = { ...stored, firstLaunchOpenCount: n }
void persist()
}
function state(): ProjectLimitState {
recordFirstLaunchOpenCount()
return compute()
}
/** Send the state to this machine's windows, unconditionally (`refresh()`; also the boot-time
* machine read landing, which can change what the windows were told at init). */
function notify(): void {
const s = state()
lastSent = JSON.stringify(s)
deps.notify(s)
}
/** Send the state only if it differs from the last one sent. Compared against what was SENT, not
* against the state a moment ago, so a change that came with time alone — the anchor crossing the
* deadline, an `offAt` going stale, Pro's grace lapsing — is pushed by the next call too. */
function pushIfChanged(): void {
const s = state()
const json = JSON.stringify(s)
if (json === lastSent) return
lastSent = json
deps.notify(s)
}
/** Install `next`, save it when `save`, and tell this machine's windows if what they see changed. */
function commit(next: Stored, save: boolean): Promise<void> {
stored = next
const saved = save ? persist() : Promise.resolve()
pushIfChanged()
return saved
}
/** The epoch a token says it was issued under, read WITHOUT verifying it. Used only to decide that
* a newer epoch retires it — deleting is the safe direction: the next open past FREE re-claims. */
function tokenEpoch(token: string): number | null {
const dot = token.indexOf('.')
if (dot < 1) return null
try {
const payload: unknown = JSON.parse(Buffer.from(token.slice(0, dot), 'base64url').toString('utf-8'))
return isRecord(payload) && isInt(payload.epoch) ? payload.epoch : null
} catch {
return null
}
}
/** One check answer. Idempotent: the same answer twice changes nothing the second time. */
function onAnswer(a: LimitsAnswer): void {
if (a.kind === 'on') {
const next: Stored = { ...stored, latched: true, free: a.free, epoch: a.epoch }
if (next.token !== undefined && tokenEpoch(next.token) !== a.epoch) delete next.token
const changed =
stored.latched !== true || stored.free !== a.free || stored.epoch !== a.epoch || stored.token !== next.token
void commit(next, changed)
} else if (a.kind === 'off') {
const offAt = clockAnchorMs()
// offAt only matters while `anchor - offAt < OFF_TRUST_MS` with `anchor >= deadline`, i.e. when
// it is later than `deadline - OFF_TRUST_MS`. An earlier one can never change `active`, so it is
// kept in memory but not written: a dormant install does not rewrite the file on every check.
const save = stored.latched === true || offAt > PROJECT_LIMIT_DEADLINE_MS - OFF_TRUST_MS
void commit({ ...stored, latched: false, offAt }, save)
}
// 'unknown' changes nothing: a reply that did not come from the route must not move the latch.
}
function fail(error: ClaimError, retryAfter?: number): ClaimResult {
return retryAfter === undefined
? { ok: false, error, state: state() }
: { ok: false, error, retryAfter, state: state() }
}
async function runClaim(): Promise<ClaimResult> {
const gate = licenseNetworkGate()
if (gate !== 'ok') return fail(gate)
// Dormant: there is no limit to claim an allowance against, so nothing is asked — no request and
// no machine read, whoever calls. After the gate, so `consent_required` / `disabled` still surface.
const now = state()
if (!now.active) return { ok: true, state: now }
const deviceId = getDeviceId()
const machine = await deps.machineHash()
const count = stored.firstLaunchOpenCount
const ctrl = new AbortController()
const timer = setTimeout(() => ctrl.abort(), CLAIM_TIMEOUT_MS)
let status: number
let body: unknown
try {
const res = await fetch(`${API_BASE}/v1/limits/claim`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
deviceId,
machine: machine.hash,
firstLaunchOpenCount: count === undefined ? null : Math.min(count, COUNT_MAX)
}),
signal: ctrl.signal
})
status = res.status
try {
body = await res.json()
} catch (err) {
// Only a body that arrived and is not JSON is the server's. A body cut off by the timeout, or
// by the connection dropping mid-read (undici: `TypeError: terminated`), is the network failing.
if (ctrl.signal.aborted || !(err instanceof SyntaxError)) return fail('offline')
body = undefined
}
} catch {
return fail('offline')
} finally {
// Cleared only once the body has been read: see CLAIM_TIMEOUT_MS.
clearTimeout(timer)
}
const b = isRecord(body) ? body : {}
if (status >= 200 && status < 300) {
const { token, free, epoch } = b
if (typeof token !== 'string' || !isFree(free) || !isEpoch(epoch)) return fail('server')
// A 2xx is only an allowance if its token is one: signed, for this device, the machine we sent
// and the epoch the reply states.
if (!verifyAllowanceToken(token, { deviceId, machine: machine.hash, epoch }, allowanceKey())) {
return fail('server')
}
if (machine.fromOs) osMachine = machine.hash
await commit({ ...stored, latched: true, free, epoch, token }, true)
return { ok: true, state: state() }
}
if (status === 409 && b.error === 'not_active') {
const next: Stored = { ...stored, latched: false, offAt: clockAnchorMs() }
delete next.token
await commit(next, true)
return { ok: true, state: state() }
}
if (status === 409 && b.error === 'machine_mismatch') {
return fail('machine_mismatch', isCount(b.retryAfter) && b.retryAfter > 0 ? b.retryAfter : undefined)
}
// 429 (rate limited), 5xx, 400, an unknown 409, any other status (a 404 included — a server with
// claims switched off answers 409 not_active, never 404): never a final answer.
return fail('server')
}
function claim(): Promise<ClaimResult> {
if (!claimInFlight) {
const run = runClaim().catch((err): ClaimResult => {
console.warn('[project-limit] claim failed', err instanceof Error ? err.message : String(err))
return fail('server')
})
claimInFlight = run.finally(() => {
claimInFlight = null
})
}
return claimInFlight
}
export function initProjectLimit(d: ProjectLimitDeps): ProjectLimitHandle {
deps = d
stored = load()
osMachine = null
claimInFlight = null
lastSent = JSON.stringify(compute())
const handle: ProjectLimitHandle = { state, claim, refresh: notify, pushIfChanged }
platform().handle(IPC.projectLimitState, () => handle.state())
platform().handle(IPC.projectLimitClaim, () => handle.claim())
onCheckAnswer(onAnswer)
// Only with a stored token: the limit was on once (an undo via the check feed keeps the token).
if (stored.token && allowanceKey()) {
track(
deps
.machineHash()
.then((m) => {
if (!m.fromOs) return
osMachine = m.hash
notify()
})
.catch(() => {})
)
}
const readCheck = (): void => {
track(fetchCheck().catch(() => {}))
}
// After the workspace load, whichever way it settles: the open-project count rides this read only
// once the index is known (check.ts), and the next read of our own is the 6 h tick.
if (deps.ready) track(deps.ready.finally(readCheck).catch(() => {}))
else readCheck()
setInterval(() => {
// Time alone can change the state (see pushIfChanged); the check below covers the server's word.
pushIfChanged()
readCheck()
}, CHECK_INTERVAL_MS).unref()
return handle
}
/** TEST ONLY: resolves once every background read and write started so far has settled. */
export async function __projectLimitIdleForTests(): Promise<void> {
while (pending.size) await Promise.allSettled([...pending])
}
/** TEST ONLY: the machine hash stored tokens are judged against (null = provisional trust). */
export function __projectLimitMachineForTests(): string | null {
return osMachine
}