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
docs(project-limit): runbook, device checklist and release deadline guard
review29097fa55a9b
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex b3e68a270..8de757086 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -30,6 +30,14 @@ jobs:# network blip — after every asset had uploaded — which skipped the publish gate and# stranded v0.2.23 as a prerelease. The ephemeral Linux runner below keeps its cache.+ # The free-tier project limit's embedded deadline (PROJECT_LIMIT_DEADLINE_MS) must be bumped+ # in every release before the flip, or DO_NOT_TRACK users are gated before anyone else. This+ # refuses a tag whose deadline is under 30 days away (until it is frozen at the flip). Plain+ # node, no npm ci, so a refused release fails in seconds. A failure here keeps `publish` (which+ # needs this job) from promoting the tag. See docs/project-limit.md.+ - name: Project-limit deadline guard+ run: node scripts/check-project-limit-deadline.mjs+# caffeinate on EVERY long-running step in this job, not just build+upload: the Air# sleeping during npm ci or the tmux compile cancels the step just the same (the# v0.3.1 attempt died mid tmux build). -dims only blocks idle sleep — a closed liddiff --git a/CLAUDE.md b/CLAUDE.mdindex 960809ed6..97363929f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -9933,6 +9933,23 @@ unix-socket forward and dev-server `-L` forward over it. POSIX keeps OpenSSH unt(`applyPhoneReadAck`, the ack sweeper's body), plus `fs.browse` (home-jailed, dirs only) and`pty.capture`; `host.info` lists them. All additive — an old phone keeps its old path.+## Free-tier open-project limit (shipped dormant; the server switches it on)++A non-Pro desktop install may keep FREE (a server value) projects open, a pre-cutoff install its+signed allowance; Pro is unlimited. Design, runbook, checklist: **`docs/project-limit.md`**.+- **One count**: `countOpenProjects` (`shared/project-limit.ts`) / `WorkspaceStore.openProjectCount`+ — in the workspace, not `closed`, not a relay tab. Never write a second one.+- **Never force-close.** The gate refuses a NEW open and nothing else; no project, node or tmux+ session is ever closed, deleted or detached because of the limit, even above the allowance.+- **Placement**: a human open calls `gateProjectOpen` (`renderer/lib/projectLimitGate.ts`) as the+ LAST await before its synchronous store mutation, skipped when `opensProject(...)` is false;+ allowed returns the literal `true` in the same tick, so while the limit is off every path stays+ synchronous with no network, dialog or write. The agent `open-project` verb decides and writes in+ one tick (`finishAgentProjectOpen`).+- **Relay tabs are never gated or counted**; `projectLimit:*` is host-only and `projectLimit:changed`+ reaches this machine's windows only. **The Server Edition has no gate** (stub answers inactive).+- `PROJECT_LIMIT_DEADLINE_MS` is bumped every release until the flip — release.yml refuses < 30 days.+## `nodeterm://` links (another app asks to open a node)`nodeterm://open?agent=…&project=…|project-cwd=…&cwd=…&prompt=…|prompt-file=…&title=…&source=…`@@ -10739,8 +10756,15 @@ Server Edition: no updater (stubs; `onInstalling`/`onFlushRequest` are documenteThe "auto-download off" setting is NOT here — that is PR #956's.**Backend check feed** (`src/core/check.ts`, successor to the static `announcements.json`): the-**main process** calls `GET https://api.nodeterm.dev/v1/check?version=&os=&channel=stable` (so the-renderer CSP stays `'self'`) on launch + every 6h, cached 5 min, returning `{ messages, update }`.+**main process** calls `GET https://api.nodeterm.dev/v1/check?deviceId=&version=&os=&arch=&channel=stable&plan=`+(so the renderer CSP stays `'self'`) on launch + every 6h, cached 5 min, returning `{ messages, update }`.+`deviceId` is the anonymous install id the backend counts active installs by. **Only while Settings →+Privacy → Telemetry is on** does the query also carry `openProjects=<n>` (the open-project count, a+number only; the backend keeps each device's maximum for the project limit). The reply may also+carry `limits: { projects: { free, epoch } }` while the free-tier project limit is on (absent = off);+core hears it through `onCheckAnswer`, and only a CHECK-SHAPED reply (a `messages` array + an+`update` object) without `limits` reads as off and clears the latch — anything else is `unknown` and+changes nothing (see **Free-tier open-project limit**).Exposed split over two IPC handlers: `announcements.fetch()` → `messages`, `appUpdatePolicy` →`update`. `components/AnnouncementBanner.tsx` (stacked above `UpdateCard` under the tab bar in a`.top-banners` column) shows the newest message the user hasn't dismissed (dismissed `id`s persist@@ -10755,7 +10779,9 @@ with: the 5-min cache is keyed by plan, a failed read after a plan change keepsNOT the other plan's messages, and the banner re-asks when `useEntitlement.isPremium` flips — else a"try Pro" message stays up for six hours after the user pays. **Telemetry** (`src/main/telemetry.ts`) is a separate opt-outping to `api.nodeterm.dev/v1/ping` (version/OS on launch + daily), gated on-`settings.telemetryEnabled` + the same build/DNT guards; toggle in Settings → Privacy.+`settings.telemetryEnabled` + the same build/DNT guards; toggle in Settings → Privacy. **That toggle+gates the ping AND the check's `openProjects` count — never the check itself**, which runs whatever+it says (only DNT / `NODETERM_TELEMETRY_DISABLED` / an unpackaged build stop it).## Atomic writes (never a bare `fs.rename`)diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7b5e5c109..103890f03 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1242,6 +1242,8 @@ disable it with its reason (`NEW_FILE_NO_CWD_HINT`,nothing, and a message that names the wrong cause ("not a git repository" for a project that has nofolder to be one) sends the user hunting a problem that does not exist.+**Opening a project goes through `gateProjectOpen` (`src/renderer/lib/projectLimitGate.ts`); a new way to open one must call it — see `docs/project-limit.md`.**+**Agent features attach to base harness capabilities, not frontend allowlists.** A custom agent caninherit a builtin harness, so add the capability and its one shared leaf (`src/shared/agents`) andlet every UI ask the helper. Repeating Claude/Codex/etc. cases in menus breaks that inheritance anddiff --git a/docs/project-limit.md b/docs/project-limit.mdnew file mode 100644index 000000000..c1cb05ae4--- /dev/null+++ b/docs/project-limit.md@@ -0,0 +1,397 @@+# Free-tier open-project limit++A free desktop install may keep a limited number of projects **open** at once; Pro is unlimited;+installs that existed before the switch-on keep the number they already worked with. The client+ships the whole mechanism **switched off** and the server turns it on: until the server sets a+cutoff, no open path behaves differently from before this feature existed.++Design (binding): [`docs/superpowers/specs/2026-10-29-free-tier-project-limit-design.md`](superpowers/specs/2026-10-29-free-tier-project-limit-design.md)+(§n below refers to it). Implementation plan: `docs/superpowers/plans/2026-10-29-free-tier-project-limit.md`.++Code: `src/shared/project-limit.ts` (the count, the decision, the deadline), `src/core/project-limit.ts`+(on/off, the latch, the allowance, the claim), `src/core/license.ts` (clock anchor, Pro for the+limit, DO_NOT_TRACK consent), `src/core/machine-id.ts` + `src/core/project-allowance-token.ts`+(the machine hash and the offline token check), `src/core/check.ts` (the server's on/off answer),+`src/renderer/lib/projectLimitGate.ts` (the gate), `src/renderer/state/projectLimit.ts` ++`src/renderer/components/ProjectLimitDialog.tsx` (the limit moment). Server: nodeterm-server's+`/v1/check`, `POST /v1/limits/claim` and the admin console's **Project limit** card.++## Definitions (§3)++- **Open project**: a project in the workspace that is not `closed` and not a relay tab+ (`project.remote`). SSH projects, cwd-less canvases and unavailable placeholders count — each is+ a tab on the user's screen. Closed projects ("Recently closed") and relay tabs never count.+ **One definition**: `countOpenProjects` (`src/shared/project-limit.ts`), and in core+ `WorkspaceStore.openProjectCount` (the workspace index never holds relay tabs). The open-project+ report (Release A) and the gate both use it.+- **Opening a project**: anything that makes a project open that was not — new project, Open+ folder… (including adopting an existing `.nodeterm/project.json` and reusing a *closed* project+ for that folder), the SSH dialog (including reusing a closed SSH project), reopening from+ Recently closed / the welcome screen / ⌘K / the sessions sidebar / ⇧⌘T / a notification or link+ into a closed project, and the agent `open-project` verb. Activating a project that is already+ open is not an open. Creating a relay or team tab is never an open.+- **Cutoff**: one server-side timestamp. It is both the legacy line (the open-project maximum a+ device reported *before* it is what grandfathers it) and the switch-on moment.+- **Allowance**: how many open projects a non-Pro install may have. The server computes it at the+ install's first claim (§4) and signs it into an allowance token.+- **FREE / CAP / epoch**: server values (admin card). FREE is the allowance of a new install (the+ client compiles `PROJECT_LIMIT_DEFAULT_FREE` only for before the server has said otherwise); CAP+ caps both client-reported legacy counts; the epoch is bumped to make every issued allowance be+ recomputed. Initial values: FREE 5, CAP 50, epoch 1, cutoff unset.++## The dormant invariant++While `active` is false, every open path behaves exactly as it did before this feature, **including+staying synchronous where it was synchronous**. No network call, no modal, no state written by the+gate. How that is held, layer by layer:++- `gateProjectOpen()` returns the literal `true` in the same tick when `decideOpen` allows (no+ promise, no microtask), and an inactive state always allows. Each caller writes+ `if (g !== true && !(await g)) return`, so a dormant open never awaits.+- Core's `claim()` returns `{ ok: true, state }` without a request and without reading the machine+ id when the limit is off, whoever calls it.+- The machine id is read only by a claim, or at boot when an allowance token is already stored —+ never on a dormant install.+- The only request a dormant install makes is `/v1/check`, the call it already made. Core also+ reads it at boot and every 6 h, through the same 5-minute cache and the same build /+ DO_NOT_TRACK guards. Core records the first-launch count once (§6, by design);+ `project-limit.json` is otherwise written only when a server word changes the stored state, not+ on every check.+- The agent `open-project` verb asks synchronously too while the limit is off; the headless start+ of a node in a closed project unhides exactly as before.++## How `active` is computed++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))+```++- **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).+- **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+ answering `409 not_active`. A failed check, a non-2xx, an HTML captive portal, a JSON page that is+ not a check reply, or a malformed `limits` is no answer and changes nothing — being unreachable+ never turns the limit off.+- **The embedded deadline** (`PROJECT_LIMIT_DEADLINE_MS`) covers a client whose check never runs+ (DO_NOT_TRACK, `NODETERM_TELEMETRY_DISABLED`, a blocked host). Past it the client treats the limit+ as on, which in practice only means "claim before opening beyond FREE"; a `not_active` answer+ turns it off again. It is compared against the **clock anchor** (`clockAnchorMs`: the later of the+ wall clock and the latest instant this install has observed), so rolling the clock back does not+ undo it.+- **A server "off"** (`offAt`) suppresses the deadline for `OFF_TRUST_MS` (24 h); a check that keeps+ answering off keeps refreshing it.+- Changes are pushed to this machine's windows (`projectLimit:changed`) after every server word and+ on a 6-hourly tick for what time alone changes (the deadline passing, an "off" going stale, Pro's+ grace lapsing), so a long-running app does not stay dormant past the deadline.++The rest of the state (`ProjectLimitState`):++- `free`: FREE as the server last sent it, else the compiled default.+- `allowance`: from the stored token, verified **offline on every read** — signature (the separate+ allowance key), `typ`, deviceId, epoch, and the machine hash. The machine is judged only against a+ hash from a *successful* OS read; while none is known yet (read pending at boot, or the OS read+ failed and only the hostname fallback exists) the token is trusted provisionally on everything+ else. A check that announces a different epoch deletes the token; the next open at the limit+ claims again.+- `pro`: `proForProjectLimit()` — `isPremium()`, or an entitlement token that expired less than+ 30 days ago by the clock anchor with no 2xx `active:false` from the server since. That grace is for+ the limit only; no other Pro feature sees it.+- `dnt`: DO_NOT_TRACK / `NODETERM_TELEMETRY_DISABLED` is set — a claim (and a purchase) needs the+ user's consent first.++One open is then decided by `decideOpen(state, openCount)`: off or Pro → allow; fewer open than+`effectiveLimit` (`max(allowance ?? free, free)` — an old allowance never undercuts a raised FREE)+→ allow; at the limit with no allowance yet → claim first; at or above a known allowance → block.+Above it is reachable (a Pro lapse): the new open is blocked and **nothing is closed**.++## Where the gate sits++Every way a person opens a project goes through `gateProjectOpen`+(`src/renderer/lib/projectLimitGate.ts`), in five Canvas call sites: `addProject`,+`openOrAdoptFolder`, `createSshProject`, `onRepoCloned`, `reopenProject`. The rule:++```ts+const g = opensProject(useProjects.getState().projects, action) ? gateProjectOpen() : true+if (g !== true && !(await g)) return+```++- The gate is the **last await** before the synchronous store mutation, so nothing can change the+ count between the decision and the write.+- It is **skipped** when `opensProject(...)` (`src/renderer/lib/projectOpens.ts`) says the action+ opens nothing (the folder or SSH host is already an open project). That predicate uses each store+ action's own matcher, so the prediction cannot drift from what the action does.+- `reopenProject` keeps its synchronous path when `g === true`. `reopenProjectUnchecked` (the+ share-to-team undo: the project was open moments before) stays ungated.+- **Relay and team tabs are never gated** (`addRelayTab`, `hostedTeamTabs`, `relay-tab.ts`), and+ never counted.+- **The agent `open-project` verb** goes through `checkAgentProjectOpen` (early, before the folder+ probe) and `finishAgentProjectOpen` (the final decision and `registerProject` in one tick). A+ refusal is the plain sentence `free plan: N of N projects are open; the user has been shown the+ options`, and the user sees the dialog at most once per minute of refusals. The agent-facing verb+ help says not to retry. A headless start of a node in a CLOSED project at the limit starts the+ session but does not unhide the project (the existing "reopen it from the welcome screen" reply).+- A new way to open a project must call the gate. `src/renderer/canvas/project-limit-opens.source.test.ts`+ pins the five call sites.++**Never force-close.** The gate only answers whether one NEW open may proceed. Nothing closes,+deletes or detaches a project, a node or a tmux session because of the limit — not at the limit,+not above it.++## The limit moment (§7)++1. No token yet → claim. The "Checking your free allowance…" panel appears only if the claim is+ still in flight after 300 ms. If the claimed allowance permits the open, it proceeds with no+ dialog.+2. Still at the limit → the dialog: "N of N free projects are open", the open projects each with+ **Close** (`closeProject`, non-destructive), **Cancel**, and **Unlimited with Pro — $10/mo**.+ After a Close, or once Pro arrives through the license broadcast, the pending open proceeds.+3. A failed claim (offline, server error) → the same dialog with "Couldn't check your free+ allowance" and **Retry**; Close and Pro still work. A `machine_mismatch` says the allowance is tied+ to another computer and, when the server gave one, the date it can move.+4. DO_NOT_TRACK without consent → "Connection needed" first. Consent is+ `settings.licenseNetworkConsent`, shown and revocable in Settings → Privacy only while DNT is set,+ never settable by an agent, and it covers license and claim calls only — never telemetry or the+ check feed.++While the limit is on, the Pro comparison (Settings) heads Core "Core — free" (not "free forever")+with "Up to N open projects", lists "Unlimited open projects" under Pro, and the upgrade dialog adds+"unlimited open projects". Inactive, both read exactly as before.++## Data++- `<userData>/project-limit.json`: `latched`, `offAt`, `free`, `epoch`, `token`,+ `firstLaunchOpenCount` (the open-project count at the first launch of a limit-capable build — the+ late-updater basis). Written through `writeFileAtomic`; every wrong-typed field is dropped on its+ own and a bad file reads as empty.+- `/v1/check` (every install, unless DO_NOT_TRACK / `NODETERM_TELEMETRY_DISABLED` / an unpackaged+ build without `NODETERM_API_BASE`): `deviceId, version, os, arch, channel, plan`, and **only+ while Settings → Privacy → Telemetry is on** `openProjects=<n>` — a number, never names, paths or+ hosts. The server keeps each device's maximum (until the cutoff).+- `POST /v1/limits/claim` (only at the limit moment, only while active):+ `{ deviceId, machine, firstLaunchOpenCount }`. `machine` = lowercase hex SHA-256 of+ `'nodeterm-project-allowance-v1:' + rawMachineId.trim().toLowerCase()` (macOS `IOPlatformUUID`,+ Linux `/etc/machine-id`, Windows `MachineGuid`; after two failed OS reads, the hostname). The raw id+ never leaves `machine-id.ts`. Replies: `200 { token, free, epoch }`, `409 not_active`,+ `409 machine_mismatch` + `retryAfter` (unix seconds), `429` (10 per minute per address — retryable,+ never final). Claims time out after 8 s and never reject.+- Allowance token: `base64url(payloadJSON).base64url(ed25519sig)`, payload+ `{ typ: 'project-allowance', deviceId, machine, allowance, epoch, iat }`, no expiry, signed with+ `PROJECT_ALLOWANCE_PRIVATE_KEY` — a key of its own, never the entitlement key (shipped clients do+ not check `typ` on an entitlement token, so one signed with that key would read as Pro).++## Three surfaces (§10)++- **Desktop**: everything above.+- **Server Edition**: no gate, no claim. The bridge stub answers `INACTIVE_PROJECT_LIMIT` and+ claims `disabled`; `src/server` never calls `initProjectLimit`. Running the Server Edition avoids+ the limit — a documented gap (§13), enes's call.+- **Mobile**: N/A — the phone opens no desktop projects. Relay tabs are excluded from the count, and+ `projectLimit:*` is host-only: a relay peer can neither call it nor receive `projectLimit:changed`+ (core sends it to this machine's windows only, never through `platform().broadcast`).+- **Kanban**: N/A — the board creates nodes inside a project, never projects.++## Release checklist++1. **Every release before the flip bumps `PROJECT_LIMIT_DEADLINE_MS`** (`src/shared/project-limit.ts`)+ to a date past the planned flip. A deadline that passes before the flip gates DO_NOT_TRACK users+ before anyone else.+2. **At the flip** (the release that precedes or accompanies it): set the deadline to the flip date+ and `PROJECT_LIMIT_DEADLINE_FROZEN = true`. From then on the deadline is the flip date for good.+3. Keep both constants in their literal one-line form —+ `export const PROJECT_LIMIT_DEADLINE_MS = Date.parse('<ISO instant>')` and+ `export const PROJECT_LIMIT_DEADLINE_FROZEN = true | false` — because the guard reads the source.++**The guard**: `scripts/check-project-limit-deadline.mjs` is the first step of the `release-mac` job+in `.github/workflows/release.yml` (after checkout, before `npm ci`; plain node). It exits 1 when the+deadline is less than 30 days away and not frozen, or when it cannot read the constants. A refused+release fails that job, and `publish` (which needs it) never promotes the tag. The Linux and Windows+jobs run in parallel and may still upload their assets to the tag's **prerelease**; it never becomes+"latest". Bump the deadline, then delete that prerelease and re-tag, or tag the next version.+`scripts/check-project-limit-deadline.test.ts` pins the guard's reading to the compiled constants,+so a change of literal form fails on the PR, not on release day.++## Before Release B ships — owner decisions++### O1: the allowance key pair (merge guard)++`PROJECT_ALLOWANCE_PUBLIC_KEY` in `src/core/project-allowance-key.ts` is `''` until the owner+generates the key pair:++```sh+openssl genpkey -algorithm ed25519 -out allowance.pem && openssl pkey -in allowance.pem -pubout+```++The private key goes **only** into the server's Dokploy env as `PROJECT_ALLOWANCE_PRIVATE_KEY`; the+public half (SPKI PEM) goes into `project-allowance-key.ts`. Delete the local `.pem` afterwards.+Until then the test "PROJECT_ALLOWANCE_PUBLIC_KEY parses as an Ed25519 public key and differs from+ENTITLEMENT_PUBLIC_KEY" (`src/core/project-allowance-token.test.ts`) is **red on purpose**, and+every allowance token verifies to `null` (no allowance — a claim then reads as a server error). On+the server, without the private key the claim route does not exist (404) and `/v1/check` never+sends `limits`, whatever the cutoff says.++### NODE_EXTRA_CA_CERTS / NODE_OPTIONS (owner's call before Release B)++The hardening fuse `enableNodeOptionsEnvironmentVariable: false` (`package.json`+`build.electronFuses`, spec §12) makes Electron **unset** `NODE_OPTIONS` **and**+`NODE_EXTRA_CA_CERTS` at process start, in GUI and RunAsNode mode alike (measured on Electron+42.11.16). Consequences:++- Every descendant loses both: the tmux server from its next start, and with it every shell and+ Node-based agent CLI in a terminal (claude, gemini, opencode, copilot); the commit-message agent;+ on Windows the session host and every ConPTY shell under it.+- Main-process HTTPS is Node's `fetch`, so a CA trusted only through `NODE_EXTRA_CA_CERTS` is gone+ for: license, check, project-limit claims, telemetry, model-gateway discovery, the local usage+ readers, git-service, pairing and the relay host. Behind a TLS-intercepting proxy that means: stuck+ at FREE, every claim "could not check", Pro not refreshing.+- **Affected**: users whose GUI launch environment carries those variables (macOS+ `launchctl setenv` / MDM, Windows user or system environment variables, Linux `environment.d` or+ `/etc/environment`). **Not affected**: users who export them in a shell rc (every interactive+ shell re-applies them). No evidence in the repo or its issues that anyone relies on it today.+- **Why the fuse is kept**: without it `NODE_OPTIONS=--require …` runs arbitrary code inside the+ main process (measured against an unfused control) — a one-line bypass of the gate on macOS and+ Windows.++Options before Release B ships:++- **(a)** Ship with the cost and say so in the release notes.+- **(b)** First build child re-supply: read the values from the login-shell probe+ `src/core/exec-path.ts` already runs, `launchctl getenv`, the Windows registry, or+ `/proc/self/environ`, and pass them into the pty and session-host env.+- **(c)** Drop only the nodeOptions fuse (and accept the bypass).++The decision is enes's. Device check 10 below gathers the evidence.++## Flip and undo runbook (owner steps, plan Part 6)++- **O0 — before the privacy copy ships:** decide the telemetry default. The app ships+ `telemetryEnabled: true`; the site says off by default. Either the site changes or the app default+ changes (a separate PR). Release A's count follows the toggle, so this also decides how many+ installs get a snapshot.+- **O1 — before the client half merges:** the key pair (above).+- **O2 — Release A:** merge and deploy the server snapshot recording, merge the privacy copy, then+ release the desktop report. Let it run 1–2 weeks; read the admin card's p50 / p90 / p99 and set+ CAP ≈ p99 (and revisit FREE).+- **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. Every later release before the flip bumps `PROJECT_LIMIT_DEADLINE_MS` (the release+ workflow refuses otherwise).+- **O4 — flip day:**+ 1. In the release that precedes or accompanies the flip, set `PROJECT_LIMIT_DEADLINE_FROZEN = true`+ and the deadline to the flip date.+ 2. Set the cutoff in the admin console's Project limit card (an ISO instant with an offset).+ 3. Same day on nodeterm-web: add a **Plans** section (the site has no pricing page today) —+ Core: `Up to 5 open projects (existing installs keep their current count)`; Pro `$10/mo`:+ unlimited open projects, live links, 3 team seats, larger dictation models, nodeterm mobile+ Pro — and the changelog line `Free plan: 5 open projects; existing installs keep their current+ count.` No banner, email or in-app notice.+ 4. Privacy page additions, deferred to the flip on purpose:+ - (a) The stored open-project maximum is **also used to compute an existing installation's+ free-project allowance** — added before any allowance is computed.+ - (b) The maximum used is the one **reported before the cutoff**.+ - (c) The machine hash (spec §6): when an install reaches the free-project limit and asks for+ its allowance, nodeterm sends a one-way, salted hash of the computer's hardware id (macOS+ `IOPlatformUUID`, Linux `/etc/machine-id`, Windows `MachineGuid`) with its anonymous install+ id, so the allowance stays with one computer. The raw id never leaves the machine; installs+ that never reach the limit never send it.+ - (d) Deleting the per-installation check record also deletes the basis for a grandfathered+ allowance.+ - The DO_NOT_TRACK consent: under DO_NOT_TRACK nothing license-related is sent until the user+ allows it in the limit dialog or Settings → Privacy; that consent covers license and+ allowance checks only, never telemetry or the check feed, and can be revoked there.+- **Undo:** clear the cutoff. Clients turn the limit off on their next successful check; DO_NOT_TRACK+ clients (no check feed) on their next claim (`not_active`). Nothing was ever closed, so there is+ nothing to restore. To re-flip at a new cutoff, **bump the epoch in the same save** (the admin+ card's "Bump epoch" box), so allowances issued under the old cutoff are recomputed.++## Accepted gaps (§13, and what the build added)++1. Builds released before Release B stay unlimited forever.+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.+4. A patched build (easy on Linux — Electron has no asar integrity there — re-signing needed on+ macOS/Windows). After the license change (#1317) this is a license breach for production use,+ not something the code prevents.+5. Both legacy counts are client-reported and only capped at CAP. Before the cutoff anyone who reads+ the public Release A change can mint a legacy device id with a CAP-sized allowance by calling+ `/v1/check` by hand. This ends at the cutoff; the date is not announced in advance.+6. Rebinding lets one legacy `device-id` be shared slowly: each machine that rebinds keeps the token+ it already stored, so N machines take N × 30 days.+7. A cancelled Pro user who blocks the API keeps unlimited opens for at most 30 days.+8. A claim sent while the OS machine-id read failed twice binds the server row to the **hostname**+ hash. The next normal launch then reads the OS id, the token stops matching, and a re-claim may+ hit `machine_mismatch` inside the 30-day rebind window (the user sits at FREE until then).+9. An epoch bump resets the rebind clock: one extra immediate machine move per bump.+10. A key-paste Pro install whose key the server refuses keeps limit-Pro for the token TTL + 30 days+ (the key-paste refresh never sees a 2xx `active:false`).++Not gaps: blocking api.nodeterm.dev leaves an install at FREE after the deadline; resetting+`device-id` makes it a new install at FREE.++Rough edges a user can notice (behaviour, not bypasses):++- A second open pressed while a claim or the dialog is in flight is dropped (press again).+- When the dialog was raised by an agent's refusal, a Close makes room but nothing opens — the agent+ was already told no; ask it again.+- At the limit, an agent's headless start of a node in a closed project runs without bringing the+ project's tab back.++## Device checklist++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".++**Run 1 — packaged builds, no server needed**++1. macOS arm64 and x64, signed: the app launches; `npx @electron/fuses read --app <path>` shows+ `EnableEmbeddedAsarIntegrityValidation` and `OnlyLoadAppFromAsar` enabled, RunAsNode enabled,+ NodeOptions and NodeCliInspect disabled; `Info.plist` carries `ElectronAsarIntegrity`.+ Terminals open (node-pty loads from `app.asar.unpacked`), dictation loads a model (smart-whisper),+ a project icon upload works (sharp).+2. macOS and Windows: a deliberately modified `app.asar` refuses to start; `NODE_OPTIONS=--require+ x.js` and `--inspect` are ignored by the GUI app (measured on Linux only).+3. Windows (NSIS build): asar integrity on; the session host starts — from the staged runtime+ (`nodeterm-sessionhost-v2.exe`, whose runtime smoke exits 42) and from the hard-link fallback+ `nodeterm-session-host.exe` — and a terminal survives an app restart (RunAsNode).+4. macOS and Windows: the codex relay daemon starts and answers `/ping` (RunAsNode running a script+ inside `app.asar` with integrity validation on).+5. Linux: the executable is `dist/linux-unpacked/node-terminal` (not `nodeterm`); the fuse read+ matches item 1 (asar integrity is not enforced on Linux).+6. macOS: auto-update (Squirrel.Mac) installs a fused, signed update.+7. Capture real `ioreg -rd1 -c IOPlatformExpertDevice` (macOS) and+ `reg query HKLM\SOFTWARE\Microsoft\Cryptography /v MachineGuid` (Windows) output and confirm+ `parseIoregUuid` / `parseRegMachineGuid` read them — paste the captures into+ `src/core/machine-id.test.ts` in place of the samples, which are written from documented formats,+ not captured.++**Run 2 — staging server, limit still off (cutoff unset)**++8. Dormant: 9 projects open, the 10th opens with no request in the server log but the usual+ `/v1/check` (no claim).+9. DO_NOT_TRACK after the deadline (a test build with a past `PROJECT_LIMIT_DEADLINE_MS`, never a+ release): with no consent the limit moment shows "Connection needed"; with consent a claim runs,+ answers `not_active`, and the gate clears.+10. Corporate CA (evidence for the NODE_EXTRA_CA_CERTS decision): with `NODE_EXTRA_CA_CERTS` set via+ `launchctl setenv` (macOS) / a user environment variable (Windows) and the staging server behind+ a CA only that file trusts, record what breaks: license status, a claim, `/v1/check`, and a+ `claude` CLI in a terminal.++**Run 3 — staging server, flipped (cutoff set)**++11. Flip: a new device at 5 open → the 6th open claims → the dialog; Close one → the pending open+ proceeds; Pro checkout from the dialog → it closes and the open proceeds.+12. Legacy device with a snapshot of 12: after one claim it opens up to 12 with the network off.+13. DO_NOT_TRACK=1: the limit moment asks for consent; decline keeps 5; accept claims; the Privacy+ row shows the consent and revoking it works.+14. Machine move: copy userData to a second machine → its first claim rebinds; a third machine is+ told the date the allowance can move.+15. Undo: clear the cutoff → the next check removes the gate; a DO_NOT_TRACK client clears on its+ next claim.diff --git a/scripts/check-project-limit-deadline.mjs b/scripts/check-project-limit-deadline.mjsnew file mode 100644index 000000000..17e7d5dea--- /dev/null+++ b/scripts/check-project-limit-deadline.mjs@@ -0,0 +1,91 @@+#!/usr/bin/env node+// Release guard for the free-tier open-project limit's embedded deadline (docs/project-limit.md).+//+// `PROJECT_LIMIT_DEADLINE_MS` (src/shared/project-limit.ts) is the instant past which a client that+// never heard from the server — DO_NOT_TRACK, NODETERM_TELEMETRY_DISABLED, a blocked host — treats+// the limit as on and asks the server before opening beyond FREE. Until the flip it must be BUMPED+// IN EVERY RELEASE to a date past the planned flip, or those users are gated before anyone else.+// Nobody remembers a checklist item every release, so the release workflow runs this first and+// refuses to build when the deadline is less than 30 days away. At the flip the deadline becomes the+// flip date for good and `PROJECT_LIMIT_DEADLINE_FROZEN = true` switches this guard off.+//+// It reads the SOURCE TEXT, not the compiled constant, so it runs before `npm ci` with node alone.+// That is why the constants must keep their literal forms on one line:+// export const PROJECT_LIMIT_DEADLINE_MS = Date.parse('<ISO instant>')+// export const PROJECT_LIMIT_DEADLINE_FROZEN = true | false+// Anything else is reported as unreadable — never waved through. The test pins these readings to the+// values the app actually compiles.+//+// Usage: node scripts/check-project-limit-deadline.mjs [path/to/project-limit.ts]+import fs from 'node:fs'+import path from 'node:path'+import { fileURLToPath } from 'node:url'++const MIN_LEAD_MS = 30 * 24 * 60 * 60 * 1000+const SOURCE = 'src/shared/project-limit.ts'++const DEADLINE_RE = /^export const PROJECT_LIMIT_DEADLINE_MS = Date\.parse\('([^']*)'\)\s*$/m+const FROZEN_RE = /^export const PROJECT_LIMIT_DEADLINE_FROZEN = (true|false)\s*$/m++/**+ * The deadline and the frozen flag as written in the source, or null when either is missing or not in+ * its literal form (or the ISO string does not parse).+ * @param {string} source+ * @returns {{ deadlineMs: number, frozen: boolean } | null}+ */+export function readDeadline(source) {+ const d = DEADLINE_RE.exec(source)+ const f = FROZEN_RE.exec(source)+ if (!d || !f) return null+ const deadlineMs = Date.parse(d[1])+ if (!Number.isFinite(deadlineMs)) return null+ return { deadlineMs, frozen: f[1] === 'true' }+}++/**+ * Why this source must not be released at `now`, or null when it may. A frozen deadline always may;+ * an unreadable one never does.+ * @param {string} source the text of src/shared/project-limit.ts+ * @param {Date} now+ * @returns {string | null}+ */+export function deadlineProblem(source, now) {+ const read = readDeadline(source)+ if (!read) {+ return (+ `could not read PROJECT_LIMIT_DEADLINE_MS / PROJECT_LIMIT_DEADLINE_FROZEN from ${SOURCE} — keep the ` ++ "literal forms `Date.parse('<ISO instant>')` and `true`/`false`, each on one line (docs/project-limit.md)"+ )+ }+ if (read.frozen) return null+ if (read.deadlineMs < now.getTime() + MIN_LEAD_MS) {+ return (+ `PROJECT_LIMIT_DEADLINE (${new Date(read.deadlineMs).toISOString()}) is less than 30 days away — ` ++ `bump it in ${SOURCE} before releasing (docs/project-limit.md)`+ )+ }+ return null+}++function fail(message) {+ // An annotation on the run summary when it runs in GitHub Actions, a plain line elsewhere.+ console.error(`${process.env.GITHUB_ACTIONS === 'true' ? '::error::' : ''}${message}`)+ process.exit(1)+}++if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ const file =+ process.argv[2] ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', SOURCE)+ let source+ try {+ source = fs.readFileSync(file, 'utf8')+ } catch (err) {+ fail(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`)+ }+ const problem = deadlineProblem(source, new Date())+ if (problem) fail(problem)+ const { deadlineMs, frozen } = readDeadline(source)+ console.log(+ `project-limit deadline ${new Date(deadlineMs).toISOString()}${frozen ? ' (frozen)' : ''}: ok to release`+ )+}diff --git a/scripts/check-project-limit-deadline.test.ts b/scripts/check-project-limit-deadline.test.tsnew file mode 100644index 000000000..ec2c7b6ac--- /dev/null+++ b/scripts/check-project-limit-deadline.test.ts@@ -0,0 +1,133 @@+import { describe, it, expect } from 'vitest'+import { spawnSync } from 'node:child_process'+import fs from 'fs'+import path from 'path'+import { testTmpDir } from '../src/core/test-tmp'+import { PROJECT_LIMIT_DEADLINE_FROZEN, PROJECT_LIMIT_DEADLINE_MS } from '../src/shared/project-limit'+// @ts-expect-error -- plain .mjs repo tooling, deliberately outside the typechecked projects.+import { deadlineProblem, readDeadline } from './check-project-limit-deadline.mjs'++const DAY_MS = 24 * 60 * 60 * 1000+const SCRIPT = path.resolve(__dirname, 'check-project-limit-deadline.mjs')+const REAL_SOURCE = fs.readFileSync(path.resolve(__dirname, '../src/shared/project-limit.ts'), 'utf8')++/** The two lines the guard reads, in the shape src/shared/project-limit.ts writes them, wrapped in+ * the same kind of doc comment (which itself quotes the literal form — it must not be matched). */+function source(iso: string, frozen: boolean): string {+ return [+ '/**',+ " * Keep the literal form `Date.parse('<ISO instant>')` on one line.",+ ' */',+ `export const PROJECT_LIMIT_DEADLINE_MS = Date.parse('${iso}')`,+ '',+ `export const PROJECT_LIMIT_DEADLINE_FROZEN = ${frozen}`,+ ''+ ].join('\n')+}++const NOW = new Date('2026-10-30T12:00:00Z')+const late = (iso: string): string =>+ `PROJECT_LIMIT_DEADLINE (${iso}) is less than 30 days away — bump it in src/shared/project-limit.ts before releasing (docs/project-limit.md)`++describe('deadlineProblem', () => {+ it('passes a deadline far in the future', () => {+ expect(deadlineProblem(source('2027-01-31T00:00:00Z', false), NOW)).toBeNull()+ })++ it('refuses a deadline 10 days away, naming it', () => {+ const iso = new Date(NOW.getTime() + 10 * DAY_MS).toISOString()+ expect(deadlineProblem(source(iso, false), NOW)).toBe(late(iso))+ })++ it('refuses a deadline that has already passed', () => {+ expect(deadlineProblem(source('2026-01-01T00:00:00Z', false), NOW)).toBe(late('2026-01-01T00:00:00.000Z'))+ })++ it('draws the line at exactly 30 days', () => {+ const at = new Date(NOW.getTime() + 30 * DAY_MS).toISOString()+ const justInside = new Date(NOW.getTime() + 30 * DAY_MS - 1).toISOString()+ expect(deadlineProblem(source(at, false), NOW)).toBeNull()+ expect(deadlineProblem(source(justInside, false), NOW)).toBe(late(justInside))+ })++ it('reads the live constants, not a commented-out earlier value', () => {+ const src =+ "// export const PROJECT_LIMIT_DEADLINE_MS = Date.parse('2026-11-01T00:00:00Z')\n" ++ '// export const PROJECT_LIMIT_DEADLINE_FROZEN = true\n' ++ source('2027-01-31T00:00:00Z', false)+ expect(readDeadline(src)).toEqual({ deadlineMs: Date.parse('2027-01-31T00:00:00Z'), frozen: false })+ expect(deadlineProblem(src, NOW)).toBeNull()+ })++ it('passes a frozen deadline, even one in the past (the flip happened; it is the flip date for good)', () => {+ expect(deadlineProblem(source('2026-01-01T00:00:00Z', true), NOW)).toBeNull()+ })++ it.each([+ ['garbage', 'this is not the file you are looking for'],+ ['an empty file', ''],+ ['a deadline that is not a Date.parse literal', source('x', false).replace("Date.parse('x')", '1_800_000_000_000')],+ ['an unparsable ISO literal', source('not-a-date', false)],+ ['no FROZEN constant', source('2027-01-31T00:00:00Z', false).replace(/^export const PROJECT_LIMIT_DEADLINE_FROZEN.*$/m, '')],+ ['a FROZEN value that is not a boolean literal', source('2027-01-31T00:00:00Z', false).replace('= false', '= !0')]+ ])('refuses %s with a message saying it could not read the deadline', (_name, src) => {+ const problem = deadlineProblem(src, NOW)+ expect(problem).toMatch(/^could not read PROJECT_LIMIT_DEADLINE_MS/)+ expect(problem).toContain('src/shared/project-limit.ts')+ expect(problem).toContain('docs/project-limit.md')+ })++ it('refuses a frozen file whose deadline it cannot read (a broken literal is never waved through)', () => {+ expect(deadlineProblem(source('not-a-date', true), NOW)).toMatch(/^could not read/)+ })+})++describe('the real src/shared/project-limit.ts', () => {+ // Pins the guard to the compiled constants, so a change of literal form fails on the PR that makes+ // it, not on release day.+ it('reads exactly the values the app compiles', () => {+ expect(readDeadline(REAL_SOURCE)).toEqual({+ deadlineMs: PROJECT_LIMIT_DEADLINE_MS,+ frozen: PROJECT_LIMIT_DEADLINE_FROZEN+ })+ })+})++describe('the CLI the release workflow runs', () => {+ function run(src: string): { status: number | null; stderr: string; stdout: string } {+ const dir = testTmpDir('nt-limit-deadline-')+ const file = path.join(dir, 'project-limit.ts')+ fs.writeFileSync(file, src)+ const r = spawnSync(process.execPath, [SCRIPT, file], { encoding: 'utf8' })+ return { status: r.status, stderr: r.stderr, stdout: r.stdout }+ }++ it('exits 1 with the message when the deadline is too close', () => {+ const iso = new Date(Date.now() + 10 * DAY_MS).toISOString()+ const r = run(source(iso, false))+ expect(r.status).toBe(1)+ expect(r.stderr).toContain(late(iso))+ })++ it('exits 1 when it cannot read the file it was pointed at', () => {+ const r = spawnSync(process.execPath, [SCRIPT, path.join(testTmpDir('nt-limit-deadline-'), 'missing.ts')], {+ encoding: 'utf8'+ })+ expect(r.status).toBe(1)+ expect(r.stderr).toContain('missing.ts')+ })++ it('exits 0 for a far deadline and for a frozen one', () => {+ expect(run(source(new Date(Date.now() + 90 * DAY_MS).toISOString(), false)).status).toBe(0)+ expect(run(source('2026-01-01T00:00:00Z', true)).status).toBe(0)+ })++ it('is the workflow step, after checkout and before npm ci, in the first build job', () => {+ const wf = fs.readFileSync(path.resolve(__dirname, '../.github/workflows/release.yml'), 'utf8')+ const job = wf.slice(wf.indexOf('release-mac:'), wf.indexOf('release-linux:'))+ const guard = job.indexOf('run: node scripts/check-project-limit-deadline.mjs')+ expect(guard, 'release-mac runs the deadline guard').toBeGreaterThan(-1)+ expect(guard).toBeGreaterThan(job.indexOf('uses: actions/checkout@'))+ expect(guard).toBeLessThan(job.indexOf('run: caffeinate -dims npm ci'))+ })+})