fix(cli): warn when the declared replica count exceeds the licensed node cap

[qq9340100]

Fixes #8504

What was missing

The 2026-08-13 max_nodes ruling (recorded on objectstack-ai/cloud#1275) has three
clauses: refuse the excess, run up to the paid limit, and warn loudly. The gate
learned to express the first two (admitted / refused / capped). The third had no
owner, and os serve is the gate's sole runtime consumer.

Both of the card's asserted causes were still live on origin/main and both were
confirmed independently — either one alone reproduces the silence:

1. Unreachable — serve.ts:1404 called checkMultiNodeAllowed() zero-arg, so
   requested was undefined and a cap-aware gate had nothing to clamp against.
2. Unread — serve.ts:1402 re-declared the return type locally, inside the
   dynamic-import cast, as { allowed: boolean; reason?: string }. The widened shape is
   not inherited implicitly, so refused and capped were invisible even when set.

What this changes

serve passes the resolved replica count into the gate, widens the local mirror, and
emits an advisory on capped:

[cluster] licensed node cap exceeded: the licence admits 3 node(s), but
OS_CLUSTER_REPLICAS declares 5 — 2 beyond the cap.
[cluster] This cap is ADVISORY and is not enforced yet: nothing is refused, and all
5 replicas will still join the cluster.
[cluster] Reduce OS_CLUSTER_REPLICAS to 3, or raise the licensed node limit.

Scope is clause 3 only. Enforcement (clauses 1 and 2) needs an atomic slot claim across
replicas and is #8501's; nothing here refuses anything, and the gate was not changed.

Two decisions, stated rather than assumed

1. The wording is advisory, and that is the substance of the deliverable. While
enforcement is open, nothing is actually refused: the gate is consulted once per process
at boot, every replica computes the same verdict, and none can tell whether it is one of
the admitted ones — so all of them join. A message phrased as "2 replicas refused" would
be false, and would recreate the declared-vs-delivered gap this whole family of cards
exists to close. A test asserts the false phrasings stay absent, not merely that the true
ones are present.

2. OS_CLUSTER_REPLICAS is the input, as a deliberate choice. It is an operator
declared desired count, identical in every replica — not a live membership count, and
no membership count exists at boot. For an advisory message that is exactly right: the
operator is being told about the configuration they wrote. It is explicitly not
sufficient input for enforcement, which is why enforcement is a separate mechanism rather
than a stricter reading of this value.

Number(undefined) is NaN, which the gate normalizes to "not declared" — normalization
lives at the seam by design, so there is deliberately no ?? 0 or pre-parse at the call
site.

An outright allowed: false denial is untouched and is deliberately not reported as a
cap: the producer keeps capped false for it precisely so the unlicensed case cannot be
conflated with the licensed-overflow one, and the call site already reports it as a
single-node downgrade.

Docs

content/docs/kernel/cluster.mdx documented only the deny/downgrade path — the gap the
card itself names ("an operator has no other place to learn whether a node cap binds").
It now describes the partial-cap verdict as what it is: a different verdict from a
denial, not a downgrade, and advisory today, with a callout stating plainly that
nothing is refused, that every declared replica joins, and why acting on the verdict
locally is not possible yet. It also records that the input is the declared count rather
than live membership.

Doc verdicts, one line each — see the report comment on #8504 for the full accounting of
the docs-drift-check list. The three content/docs/releases/** pages are release-owned
and were not touched.

The pin — why this drifted silently, and what stops it next time

The local cast is the only place the two shapes meet, so the producer's widening
propagated nowhere while every package built, every test passed and type-check stayed
green. A source-level pin now derives both sides from the file that owns each — the
gate's own ResolvedMultiNodeVerdict declaration and serve's mirror — rather than
checking either against a list written out in the test, which would only relocate the
divergence into the test file. It also pins that the call passes a count at all.

That pin only works if a cluster-only change re-runs cli's tests, so the read is declared
in CROSS_PACKAGE_TEST_INPUTS and in turbo.json's @objectstack/cli#test inputs.
Getting that right took two corrections, both found by ablating the declaration and
watching the gate rather than by trusting its green:

• a resolve() nested straight into readFileSync produces no binding, so the scanner
  never saw the read and removing the declaration left the gate green. The read is now
  a repo-relative literal off an escaping REPO_ROOT binding — the shape the scanner
  follows — and ablation fails loudly, naming the file.
• the scanner collects path literals out of comments too, so naming its own script by
  repo-relative path demanded a glob for a file this test never reads.

The detector gap itself is filed as #8698 (observation-class, unassigned).

Verification

All at 913680342 — the final commit, re-run after the docs commit.

what	result
pnpm --filter @objectstack/cli test	PASS — 122 files, 1329 tests
pnpm --filter @objectstack/cli typecheck	PASS
check:type-check-debt (--re-measure)	PASS — 33 ledger entries, none above its recorded number
check:type-check-coverage	PASS
check:cross-package-test-inputs	PASS
check:docs-audit-scope	PASS
check:role-word	PASS
check:nul-bytes	PASS
check:query-options-erasure	PASS
check:changeset-gate-self-tests, check:objectui-changeset + the three changeset scans	PASS

Gate families were re-derived with scripts/pm/dispatch-gates.mjs against the actual
changed paths rather than predicted, and re-derived again after the docs commit — which
is what surfaced check:docs-audit-scope and check:role-word. The earlier derivation
surfaced check:cross-package-test-inputs, the gate that mattered most here.
(The @objectstack/lint TEST_DEBT surplus the ratchet reports is pre-existing, untouched,
and not this PR's to lower.)

Reverse verification (direction predicted before running, observed as predicted):

• widened the producer's interface with a probe field ⇒ exactly the shape pin red, with
  its guidance message; restored byte-identically.
• restored serve.ts to its origin/main state ⇒ all 13 tests red across both files;
  restored and proved identity by blob hash against HEAD.
• removed the cross-package declaration ⇒ the gate red, naming this test and the producer
  path.

These ablations read .ts source, not dist, by design — so there is no artifact to
rebuild and no stale-dist false green.

main was merged (clean, no generated-artifact obligation) before the final runs.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 14, 2026 2:50pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli.

17 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/skills-reference.mdx (via packages/cli)
• content/docs/api/client-sdk.mdx (via @objectstack/cli)
• content/docs/api/data-flow.mdx (via @objectstack/cli)
• content/docs/api/environment-routing.mdx (via @objectstack/cli)
• content/docs/api/error-catalog.mdx (via @objectstack/cli)
• content/docs/automation/hook-bodies.mdx (via packages/cli)
• content/docs/deployment/backup-restore.mdx (via @objectstack/cli)
• content/docs/deployment/cli.mdx (via @objectstack/cli)
• content/docs/deployment/self-hosting.mdx (via @objectstack/cli)
• content/docs/getting-started/your-first-project.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/data-service.mdx (via @objectstack/cli)
• content/docs/kernel/runtime-services/index.mdx (via packages/cli)
• content/docs/permissions/authentication.mdx (via @objectstack/cli)
• content/docs/plugins/index.mdx (via @objectstack/cli)
• content/docs/plugins/packages.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/plugin-spec.mdx (via @objectstack/cli)
• content/docs/protocol/kernel/realtime-protocol.mdx (via @objectstack/cli)

⛔ 3 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx (via @objectstack/cli)
• content/docs/releases/v16.mdx (via @objectstack/cli)
• content/docs/releases/v17.mdx (via @objectstack/cli)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.