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

* fix(cli): warn when declared replicas exceed the licensed node cap (#8504)

The 2026-08-13 max_nodes ruling's third clause — warn loudly on a licensed
overflow — had no owner. `os serve` is the gate's sole runtime consumer and
called `checkMultiNodeAllowed()` zero-arg, typing the result with a local
`{ allowed, reason }` cast, so the partial-cap verdict was both unreachable
(no `requested` to clamp against) and unread.

serve now passes the operator-declared OS_CLUSTER_REPLICAS and emits an
advisory on `capped`. The wording is advisory on purpose: enforcement is a
separate mechanism, so nothing is refused today and every declared replica
still joins — claiming otherwise would be the same declared-vs-delivered gap
this warning closes.

A source-level pin derives serve's local verdict mirror from the gate's own
declaration, so the next producer widening is a decision rather than a silent
divergence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MX1qcBzfwZb5wkRrJTNbhH

* test(cli): declare the multi-node gate as a cross-package test input (#8504)

The shape pin reads the gate's own declaration from
packages/services/service-cluster/src. Undeclared, that read is invisible to
both layers that decide whether cli's tests run: turbo's affected-subset
filter and the test task's input hashing. A cluster-only change would then
skip cli's suite entirely and the pin would stay green through exactly the
drift it exists to catch.

Declared in CROSS_PACKAGE_TEST_INPUTS + turbo.json, and the read is spelled
as resolve() off a dirname(fileURLToPath(import.meta.url)) seed — the shape
check-cross-package-test-inputs.mjs can follow. The new URL() form it had
reads identically at runtime but is invisible to that gate, so the gate's
green said nothing about this file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MX1qcBzfwZb5wkRrJTNbhH

* test(cli): address the gate's read shape, not just its declaration (#8504)

Two corrections proved by ablating the declaration and watching the gate:

- a resolve() nested straight into readFileSync produces no binding, so
  escapingBindings never saw the read and removing the declaration left the
  gate green. Bound REPO_ROOT and addressed the producer by repo-relative
  literal — the shape the scanner follows. Ablation now fails loudly, naming
  this file.
- the gate 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. Named without the path instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MX1qcBzfwZb5wkRrJTNbhH

* docs(kernel): document the advisory node cap in cluster semantics (#8504)

cluster.mdx described only the deny/downgrade path, so an operator had no
place to learn whether a node cap binds — the gap #8504 names. Documents the
partial-cap verdict as what it is: a different verdict from a denial, not a
downgrade, and advisory today — nothing is refused and every declared replica
joins. Also records that the input is the operator-declared OS_CLUSTER_REPLICAS
rather than live membership, and why that is insufficient for enforcement.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MX1qcBzfwZb5wkRrJTNbhH

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: qq9340100

.changeset/serve-multi-node-cap-advisory.md

@@ -0,0 +1,33 @@
+---
+'@objectstack/cli': patch
+---
+
+`serve`: warn when the declared replica count exceeds the licensed node cap (#8504)
+
+The 2026-08-13 `max_nodes` ruling requires a licensed overflow to refuse the excess,
+run up to the paid limit, and **warn loudly**. The gate learned to express the first
+two — `admitted` / `refused` / `capped` — but the only program that consults it, `os
+serve`, called it zero-arg and typed the result with a hand-written
+`{ allowed, reason }` cast. So the partial-cap verdict was unreachable *and* unread:
+the gate could say "3 admitted, 2 refused" and nothing rendered it.
+
+`serve` now passes the operator-declared `OS_CLUSTER_REPLICAS` into the gate 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.
+```
+
+⚠️ The wording is deliberately advisory. Enforcement needs an atomic slot claim
+across replicas and is tracked separately; until it lands **nothing is actually
+refused** — every replica computes the same verdict at boot and none can tell whether
+it is one of the admitted ones, so all of them join. A message claiming "2 replicas
+refused" would be false in exactly the declared-vs-delivered way this warning exists
+to close.
+
+An outright `allowed: false` denial is untouched: it keeps reporting as a
+single-node downgrade, and is deliberately not reported as a cap.

content/docs/kernel/cluster.mdx

@@ -532,6 +532,38 @@ string. A distribution may register a multi-node gate; when it denies,
 `os serve` logs a warning and downgrades to the single-node in-memory cluster
 rather than failing.
 
+A gate may instead admit **fewer** nodes than the deployment declares — a
+licensed node-cap overflow. That is a different verdict from a denial and is
+deliberately *not* a downgrade: the cluster is entitled to run, it simply asked
+for more nodes than it paid for. `os serve` passes the declared
+`OS_CLUSTER_REPLICAS` to the gate and, when the declaration exceeds what the
+gate admits, prints an advisory naming both counts:
+
+```
+[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.
+```
+
+<Callout type="warn">
+  **The cap is advisory today — it does not bind.** Nothing is refused, and every
+  declared replica joins. The gate is consulted once per process at boot, so each
+  replica computes the *same* verdict and none can tell whether it is one of the
+  admitted ones: acting on it locally would mean either "all join" (what happens)
+  or "all refuse" (a whole-cluster outage, which is worse than the overflow).
+  Making it bind needs an atomic slot claim across replicas — each booting replica
+  claims a seat, the excess downgrades itself, and seats are released on shutdown
+  or TTL expiry — which does not exist yet. Treat the warning as a prompt to fix
+  the configuration or the licence, not as evidence that the limit is enforced.
+</Callout>
+
+Note this reads the operator-**declared** count, not live membership: no
+membership view exists at boot. It is the right input for telling an operator
+about the configuration they wrote, and is deliberately not sufficient for
+enforcement.
+
 Every cluster primitive selects its implementation from `cluster.driver`.
 When the field is absent, `Runtime` auto-registers the in-memory, single-node
 driver (pass `cluster: false` to skip registration entirely). No production

packages/cli/src/commands/serve-multi-node-cap-advisory.pin.test.ts

@@ -0,0 +1,139 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * THE PIN: `os serve` asks the multi-node gate a counted question, and its local
+ * copy of the gate's verdict shape still matches the gate's own.
+ *
+ * The defect this guards is authoring-time and invisible to any behavioural
+ * test. `serve.ts` reaches `@objectstack/service-cluster` through a dynamic,
+ * non-literal specifier — deliberately, so the CLI carries no static dependency
+ * on a package that ships with a distribution — and types the result with a
+ * hand-written cast. That cast is the ONLY place the two shapes meet, so when
+ * the gate widened to express a licensed node cap (`admitted` / `refused` /
+ * `capped`), nothing propagated to the consumer: the cast still said
+ * `{ allowed, reason }` and the call was still zero-arg. The gate could express
+ * "3 admitted, 2 refused" and the only program that consults it could neither
+ * ask the question nor read the answer — with every package building, every
+ * test passing and every type-check green.
+ *
+ * Both halves are pinned because either one alone reproduces the silence:
+ *
+ *   1. a zero-arg call leaves `requested` undefined, so a cap-aware gate has
+ *      nothing to clamp against and the partial-cap verdict is *unreachable*;
+ *   2. a narrow local cast means the fields are *unreadable* even when set.
+ *
+ * The shape assertion derives BOTH sides from the file that owns each, rather
+ * than checking either against a list written out here — a hard-coded expected
+ * list would just relocate the divergence into this file, where it would be
+ * equally silent. So the producer widening again turns this red, which makes
+ * the next widening a decision (does `serve` need the new field?) instead of a
+ * silent divergence.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** `packages/cli/src/commands` → four levels up. */
+const REPO_ROOT = resolve(HERE, '../../../..');
+
+/** `packages/cli/src/commands/serve.ts` — the consumer. */
+const SERVE_SOURCE = readFileSync(resolve(HERE, 'serve.ts'), 'utf8');
+
+/**
+ * The producer, read from source rather than imported: the CLI has no
+ * dependency on this package (that is the whole reason the cast exists), and
+ * reading `src` also means the pin does not depend on anything being built.
+ *
+ * ⚠️ Addressed as a repo-relative literal off an escaping `REPO_ROOT` binding
+ * on purpose — that is the shape the repo's `check:cross-package-test-inputs`
+ * gate can follow. (Its script is named without a repo-relative path here: that
+ * gate collects path literals out of a test's source, comments included, and
+ * would then require a glob for a file this test never reads.) Spellings it cannot follow (a `new URL('…', import.meta.url)`
+ * seed, or a `resolve()` nested straight into the `readFileSync` call) read
+ * identically at runtime but produce no binding and therefore no flag, which
+ * would leave this read **undeclared**: `@objectstack/cli` would then be absent
+ * from `turbo ls --affected` for a cluster-only change and its `test` cache
+ * would not hash this file, so the pin below would sit green through exactly
+ * the drift it exists to catch. The declaration it needs lives in that script's
+ * `CROSS_PACKAGE_TEST_INPUTS` and in `turbo.json`'s `@objectstack/cli#test`
+ * inputs; removing either turns this file's own gate red.
+ */
+const GATE_SOURCE = readFileSync(
+  join(REPO_ROOT, 'packages/services/service-cluster/src/multi-node-gate.ts'),
+  'utf8',
+);
+
+/**
+ * The property names of an `export interface`, each suffixed with `?` when
+ * optional — optionality is part of the contract, so a field that quietly
+ * becomes required must not read as agreement.
+ *
+ * Brace-matched rather than line-counted, and comment-stripped before the
+ * property scan so TSDoc prose cannot be mistaken for a field. (A property
+ * whose type is an inline object literal would over-collect its nested keys;
+ * neither interface has one, and one appearing is itself worth a look.)
+ */
+function interfaceFields(source: string, name: string): string[] {
+  const declaration = `export interface ${name} {`;
+  const start = source.indexOf(declaration);
+  expect(start, `${name} not found — did the declaration move or get renamed?`).toBeGreaterThan(-1);
+
+  let depth = 1;
+  let i = start + declaration.length;
+  for (; i < source.length && depth > 0; i++) {
+    if (source[i] === '{') depth++;
+    else if (source[i] === '}') depth--;
+  }
+  const body = source
+    .slice(start + declaration.length, i - 1)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '');
+
+  return [...body.matchAll(/^\s*(\w+)(\??):/gm)].map((m) => `${m[1]}${m[2]}`).sort();
+}
+
+describe('os serve ↔ multi-node gate', () => {
+  it('calls the gate WITH a requested node count', () => {
+    // The exact regression: `checkMultiNodeAllowed()`. Passing nothing makes the
+    // licensed-overflow verdict unreachable rather than merely unread.
+    expect(SERVE_SOURCE).not.toMatch(/checkMultiNodeAllowed\(\s*\)/);
+    expect(SERVE_SOURCE).toMatch(/checkMultiNodeAllowed\(\s*[^)\s]/);
+  });
+
+  it('passes the operator-declared replica count', () => {
+    // A stated decision, not an accident: `OS_CLUSTER_REPLICAS` is a *declared*
+    // desired count, identical in every replica, not a live membership count —
+    // which is right for an advisory message about the operator's own
+    // configuration, and is NOT sufficient for enforcement.
+    expect(SERVE_SOURCE).toMatch(/checkMultiNodeAllowed\(\s*Number\(process\.env\.OS_CLUSTER_REPLICAS\)\s*\)/);
+  });
+
+  it('types the dynamic import with the mirrored verdict, not an inline literal', () => {
+    expect(SERVE_SOURCE).toMatch(
+      /checkMultiNodeAllowed:\s*\(requested\?:\s*number\)\s*=>\s*MultiNodeGateVerdict/,
+    );
+  });
+
+  it("serve's local verdict mirror matches the gate's own resolved verdict", () => {
+    const producer = interfaceFields(GATE_SOURCE, 'ResolvedMultiNodeVerdict');
+    const consumer = interfaceFields(SERVE_SOURCE, 'MultiNodeGateVerdict');
+
+    // Guard the extractor itself: two empty lists would agree vacuously and pin
+    // nothing at all.
+    expect(producer).toContain('capped');
+    expect(producer).toContain('refused');
+    expect(producer.length).toBeGreaterThan(3);
+
+    expect(
+      consumer,
+      'packages/services/service-cluster/src/multi-node-gate.ts changed its resolved verdict shape. '
+      + "serve.ts mirrors it by hand (no static dependency), so update `MultiNodeGateVerdict` in "
+      + 'packages/cli/src/commands/serve.ts to match — and decide whether the operator warning '
+      + 'should now read the new field.',
+    ).toEqual(producer);
+  });
+});

packages/cli/src/commands/serve-multi-node-cap-advisory.test.ts

@@ -0,0 +1,117 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The operator-facing half of the 2026-08-13 `max_nodes` ruling (cloud#1275).
+ *
+ * The ruling has three clauses — refuse the excess, run up to the paid limit,
+ * warn loudly. The first two need an atomic slot claim across replicas and are
+ * tracked as their own mechanism. The third needs nothing but the verdict the
+ * gate already returns, and had no owner: `os serve` is the sole runtime
+ * consumer of that gate, and it neither asked for a count nor rendered one.
+ *
+ * ⚠️ These assertions are about **wording**, and that is deliberate. 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
+ * claiming "2 replicas refused" would be false in exactly the
+ * declared-vs-delivered way this warning exists to close. The tests below pin
+ * the honest shape: the cap is advisory, and the excess replicas still join.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatMultiNodeCapAdvisory, type MultiNodeGateVerdict } from './serve.js';
+
+/**
+ * The four verdicts the producer can hand this consumer, spelled the way
+ * `checkMultiNodeAllowed` builds them (`multi-node-gate.ts`). The pin test
+ * beside this one is what keeps that claim true; here they are fixtures.
+ */
+const VERDICTS = {
+  /** No gate registered, or an allowing gate that declared no cap. */
+  uncapped: { allowed: true, refused: 0, capped: false },
+  /** A cap exists and the declared topology fits inside it. */
+  withinCap: { allowed: true, admitted: 3, refused: 0, capped: false },
+  /** The licensed-overflow case: 5 declared, 3 paid for. */
+  overflow: { allowed: true, admitted: 3, refused: 2, capped: true },
+  /** Unlicensed: the whole cluster is denied. `capped` stays false by design. */
+  denied: { allowed: false, reason: 'no clustering entitlement', admitted: 0, refused: 5, capped: false },
+} satisfies Record<string, MultiNodeGateVerdict>;
+
+describe('formatMultiNodeCapAdvisory', () => {
+  it('says nothing when no cap is configured', () => {
+    expect(formatMultiNodeCapAdvisory(VERDICTS.uncapped)).toBeNull();
+  });
+
+  it('says nothing when a cap is configured and the declared topology fits', () => {
+    expect(formatMultiNodeCapAdvisory(VERDICTS.withinCap)).toBeNull();
+  });
+
+  it('warns on a licensed overflow, naming both numbers', () => {
+    expect(formatMultiNodeCapAdvisory(VERDICTS.overflow)).toBe(
+      '[cluster] licensed node cap exceeded: the licence admits 3 node(s), '
+      + 'but OS_CLUSTER_REPLICAS declares 5 — 2 beyond the cap.\n'
+      + '[cluster] This cap is ADVISORY and is not enforced yet: nothing is refused, '
+      + 'and all 5 replicas will still join the cluster.\n'
+      + '[cluster] Reduce OS_CLUSTER_REPLICAS to 3, or raise the licensed node limit.',
+    );
+  });
+
+  it('⚠️ never claims replicas were refused — nothing is refused today', () => {
+    const text = formatMultiNodeCapAdvisory(VERDICTS.overflow) ?? '';
+
+    // The false sentences, in the shapes they would plausibly be written.
+    expect(text).not.toMatch(/\d+\s+(replicas?\s+)?(were\s+|was\s+|are\s+)?refused/i);
+    expect(text).not.toMatch(/refus(ed|ing)\s+\d+/i);
+    expect(text).not.toMatch(/(rejected|denied|dropped|will not join|won't join)/i);
+
+    // ...and the true ones it must carry instead.
+    expect(text).toMatch(/advisory/i);
+    expect(text).toMatch(/not enforced/i);
+    expect(text).toMatch(/nothing is refused/i);
+    expect(text).toMatch(/still join/i);
+  });
+
+  it('names the declared count, the admitted count and the remedy', () => {
+    const text = formatMultiNodeCapAdvisory(VERDICTS.overflow) ?? '';
+    expect(text).toContain('admits 3');
+    expect(text).toContain('declares 5');
+    expect(text).toContain('2 beyond the cap');
+    expect(text).toContain('OS_CLUSTER_REPLICAS');
+    expect(text).toContain('Reduce OS_CLUSTER_REPLICAS to 3');
+  });
+
+  it('stays silent on an outright denial — that one is a downgrade, not a cap', () => {
+    // `capped: false` on a denial is the producer's deliberate choice so the
+    // unlicensed case cannot be conflated with the licensed-overflow one. The
+    // call site already prints its own downgrade warning; a second message here
+    // would report one event twice, and would call a full denial a partial cap.
+    expect(formatMultiNodeCapAdvisory(VERDICTS.denied)).toBeNull();
+  });
+
+  it('surfaces the gate reason when the cap carries one', () => {
+    const text = formatMultiNodeCapAdvisory({
+      allowed: true,
+      reason: 'plan: team (3 nodes)',
+      admitted: 3,
+      refused: 2,
+      capped: true,
+    });
+    expect(text).toContain('(plan: team (3 nodes))');
+  });
+
+  it('scales with the numbers rather than hard-coding the 3/5 case', () => {
+    const text = formatMultiNodeCapAdvisory({ allowed: true, admitted: 10, refused: 7, capped: true }) ?? '';
+    expect(text).toContain('admits 10');
+    expect(text).toContain('declares 17');
+    expect(text).toContain('7 beyond the cap');
+  });
+
+  it('prints no number it was not given: a countless `capped` verdict stays silent', () => {
+    // Unreachable from the shipped producer (`capped: true` always arrives with
+    // a numeric `admitted`), so this pins the choice rather than a behaviour:
+    // faced with a stale or foreign build, silence beats a warning with an
+    // invented count in it.
+    expect(formatMultiNodeCapAdvisory({ allowed: true, refused: 2, capped: true })).toBeNull();
+    expect(formatMultiNodeCapAdvisory({ allowed: true, admitted: 3, refused: 0, capped: true })).toBeNull();
+  });
+});