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
fix(project-limit): a build without the allowance key is never active
review1bac5973720b
diff --git a/docs/project-limit.md b/docs/project-limit.mdindex 9e632ec75..cd657d6f3 100644--- a/docs/project-limit.md+++ b/docs/project-limit.md@@ -75,11 +75,17 @@ gate. How that is held, layer by layer:In core (`src/core/project-limit.ts`, `isActive`):```-active = packaged build AND (latched OR (anchor >= PROJECT_LIMIT_DEADLINE_MS AND NOT a server "off" in the last 24 h))+active = packaged build AND allowance key configured+ AND (latched OR (anchor >= PROJECT_LIMIT_DEADLINE_MS AND NOT a server "off" in the last 24 h))```- **Packaged only.** `npm run dev` builds are never active, with or without `NODETERM_API_BASE`.The Server Edition never runs this module at all (see Three surfaces).+- **Only with the allowance key.** A build whose `PROJECT_ALLOWANCE_PUBLIC_KEY` is `''` (shipped+ before owner step O1) is never active, whatever the server or the deadline says: it could verify+ no allowance, so every claim would fail and every install — legacy ones included — would be held+ at FREE. It stays unlimited instead, exactly like a build from before the limit existed (no claim,+ no dialog, no machine read).- **The latch is the server's word.** A check reply carrying `limits: { projects: { free, epoch } }`sets it (and stores FREE and the epoch). It is cleared by exactly two answers: a successful,*check-shaped* reply (a `messages` array and an `update` object) **without** `limits`, or a claim@@ -270,14 +276,11 @@ What enforces it:- **On the server**, without the private key the claim route does not exist (404) and `/v1/check`never sends `limits`, whatever the cutoff says.-**Do O1 before the next release you expect people to still be running at the flip — not just-before the flip release.** While the key is `''` every allowance token verifies to `null`. Nothing-happens while the limit is off, but a build with an empty key that is still in use when the server-switches the limit on fails every claim (the server's signed token does not verify, which reads as a-server error): its installs — legacy ones included — are held at FREE behind "Couldn't check your-free allowance" until they update. (Nothing is closed; new opens above FREE are refused.) The-guard only enforces the key at the flip release, because refusing every release before O1 would-block unrelated releases; so the timing is the owner's to keep.+**A build shipped with `''` is never active** — it stays unlimited, like a build from before the+limit (see How `active` is computed), even after the flip. So every release made before O1 adds to+the installs the limit will never reach until they update (Accepted gaps). The guard enforces the+key only at the flip release, because refusing every release before O1 would block unrelated+releases; doing O1 early is the owner's call.### NODE_EXTRA_CA_CERTS / NODE_OPTIONS (owner's call before Release B)@@ -325,7 +328,7 @@ The decision is enes's. Device check 10 below gathers the evidence.- **O3 — Release B:** confirm server#18 is deployed (`/v1/license/status` answers 502 when keygen isdown — otherwise a keygen outage drops paying users into the limit); merge and deploy the serverclaims with `PROJECT_ALLOWANCE_PRIVATE_KEY` set **and the cutoff still unset**; release this- client — with the O1 public key pasted, or its installs will fail every claim after the flip.+ client — with the O1 public key pasted, or its installs stay unlimited even after the flip.Every later release before the flip bumps `PROJECT_LIMIT_DEADLINE_MS` (the release workflowrefuses otherwise).- **O4 — flip day:**@@ -377,7 +380,8 @@ The decision is enes's. Device check 10 below gathers the evidence.## Accepted gaps (by design, and found while building)-1. Builds released before Release B stay unlimited forever.+1. Builds released before Release B stay unlimited forever — and so do builds released without the+ allowance public key (before owner step O1), which are never active.2. The Server Edition is unlimited.3. Hand-editing `workspace.json` to un-close projects bypasses the gate; never clamped. The sameclass: a hand-edited future `offAt` in `project-limit.json` suppresses the deadline.@@ -412,9 +416,10 @@ Rough edges a user can notice (behaviour, not bypasses):Run on **packaged** builds (a dev build is never active). For the server runs, launch the app with`NODETERM_API_BASE=<staging URL>` in its environment (start the binary from a terminal — on macOS-`<app>/Contents/MacOS/nodeterm`, not `open`, which drops the environment). The staging server must-hold the private half of the public key compiled into that build (O1): with a mismatched pair every-claim's token fails verification and reads as "Couldn't check your free allowance".+`<app>/Contents/MacOS/nodeterm`, not `open`, which drops the environment). The build must carry an+allowance public key — without one it is never active, and the server runs show nothing — and the+staging server must hold its private half: with a mismatched pair every claim's token fails+verification and reads as "Couldn't check your free allowance".**Run 1 — packaged builds, no server needed**diff --git a/scripts/check-project-limit-deadline.mjs b/scripts/check-project-limit-deadline.mjsindex e9be345d6..d1931d3ce 100644--- a/scripts/check-project-limit-deadline.mjs+++ b/scripts/check-project-limit-deadline.mjs@@ -11,7 +11,8 @@//// The FLIP release (frozen) also needs owner step O1 done: `PROJECT_ALLOWANCE_PUBLIC_KEY`// (src/core/project-allowance-key.ts) ships as '' until the owner pastes the public half of the-// server's `PROJECT_ALLOWANCE_PRIVATE_KEY`, and with '' every allowance token verifies to nothing.+// server's `PROJECT_ALLOWANCE_PRIVATE_KEY`, and with '' the limit never switches on (core treats a+// keyless build as unlimited, like one from before the limit).// So a frozen release is refused while the key is empty, unreadable, not an Ed25519 public-key PEM,// or a PRIVATE key. An unfrozen release does not look at the key at all.//diff --git a/src/core/project-allowance-key.ts b/src/core/project-allowance-key.tsindex 20daeef1d..0ba58705c 100644--- a/src/core/project-allowance-key.ts+++ b/src/core/project-allowance-key.ts@@ -7,9 +7,9 @@// nor `tier`, so an allowance token signed with the entitlement key would read as Pro everywhere.//// TODO(O1): the owner pastes the production SPKI PEM here (docs/project-limit.md, O1). Until then-// it is empty and every allowance token verifies to null: harmless while the limit is off, but a-// build with '' that is still in use at the flip fails every claim, so do it before the next-// release expected to be running then. The flip (frozen-deadline) release is refused while it is-// empty (scripts/check-project-limit-deadline.mjs); project-allowance-token.test.ts accepts only ''-// or a real Ed25519 public-key PEM distinct from ENTITLEMENT_PUBLIC_KEY.+// it is empty: every allowance token verifies to null and core never switches the limit on (a+// keyless build stays unlimited, like one from before the limit), so each release made before O1 is+// one the limit will never reach. The flip (frozen-deadline) release is refused while it is empty+// (scripts/check-project-limit-deadline.mjs); project-allowance-token.test.ts accepts only '' or a+// real Ed25519 public-key PEM distinct from ENTITLEMENT_PUBLIC_KEY.export const PROJECT_ALLOWANCE_PUBLIC_KEY: string = ''diff --git a/src/core/project-limit.test.ts b/src/core/project-limit.test.tsindex 8d4894ce4..8d7d421b5 100644--- a/src/core/project-limit.test.ts+++ b/src/core/project-limit.test.ts@@ -5,6 +5,7 @@ import path from 'path'import { IPC } from '../shared/ipc'import { PROJECT_LIMIT_DEADLINE_MS, type ClaimResult, type ProjectLimitState } from '../shared/project-limit'import { machineHashOf, type MachineHashResult } from './machine-id'+import { PROJECT_ALLOWANCE_PUBLIC_KEY } from './project-allowance-key'import { makeFakeUserDataDir, type FakePlatform } from './platform-fake'// The Pro test needs a real entitlement token: license.ts verifies against this key.@@ -130,6 +131,8 @@ async function boot(file?: unknownopenProjects?: () => number | undefinedmachineHash?: () => Promise<MachineHashResult>+ /** The allowance key passed to core: the test key unless given; `undefined` = the shipped key. */+ publicKeyPem?: stringwait?: boolean} = {}): Promise<Booted> {@@ -146,7 +149,11 @@ async function boot(const handle = mod.initProjectLimit({openProjects: opts.openProjects ?? (() => 3),machineHash: opts.machineHash ?? machineSpy,- publicKeyPem: ALLOWANCE_PUB,+ ...('publicKeyPem' in opts+ ? opts.publicKeyPem === undefined+ ? {}+ : { publicKeyPem: opts.publicKeyPem }+ : { publicKeyPem: ALLOWANCE_PUB }),notify: (s) => notified.push(s)})booted = {@@ -201,6 +208,34 @@ afterEach(async () => {})describe('project limit: on or off', () => {+ it('is never active without the allowance key — latched, past the deadline, told "on" — and claims nothing', async () => {+ // Such a build could verify no allowance: every claim would fail and every install, legacy ones+ // included, would be held at FREE. It stays unlimited instead, like a build from before the limit.+ vi.setSystemTime(AFTER)+ const file = { latched: true, free: 5, epoch: 1, token: allowanceToken() }+ const { handle } = await boot({ publicKeyPem: '', file })+ expect(handle.state().active).toBe(false)+ await answer(checkOn(5, 1))+ expect(handle.state().active).toBe(false)+ expect(notified.every((s) => !s.active)).toBe(true)+ fetchMock.mockClear()+ expect(await handle.claim()).toEqual({ ok: true, state: handle.state() })+ expect(fetchMock).not.toHaveBeenCalled()+ // Not even the boot-time machine read a stored token would otherwise start.+ expect(machineSpy).not.toHaveBeenCalled()++ // The control: the same install with a key is on.+ const keyed = await boot({ file })+ expect(keyed.handle.state().active).toBe(true)+ })++ it('reads the shipped key when none is passed', async () => {+ vi.setSystemTime(AFTER)+ const { handle } = await boot({ publicKeyPem: undefined, file: { latched: true } })+ // '' until owner step O1, so off; on once the real key is pasted.+ expect(handle.state().active).toBe(PROJECT_ALLOWANCE_PUBLIC_KEY !== '')+ })+it('is inactive in an unpackaged build even when latched', async () => {vi.setSystemTime(AFTER)const { handle } = await boot({ packaged: false, file: { latched: true, free: 5, epoch: 1 } })diff --git a/src/core/project-limit.ts b/src/core/project-limit.tsindex 886a01adb..76669274b 100644--- a/src/core/project-limit.ts+++ b/src/core/project-limit.ts@@ -1,12 +1,13 @@/**- * The free-tier open-project limit, desktop core (docs/superpowers/specs/2026-10-29-free-tier-project-limit-design.md- * §5–§6). 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)+ * 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 (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.+ * 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; a successful check* without them, 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.@@ -55,6 +56,7 @@ import { clockAnchorMs, isDntEnv, licenseNetworkGate, proForProjectLimit } fromimport { 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'@@ -88,7 +90,7 @@ export interface ProjectLimitDeps {/** `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. Tests pass their own. */+ /** 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@@ -162,8 +164,11 @@ function persist(): Promise<void> {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) return false+ if (!platform().isPackaged || !allowanceKey()) return falseif (stored.latched) return trueconst anchor = clockAnchorMs()return anchor >= PROJECT_LIMIT_DEADLINE_MS && !(stored.offAt !== undefined && anchor - stored.offAt < OFF_TRUST_MS)@@ -174,7 +179,7 @@ function allowance(): number | null {const v = verifyAllowanceToken(stored.token,{ deviceId: getDeviceId(), machine: osMachine, epoch: stored.epoch },- deps.publicKeyPem+ allowanceKey())return v ? v.allowance : null}@@ -319,7 +324,7 @@ async function runClaim(): Promise<ClaimResult> {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 }, deps.publicKeyPem)) {+ if (!verifyAllowanceToken(token, { deviceId, machine: machine.hash, epoch }, allowanceKey())) {return fail('server')}if (machine.fromOs) osMachine = machine.hash@@ -364,7 +369,7 @@ export function initProjectLimit(d: ProjectLimitDeps): ProjectLimitHandle {onCheckAnswer(onAnswer)// Only with a stored token: the limit was on once (an undo via the check feed keeps the token).- if (stored.token) {+ if (stored.token && allowanceKey()) {track(deps.machineHash()