Skip to content

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.

fix(project-limit): a build without the allowance key is never active

review1bac5973720b
diff --git a/docs/project-limit.md b/docs/project-limit.md
index 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 is
down — otherwise a keygen outage drops paying users into the limit); merge and deploy the server
claims 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 workflow
refuses 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 same
class: 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.mjs
index 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.ts
index 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.ts
index 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?: unknown
openProjects?: () => number | undefined
machineHash?: () => Promise<MachineHashResult>
+ /** The allowance key passed to core: the test key unless given; `undefined` = the shipped key. */
+ publicKeyPem?: string
wait?: 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.ts
index 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 } from
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'
@@ -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 false
if (stored.latched) return true
const 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()