@bongos/core 1.19.764 → 1.19.766

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.764",
-  "core_contract": "1.19.764",
-  "source_commit": "7725fd4548c86b08962e0606e321fbf24a69a598",
+  "core_version": "1.19.766",
+  "core_contract": "1.19.766",
+  "source_commit": "02a01e26d1d999916c8c67e1e02b06d0db40b694",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T05:25:55.970Z",
+  "built_at": "2026-09-16T13:48:32.669Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2118,
+    "functional_verbatim": 2122,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2626,
-  "tree_sha256": "60cb64cd38bd994befb910ab1e86bffe5a5cc55c50a4bc9ca346c94bb67be1ec",
+  "file_count": 2630,
+  "tree_sha256": "56708a327bb43ff2237f2ef0cdd0fac079947882699533e825262e7a16bcf724",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -387,7 +387,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "83e3ccb8b00fff525ff5ca9a9c209ec39fc5abb78274b116b64c7a72d0137664"
+      "sha256": "6b6255f6dbfca5789f7500180c15eb88c01311f2048e327e85ee98d8cf683d9a"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1957,7 +1957,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "1d0af3ffd2aa0db34e9aeb295cf67a34e1c9e490bbacf3bc271ec2b082b34476"
+      "sha256": "3cdb8968261fe761545cb415ac3e1a0de27dfc747dbb6f5fbc3c86fba8f0261e"
     },
     {
       "path": "docs/architecture.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "22d609769231a31e56e7e03b27a67b14a70934edc95abaa04de3a4a979e9df83"
+      "sha256": "10fb4078df266a5663d8079411fdf7698adb1aa8e20a19ca63ff722e1ecb8134"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6174,6 +6174,11 @@
       "mode": "0000644",
       "sha256": "7cb9dac9cb87b679e1ae50e4112b3a7928a38ebb9902c8947a74d17bec4d9009"
     },
+    {
+      "path": "modules/provisioning/capacity.js",
+      "mode": "0000644",
+      "sha256": "1a2b3bd97a2e0c0068c6200a71dabb692e90723ee1ff63a56775f2b91e1cb208"
+    },
     {
       "path": "modules/provisioning/catalog-bridge.js",
       "mode": "0000644",
@@ -6312,7 +6317,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "a3812af0cc12dfafff47c1b9b03edea6ef61f1f4728acead1628d0b1a1669432"
+      "sha256": "3c8359b8f624fb9521a704bb7202330eae9cfbc8a722d6c9adee207dba6d9dd0"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7572,12 +7577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7a4d2aabf54b2b21ee005be28c58e4a693a3cace5f8d1f103682aa117e506071"
+      "sha256": "6e4cfa58c41e8fbe29dc94bbe4bd7a4eafedb88034b7d1ba3334d4a0764f5b56"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7cea1f421906224ec2f4b1d218bf8e5c4a8a7149a7d9c46f907caf86ff6839e0"
+      "sha256": "b61349c8315ac531b941ca35f84a7323b2192e0ab7507c4d76e1c592c2a9f2e7"
     },
     {
       "path": "public-docs/index.html",
@@ -8399,10 +8404,15 @@
       "mode": "0000644",
       "sha256": "dbaec451d7e67cfce811287ebb2289582ec47d73b1fbff92125e7991b734c807"
     },
+    {
+      "path": "scripts/gds/provision-capacity.js",
+      "mode": "0000644",
+      "sha256": "a8150a19c8839caf18706bdd5010fda25900e073063e876004bfc16397e96b95"
+    },
     {
       "path": "scripts/gds/provision-config.js",
       "mode": "0000644",
-      "sha256": "48d13ecda786629148713e0bd89f0d020ee47de107fa5a2327d44989783907ac"
+      "sha256": "c870abebd21411e1fec744281130d116f3b9e8f255ddb6823aae4072a420cc15"
     },
     {
       "path": "scripts/gds/provision-net.js",
@@ -8422,12 +8432,12 @@
     {
       "path": "scripts/gds/provision-units.js",
       "mode": "0000644",
-      "sha256": "f6a26c5a6e6cb57fbcef1cff93738d4dc0ce955486535fca7796d72c5a280cad"
+      "sha256": "e299687a54305e45ea57ff0a439f5ff099cb5d51be64bb0a48056c93309a67e3"
     },
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "614aa63d02f3ae97f39e492cb0948a92b40364e25f4780d87546b64c01e5c69c"
+      "sha256": "87a9abe0f4744a0b3a3b5cc2e326ff2adb8cba3e559228cca0798e40feaee8f6"
     },
     {
       "path": "scripts/gds/publish-credential-check.js",
@@ -9227,7 +9237,7 @@
     {
       "path": "src/bongos/pool.js",
       "mode": "0000644",
-      "sha256": "96d41f41c4e93358c66e5101b2fc43d4ff8a1c6301a1fd3ec7020ebff6029c8c"
+      "sha256": "f3fa3e0360c1bd7fb9bdf5756edccb8c5f5cad4d9ef2b89b7f0c6382c5240294"
     },
     {
       "path": "src/bongos/prelaunch-gate.js",
@@ -9387,7 +9397,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "aff2e67bbc496681f2f3862b7e512d44b9459be98b57d72cea820fb4038116eb"
+      "sha256": "9c4c56d73c466a19a699f6c37e439d54d88211a363a869f9d87e3e840f493a2a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11864,6 +11874,11 @@
       "mode": "0000644",
       "sha256": "ff9d438a33a32fecc04caa6e652eeaaded6394438bcec0d508ae7c516fa62333"
     },
+    {
+      "path": "tests/pool_max.mjs",
+      "mode": "0000644",
+      "sha256": "68e5b941a1889ddc44fd548e10bb1fdb33822628b0da392592f747a32f7ccd1a"
+    },
     {
       "path": "tests/post_login_landing.mjs",
       "mode": "0000644",
@@ -12042,7 +12057,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "25fbd2adccf79e921c642f8f57b082f5f19fa01cd981cd5b813dc1070511aadb"
+      "sha256": "245deb7b090f528180dde1457b821a8c8c2bd74a643524f441519859659643e8"
     },
     {
       "path": "tests/provision_restart.mjs",
@@ -12059,6 +12074,11 @@
       "mode": "0000644",
       "sha256": "74d53ae7f3c93883bdc6db5187c904cc6c641267233d70bfef1a25d5b2a4ca05"
     },
+    {
+      "path": "tests/provisioning_capacity.mjs",
+      "mode": "0000644",
+      "sha256": "bcb976ab17508d1af34ea0c775d25765f336f534d79de9442b2fbc6712fa2a28"
+    },
     {
       "path": "tests/provisioning_credential_preflight.mjs",
       "mode": "0000644",

package/clients/bongos-client/index.d.ts

@@ -99,7 +99,7 @@ export interface GetProfilesHandleResponse { account: unknown; cross_project: un
 export interface GetProjectSettingsResponse { rows: unknown }
 export interface GetProjectsFeaturedResponse { projects: unknown; page: PageInfo }
 export interface GetProjectsResponse { projects: unknown }
-export interface GetProvisioningFleetResponse { instances: unknown }
+export interface GetProvisioningFleetResponse { instances: unknown; capacity: unknown }
 export interface GetProvisioningGithubAppStatusResponse { ok: boolean; status: unknown; ready: unknown; terminal: unknown; domain: unknown; instance_status: unknown; app_slug: unknown }
 export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; coreVersion: unknown }
 export interface GetProvisioningInstancesIdInviteSuggestionsResponse { suggested: unknown; seeking: unknown; reason: unknown; unavailable?: unknown }

package/docs/api/openapi.json

@@ -18411,10 +18411,12 @@
       "GetProvisioningFleetResponse": {
         "type": "object",
         "properties": {
-          "instances": {}
+          "instances": {},
+          "capacity": {}
         },
         "required": [
-          "instances"
+          "instances",
+          "capacity"
         ]
       },
       "GetProvisioningGithubAppStatusResponse": {

package/docs/module-api-changelog.md

@@ -2002,5 +2002,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.762 with no explicit bump. run 35056690992. (task 1002620)
   1.19.764 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.763 with no explicit bump. run 35059447999. (task 1002620)
+  1.19.765 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.764 with no explicit bump. run 35102327521. (task 1002620)
+  1.19.766 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.765 with no explicit bump. run 35104246900. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/capacity.js

@@ -0,0 +1,162 @@
+// modules/provisioning/capacity.js — how many projects a shared box can hold, and
+// whether one more fits (ADR 0285, task 1003927).
+//
+// ADR 0285 measured the live control plane and priced a project at its WARM size:
+// ~80 MB (a 70 MB process plus one busy Postgres backend), on top of a fixed base
+// the box pays whatever the project count (~750 MB with the control plane on it,
+// ~630 MB on an overflow box). The ceiling is `floor((usable MiB − fixed) / 80)`,
+// which reproduces the ADR's table from the box's own MemTotal — 15 on today's
+// s-1vcpu-2gb, 39 on an s-2vcpu-4gb control plane, 41 on a 4 GB overflow box — so
+// a resize (task 1003923) raises the ceiling by itself, with no knob to remember.
+//
+// Two walls, asked in order, both honest refusals rather than a silent overcommit:
+//   1. the CEILING, counted against the rows the runner has placed or is placing
+//      on that box (`provisioning` + `active`). Not `error`: those rows hold no
+//      running unit (verified on the live fleet, 2026-09-16), and a re-provision
+//      runs this same check for itself.
+//   2. a live MemAvailable FLOOR, because the ledger cannot see a stray unit or a
+//      project that grew — the rows say how many, the kernel says how much is left.
+//
+// PURE except the two I/O helpers at the bottom (`countPlaced` runs one query on
+// the db it is handed; `readLocalMeminfo` reads this host's /proc/meminfo, for the
+// web tier and the CLI, which run ON the control plane). The runner reads the same
+// file through its box executor instead, so an overflow box is measured where the
+// project will actually run (scripts/gds/provision-capacity.js). No module-api, no
+// express, no pool of its own — this file is the shared arithmetic, not a surface.
+'use strict';
+
+const fs = require('node:fs');
+
+// ADR 0285 §1–§2. PROJECT_MB is the warm unit; FIXED_MB is the box's own overhead
+// by role; DEFAULT_CEILING is the ADR's smallest-tier number, used ONLY when the box
+// cannot be measured (dry-run, a fake executor, an unreadable /proc) — refusing
+// conservatively beats guessing generously. RESIZE_AT is the ADR's "resize at 12 of
+// 15" trigger. The floor is two warm projects plus margin, per the task's brief.
+const PROJECT_MB = 80;
+const FIXED_MB = Object.freeze({ 'control-plane': 750, overflow: 630 });
+const DEFAULT_CEILING = 15;
+const DEFAULT_MEM_FLOOR_MB = 256;
+const RESIZE_AT = 0.8;
+// The states that hold (or are about to hold) a slot on the box.
+const PLACED_STATES = Object.freeze(['provisioning', 'active']);
+
+function numEnv(name, dflt) {
+  const v = process.env[name];
+  if (v == null || v === '') return dflt;
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+// The two knobs, read at call time so a test can set them per case. Both live in
+// the runner's box.env; the web tier's copy (web.env) must match if the override
+// is used — deriving from MemTotal is what makes the two agree with no knob at all.
+function envOverrides() {
+  return { override: numEnv('PROVISION_BOX_CEILING', null), floorMb: numEnv('PROVISION_MEM_FLOOR_MB', DEFAULT_MEM_FLOOR_MB) };
+}
+
+// parseMeminfo — MemTotal / MemAvailable out of /proc/meminfo text, in MiB.
+// Null for a field that is absent, so "unmeasured" stays distinguishable from 0.
+function parseMeminfo(text) {
+  const grab = (key) => {
+    const m = new RegExp(`^${key}:\\s+(\\d+)\\s*kB`, 'm').exec(String(text || ''));
+    return m ? Math.floor(Number(m[1]) / 1024) : null;
+  };
+  return { memTotalMb: grab('MemTotal'), memAvailableMb: grab('MemAvailable') };
+}
+
+// placementBox — WHICH box a shape lands on, and therefore which rows share its
+// ceiling and which fixed base applies. A standalone always runs control-plane-
+// local (task 2074); a co-tenant runs on the remote co-hosting box only when the
+// runner is in remote-exec mode (ADR 0130), else here. A dedicated droplet is its
+// own box and has no shared ceiling → null (no preflight).
+function placementBox(hostingShape, { remoteHost = null } = {}) {
+  if (hostingShape === 'dedicated') return null;
+  if (hostingShape === 'co-tenant' && remoteHost) {
+    return { box: 'overflow', shapes: ['co-tenant'], fixedMb: FIXED_MB.overflow };
+  }
+  return { box: 'control-plane', shapes: remoteHost ? ['standalone'] : ['standalone', 'co-tenant'], fixedMb: FIXED_MB['control-plane'] };
+}
+
+// ceilingFor — the slot count for a box: an explicit override wins, else the ADR
+// 0285 formula over the measured MemTotal, else the conservative default. `source`
+// says which, so every surface can show where its number came from.
+function ceilingFor({ override = null, memTotalMb = null, fixedMb = FIXED_MB['control-plane'] } = {}) {
+  if (Number.isFinite(override) && override > 0) return { ceiling: Math.floor(override), source: 'env' };
+  if (Number.isFinite(memTotalMb) && memTotalMb > fixedMb) {
+    return { ceiling: Math.floor((memTotalMb - fixedMb) / PROJECT_MB), source: 'measured' };
+  }
+  return { ceiling: DEFAULT_CEILING, source: 'default' };
+}
+
+// placementVerdict — may ONE more project be placed? Ceiling first (the ledger's
+// answer), then the live floor (the kernel's). The reason is written for the
+// owner's card, not the journal: what is full, that nothing was placed, and the
+// two ways out. An unmeasured MemAvailable cannot fail the floor — the ceiling is
+// the wall that always applies, and a missing reading is logged by the caller.
+function placementVerdict({ placed, ceiling, memAvailableMb = null, floorMb = DEFAULT_MEM_FLOOR_MB }) {
+  if (placed >= ceiling) {
+    return { ok: false, wall: 'ceiling', reason: `The shared box is full: ${placed} of ${ceiling} project slots are taken (ADR 0285). Nothing was placed. Free a slot by tearing down a project, or resize the box (task 1003923), then request again.` };
+  }
+  if (Number.isFinite(memAvailableMb) && memAvailableMb < floorMb) {
+    return { ok: false, wall: 'memory', reason: `The shared box has only ${memAvailableMb} MB of memory free, under the ${floorMb} MB a new project needs to start safely (${placed} of ${ceiling} slots taken). Nothing was placed. Free memory or a slot, or resize the box (task 1003923), then request again.` };
+  }
+  return { ok: true, wall: null, reason: null };
+}
+
+// capacitySummary — the one shape every reader gets: the fleet API, the runner
+// log, the CLI status. `resize_due` is the ADR's 80% trigger, so the resize is
+// scheduled at 12 of 15 rather than discovered at 15.
+function capacitySummary({ box, placed, ceiling, source, memAvailableMb = null, floorMb = DEFAULT_MEM_FLOOR_MB }) {
+  const verdict = placementVerdict({ placed, ceiling, memAvailableMb, floorMb });
+  return {
+    box, placed, ceiling, source,
+    remaining: Math.max(0, ceiling - placed),
+    resize_at: Math.ceil(ceiling * RESIZE_AT),
+    resize_due: placed >= Math.ceil(ceiling * RESIZE_AT),
+    mem_available_mb: memAvailableMb,
+    mem_floor_mb: floorMb,
+    verdict,
+  };
+}
+
+// countPlaced — rows holding a slot on the box: the given shapes in PLACED_STATES.
+// `excludeId` keeps a row from counting itself when a reconcile re-runs its own
+// provision (it is already 'provisioning' then). Fail-soft on a fake db that
+// answers with no rows.
+async function countPlaced(db, shapes, { excludeId = null } = {}) {
+  const params = [shapes, PLACED_STATES];
+  let where = 'hosting_shape = ANY($1) AND status = ANY($2)';
+  if (excludeId != null) { params.push(excludeId); where += ` AND id <> $${params.length}`; }
+  const { rows } = await db.query(`SELECT count(*)::int AS n FROM provisioning_instances WHERE ${where}`, params);
+  return Number((rows && rows[0] && rows[0].n) || 0);
+}
+
+// readLocalMeminfo — THIS host's /proc/meminfo, for the surfaces that run on the
+// control plane itself. Null (not a throw) where it does not exist, e.g. a dev box
+// that is not Linux — the summary then reads 'default' and says so.
+function readLocalMeminfo() {
+  try { return fs.readFileSync('/proc/meminfo', 'utf8'); } catch { return null; }
+}
+
+// fleetCapacity — the control-plane box's summary for the fleet API and the CLI:
+// its rows against its ceiling, measured from this host. `meminfo` is injectable
+// for tests; `remoteHost` mirrors the runner's PROVISION_REMOTE_HOST so the two
+// count the same shapes (set it in web.env too if co-tenants ever run remotely).
+async function fleetCapacity(db, { meminfo = readLocalMeminfo(), remoteHost = process.env.PROVISION_REMOTE_HOST || null } = {}) {
+  const target = placementBox('standalone', { remoteHost });
+  const { override, floorMb } = envOverrides();
+  const mem = parseMeminfo(meminfo);
+  const { ceiling, source } = ceilingFor({ override, memTotalMb: mem.memTotalMb, fixedMb: target.fixedMb });
+  const placed = await countPlaced(db, target.shapes);
+  return capacitySummary({ box: target.box, placed, ceiling, source, memAvailableMb: mem.memAvailableMb, floorMb });
+}
+
+// The constants a caller needs to reason about a verdict, plus the helpers the
+// runner preflight and the fleet API compose. PROJECT_MB / FIXED_MB / RESIZE_AT
+// and the two env readers stay private: nothing outside asks them separately from
+// the summary they produce, and an export nobody consumes is one more thing to
+// keep true (the paid-shape-gate precedent).
+module.exports = {
+  DEFAULT_CEILING, DEFAULT_MEM_FLOOR_MB, PLACED_STATES,
+  parseMeminfo, placementBox, ceilingFor, placementVerdict, capacitySummary,
+  countPlaced, fleetCapacity,
+};

package/modules/provisioning/routes/provisioning.js

@@ -25,7 +25,7 @@
 //     POST   /provisioning/instances/:id/teardown  — request teardown of one's own
 //     GET    /provisioning/instances/:id/invite-suggestions — who is worth inviting (R28, ADR 0251)
 //   Archon-scoped (requireRank('archon') — the fleet, the /boxes precedent):
-//     GET    /provisioning/fleet                    — the full instance roster
+//     GET    /provisioning/fleet                    — the full instance roster + the box's slot `capacity` (ADR 0285)
 //     GET    /provisioning/fleet/cost-ledger        — per-instance + total cost estimate
 //     POST   /provisioning/instances/:id/force-teardown — tear down ANY instance
 //   public:
@@ -44,8 +44,7 @@
 const crypto = require('node:crypto');
 const express = require('express');
 const api = require('../../../src/module-api');
-const auth = api;
-const { pool, validateOrRespond, parseId } = api;
+const auth = api, { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { onboardPlan, stepsForShape } = require('../onboard-plan');
 const { ALWAYS_ON_CORE, OPTIONAL_MODULES, starterBundleAnswerTable, optionalModules, effectiveModules } = require('../starter-bundles');
@@ -54,6 +53,7 @@ const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 const { requireAuthorityForMeteredShape } = require('../paid-shape-gate');
 const { adoptCredentialFault } = require('../credential-preflight');
 const catalogBridge = require('../catalog-bridge');
+const capacity = require('../capacity');   // the box's slot ceiling (ADR 0285, task 1003927)
 const { callbackPage } = require('./callback-page');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
 const { badProjectDetail, badModuleSelection, badProjectType } = require('./body-validators');
@@ -223,7 +223,7 @@ module.exports = function provisioningRoutes() {
     try {
       const status = req.query.status || undefined;
       const rows = await provisioning.listAllInstances(pool, { status });
-      res.json({ instances: rows.map(fleetInstance) });
+      res.json({ instances: rows.map(fleetInstance), capacity: await capacity.fleetCapacity(pool).catch(() => null) });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/fleet', err);
       res.fail('fleet_failed', { status: 500, message: 'internal error' });

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.764",
+  "version": "1.19.766",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.764",
+      "version": "1.19.766",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.764",
+  "version": "1.19.766",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/provision-capacity.js

@@ -0,0 +1,74 @@
+// scripts/gds/provision-capacity.js — the runner's BOX-CAPACITY preflight
+// (ADR 0285, task 1003927): before a standalone / co-tenant project is placed on a
+// shared box, ask whether it fits, and refuse with an owner-readable reason when it
+// does not. Nothing enforced the ceiling before this — the runner stood up project
+// N+1 on a full box and swap hid the overcommit until a reboot or a fleet upgrade
+// woke every project at once.
+//
+// The arithmetic and the two walls (row ceiling, live MemAvailable floor) live in
+// modules/provisioning/capacity.js, shared with the fleet API so both surfaces show
+// one number. This file is the runner-side composition: it reads /proc/meminfo
+// through the BOX executor — the control plane for a standalone (task 2074), the
+// remote co-hosting box for a co-tenant under remote-exec (ADR 0130) — so an
+// overflow box is measured where the project will actually run. A sibling of
+// provision-config / -repo / -units / -net; provision.js requires it back.
+'use strict';
+
+const { CONFIG } = require('./provision-config.js');
+const capacity = require('../../modules/provisioning/capacity.js');
+
+// The kernel's own two lines, kept small so the journal stays readable. allowFail:
+// a box without procfs (never, on Linux) reads as "unmeasured", and the ceiling
+// then falls to ADR 0285's conservative default rather than aborting the standup.
+const MEMINFO_CMD = "grep -E '^Mem(Total|Available):' /proc/meminfo";
+
+// capacityPreflight — { ok:true, …summary } when the project fits (or the shape has
+// no shared box), { ok:false, error, …summary } when it does not. The refusal is a
+// RETURN, never a throw: the drain loop retries it (a teardown may free a slot), and
+// on retirement writes `error` onto the instance's card without flipping its status
+// — so a project that was never placed is never labelled broken. Dry-run measures
+// and reports but refuses nothing, since it places nothing either way.
+async function capacityPreflight(inst, deps) {
+  const { db, provisioning, exec, log, apply } = deps;
+  const target = capacity.placementBox(inst.hosting_shape, { remoteHost: CONFIG.remoteHost });
+  if (!target) return { ok: true, skipped: 'dedicated' };
+  const boxExec = target.box === 'control-plane' ? (deps.controlExec || exec) : exec;
+  let res = null;
+  try { res = boxExec(MEMINFO_CMD, { allowFail: true }); } catch { res = null; }
+  const mem = capacity.parseMeminfo(res && res.stdout);
+  const { ceiling, source } = capacity.ceilingFor({ override: CONFIG.boxCeiling, memTotalMb: mem.memTotalMb, fixedMb: target.fixedMb });
+  const placed = await capacity.countPlaced(db, target.shapes, { excludeId: inst.id });
+  const floorMb = CONFIG.memFloorMb || capacity.DEFAULT_MEM_FLOOR_MB;
+  const summary = capacity.capacitySummary({ box: target.box, placed, ceiling, source, memAvailableMb: mem.memAvailableMb, floorMb });
+  const free = mem.memAvailableMb != null ? `${mem.memAvailableMb} MB free` : 'memory unmeasured';
+  const where = `${target.box} box at ${placed} of ${ceiling} slots (${source}, ${free})`;
+  if (!apply) {
+    log(`  [preflight] ${where} — would refuse if full (dry-run measures nothing and places nothing)`);
+    return { ok: true, dryRun: true, ...summary };
+  }
+  if (source === 'default') log(`  [preflight] ⚠ could not measure the box — using ADR 0285's smallest-tier ceiling (${ceiling}); set PROVISION_BOX_CEILING to override`);
+  if (!summary.verdict.ok) {
+    log(`  ✖ [preflight] ${where} — refusing to place ${inst.slug} (${summary.verdict.wall} wall)`);
+    if (provisioning && provisioning.recordEvent) {
+      await provisioning.recordEvent(db, {
+        instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'placement-refused',
+        detail: summary.verdict.reason, actor: 'runner',
+      }).catch(() => {});
+    }
+    return { ok: false, error: summary.verdict.reason, ...summary };
+  }
+  log(`  [preflight] ${where} ✓${summary.resize_due ? ' — at or past 80%: schedule the resize (task 1003923) or open the next box' : ''}`);
+  return { ok: true, ...summary };
+}
+
+// statusCapacityLine — the "box at N of M" line `provision.js status` prints, read
+// from this host (the CLI runs on the control plane), so the resize is scheduled
+// at 80% rather than discovered at the ceiling.
+async function statusCapacityLine(db) {
+  const c = await capacity.fleetCapacity(db);
+  const free = c.mem_available_mb != null ? `, ${c.mem_available_mb} MB free` : '';
+  const due = c.resize_due ? ' — at or past 80%: resize or open the next box (ADR 0285, task 1003923)' : '';
+  return `  ${c.box} box: ${c.placed} of ${c.ceiling} project slots taken (${c.source}${free})${due}`;
+}
+
+module.exports = { MEMINFO_CMD, capacityPreflight, statusCapacityLine };

package/scripts/gds/provision-config.js

@@ -123,6 +123,25 @@ const CONFIG = {
   // fails fast (never hangs on a prompt); accept-new pins the host key on first
   // connect (the operator can pre-seed known_hosts for strict pinning).
   sshOpts: process.env.PROVISION_SSH_OPTS || '-o BatchMode=yes -o StrictHostKeyChecking=accept-new',
+  // ── Box capacity (ADR 0285, task 1003927) ─────────────────────────────────
+  // How many projects the box the runner places on may hold. UNSET (default)
+  // derives it from that box's own MemTotal by the ADR's formula (15 on today's
+  // s-1vcpu-2gb, 39 after the resize), so a resize raises it with no knob to
+  // remember; set it only to pin a number the measurement should not decide (a box
+  // that also hosts something the ledger cannot see). The floor is the live
+  // MemAvailable a placement must still find — two warm projects plus margin
+  // (modules/provisioning/capacity.js holds the default). Both live in box.env;
+  // mirror an override into web.env so the fleet API reports the same number.
+  boxCeiling: numEnv('PROVISION_BOX_CEILING', null),
+  memFloorMb: numEnv('PROVISION_MEM_FLOOR_MB', null),
+  // The Postgres pool cap written into a CO-LOCATED instance's web.env as PGPOOL_MAX
+  // (task 1003928, ADR 0285 §3). pg's default is 10 per process and the shared server
+  // allows 97 non-superuser backends, so nine busy projects exhaust it whatever the
+  // RAM headroom. Idle projects hold zero backends, so this bounds bursts, not the
+  // steady state: 3 × 15 slots + the control plane's own 10 stays under the 97. The
+  // control plane keeps pg's default (it is not provisioned by this runner), and a
+  // dedicated droplet has its own server, so neither is written.
+  instancePoolMax: numEnv('PROVISION_INSTANCE_PGPOOL_MAX', 3),
 };
 
 // task 1002757 — the provisioner's git identity resolves from the instance's own

package/scripts/gds/provision-units.js

@@ -267,13 +267,18 @@ GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
   const dbLines = dbPassword
     ? `PGUSER=${instanceDbRole(inst)}\nPGPASSWORD=${dbPassword}\n`
     : '';
+  // The pool cap (task 1003928, ADR 0285 §3): a co-located instance shares the box's
+  // Postgres with every sibling and the control plane, so its pool may not take pg's
+  // default 10 of the server's 97. src/bongos/pool.js reads it bare. A dedicated
+  // droplet has its own server and keeps the default — the line is not written.
+  const poolLine = inst.hosting_shape === 'dedicated' ? '' : `PGPOOL_MAX=${CONFIG.instancePoolMax}\n`;
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
 ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}${originLines}${appLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
+${poolLine}${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
 }
 function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');

package/scripts/gds/provision.js

@@ -53,6 +53,7 @@ const { CONFIG, MANIFEST_UA, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES,
 const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbName, dbRoleCmd, dbRoleCmdShown, dbRoleGrantsCmd, ensureInstanceUserCmd, generateDbPassword, grantInstanceRepoReadCmd, instanceDbRole, instanceStateDir, instanceUser, deployKeyPath, deployKeyTitle, ensurePrivateRepoAccess, installedCorePackDir, installedCoreTarball, instanceInitSpec, instanceRepoRemote, migrateCmd, onboardMode, ownerLoginOf, parseTargetRef, planCorePinRefresh, refreshStandaloneCorePin, resolveOwnerGithubToken, resolveVendorableCoreTarball, safeVersionLabel, scaffoldStandaloneRepo, seedFirstVersionCmd, standaloneInstallCmd, standaloneMigrateCmd, standalonePullCmd, standaloneRegenDocsCmd, standaloneRoot } = require('./provision-repo.js');
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
+const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
 
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   // `shown` (task 1003140): what to LOG in place of the command text — for a command
@@ -258,7 +259,8 @@ async function provisionInstance(inst, deps) {
       log(`  [preflight] would verify the Cloudflare token can reach zone ${zoneForDomain(inst.domain)} before the address step`);
     }
   }
-
+  const room = await capacityPreflight(inst, deps);   // box capacity (ADR 0285, task 1003927): an honest refusal BEFORE the status flip — never a silent oversubscribe
+  if (room.ok === false) return room;
   if (apply) await provisioning.setInstanceStatus(db, inst.id, 'provisioning');
   const patch = {};
 
@@ -1358,7 +1360,7 @@ async function cmdStatus(deps) {
     monthly += Number(r.cost_estimate_usd || 0);
     log(`  ${String(r.slug).padEnd(20)} ${String(r.status).padEnd(13)} ${r.hosting_shape.padEnd(10)} port=${r.port || '-'} @${r.github_login} $${Number(r.cost_estimate_usd || 0).toFixed(2)}/mo  ${r.domain || ''}`);
   }
-  log(`\n  estimated run-rate: ~$${monthly.toFixed(2)}/mo`);
+  log(`\n  estimated run-rate: ~$${monthly.toFixed(2)}/mo\n${await statusCapacityLine(db)}`);   // + "box at N of M" (ADR 0285, task 1003927)
   return { count: rows.length };
 }
 

package/src/bongos/pool.js

@@ -37,11 +37,27 @@ function instanceDbName() {
   return undefined;
 }
 
+// The pool's connection cap (task 1003928, ADR 0285 §3). pg's default `max` is 10 and
+// the shared server allows 97 non-superuser backends, so nine busy co-located
+// instances exhaust it whatever the RAM headroom — connections are the second wall
+// after memory. A provisioned instance's web.env carries PGPOOL_MAX (the runner
+// writes a small cap, PROVISION_INSTANCE_PGPOOL_MAX); UNSET — self-host, dev, the
+// control plane itself — returns undefined so pg keeps its own default and nothing
+// outside a co-located box changes. Read bare like the PG* family beside it: it is
+// a pg option, not a branding one, so it does not ride resolveEnv's prefix.
+// Anything that is not a positive integer is ignored rather than passed to pg.
+function poolMax(env = process.env) {
+  const n = Number(env.PGPOOL_MAX);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
 let pool;
+const max = poolMax();
 if (process.env.DATABASE_URL) {
-  pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  pool = new Pool({ connectionString: process.env.DATABASE_URL, ...(max ? { max } : {}) });
 } else {
   pool = new Pool({
+    ...(max ? { max } : {}),
     // Peer auth via the local Unix socket on the droplet; PG* env overrides for other environments.
     host: process.env.PGHOST || '/var/run/postgresql',
     database: process.env.PGDATABASE || instanceDbName(),
@@ -66,4 +82,4 @@ pool.on('error', (err) => {
   console.error('[gds/pool] unexpected pool error', err);
 });
 
-module.exports = { pool, instanceDbName };
+module.exports = { pool, instanceDbName, poolMax };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.764'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.766'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/pool_max.mjs

@@ -0,0 +1,79 @@
+// tests/pool_max.mjs
+//
+// The Postgres pool cap (task 1003928, ADR 0285 §3). Every co-located instance used
+// to open pg's default 10 connections against a shared server that allows 97, so
+// nine busy projects exhausted it whatever the RAM headroom. src/bongos/pool.js now
+// honours PGPOOL_MAX; the runner writes it into a co-located instance's web.env
+// (tests/provision.mjs pins that half). These pin the pool half:
+//
+//   • the env reaches pg's `max` — asserted on a REAL Pool built by requiring the
+//     module in a child process with the env set (pool.js builds its Pool at require
+//     time, so the assertion has to cross a process boundary; no connection is ever
+//     opened — a Pool connects lazily);
+//   • absence leaves pg's default (10), so self-host, dev and the control plane are
+//     unchanged;
+//   • garbage is ignored, never handed to pg.
+//
+// DB-free. Run:  node tests/pool_max.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { poolMax } from '../src/bongos/pool.js';
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const ROOT = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+const POOL = path.join(ROOT, 'src', 'bongos', 'pool.js');
+
+// Build the pool in a child with a controlled env and report what pg was handed.
+// The DB name is pinned so instanceDbName() never reads a pack; nothing connects.
+function poolMaxInChild(extraEnv) {
+  const env = { ...process.env, PGDATABASE: 'pool_max_probe' };
+  delete env.PGPOOL_MAX; delete env.DATABASE_URL; delete env.NODE_TEST_CONTEXT;
+  Object.assign(env, extraEnv);
+  const out = execFileSync(process.execPath, [
+    '-e', 'const { pool } = require(process.argv[1]); console.log(JSON.stringify({ max: pool.options.max })); pool.end();',
+    POOL,
+  ], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return JSON.parse(out.trim().split('\n').pop()).max;
+}
+
+console.log('poolMax (pure):');
+
+t('a positive integer is the cap; absent/blank/garbage/zero/negative/fractional → undefined (pg keeps its default)', () => {
+  assert.equal(poolMax({ PGPOOL_MAX: '3' }), 3);
+  assert.equal(poolMax({ PGPOOL_MAX: '10' }), 10);
+  assert.equal(poolMax({}), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: 'three' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '0' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '-2' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '2.5' }), undefined);
+});
+
+console.log('\nthe env reaches the real Pool (child process, no connection):');
+
+t('PGPOOL_MAX=3 → pool.options.max is 3 (the co-located instance shape)', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: '3' }), 3);
+});
+
+t('unset → pg\'s default 10 (self-host, dev, the control plane: unchanged)', () => {
+  assert.equal(poolMaxInChild({}), 10);
+});
+
+t('garbage → pg\'s default, never a NaN handed to pg', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: 'lots' }), 10);
+});
+
+t('the cap applies on the DATABASE_URL branch too', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: '4', DATABASE_URL: 'postgres://u:p@127.0.0.1:1/pool_max_probe' }), 4);
+});
+
+console.log(`\npool_max: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provision.mjs

@@ -2618,6 +2618,27 @@ t('webEnvBody: NO password ⇒ no PG credential lines — an instance provisione
   assert.match(b, /^PGDATABASE=mercury$/m, 'the DB name is unchanged either way');
 });
 
+// ── the Postgres pool cap (task 1003928, ADR 0285 §3) ─────────────────────────
+t('webEnvBody: a CO-LOCATED instance (co-tenant or standalone) carries PGPOOL_MAX at the runner\'s cap, beside PGDATABASE', () => {
+  for (const shape of ['co-tenant', 'standalone']) {
+    const b = P.webEnvBody({ ...coTenant, hosting_shape: shape });
+    assert.match(b, new RegExp(`^PGPOOL_MAX=${P.CONFIG.instancePoolMax}$`, 'm'), `${shape} carries the cap`);
+    const lines = b.split('\n');
+    assert.equal(lines[lines.indexOf('PGDATABASE=mercury') + 1], `PGPOOL_MAX=${P.CONFIG.instancePoolMax}`, 'written right after the DB name, with or without a credential');
+  }
+  assert.equal(P.CONFIG.instancePoolMax, 3, 'the default cap: 3 × 15 slots + the control plane\'s 10 stays under the server\'s 97');
+  // …and it rides along with the credential lines, not instead of them.
+  const withCred = P.webEnvBody(coTenant, { dbPassword: 'pw_ABC-123' });
+  assert.match(withCred, /^PGPOOL_MAX=3$/m);
+  assert.match(withCred, /^PGUSER=bongos-mercury$/m);
+});
+
+t('webEnvBody: a DEDICATED droplet has its own Postgres — no PGPOOL_MAX line, pg keeps its default', () => {
+  const b = P.webEnvBody({ ...coTenant, hosting_shape: 'dedicated' });
+  assert.doesNotMatch(b, /^PGPOOL_MAX=/m);
+  assert.match(b, /^PGDATABASE=mercury$/m);
+});
+
 t('dedicatedUserData: the droplet runs the SAME account + role steps, in the same order around the migrate', () => {
   const ud = P.dedicatedUserData(coTenant);
   const at = (needle) => ud.indexOf(needle);

package/tests/provisioning_capacity.mjs

@@ -0,0 +1,411 @@
+// tests/provisioning_capacity.mjs
+//
+// The box-capacity ceiling (ADR 0285, task 1003927): the shared arithmetic in
+// modules/provisioning/capacity.js, the runner preflight in
+// scripts/gds/provision-capacity.js, its composition into provisionInstance and
+// the drain loop, and the `capacity` block on GET /provisioning/fleet.
+//
+// Before this, nothing enforced the ceiling the ADR measured: the runner stood up
+// project N+1 on a full box and swap hid it. These tests pin the two walls (row
+// ceiling, live MemAvailable floor), that a refusal happens BEFORE any status write
+// or standup command, that it reaches the owner's card as error_note without
+// flipping the instance's status, and that the number every surface shows comes
+// from the same helpers. Hermetic: fake db, fake executors, a loopback listener
+// for the route; no Postgres, no shell, no /proc.
+//
+// Run:  node tests/provisioning_capacity.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import capacityDefault, {
+  DEFAULT_CEILING, DEFAULT_MEM_FLOOR_MB, PLACED_STATES,
+  parseMeminfo, placementBox, ceilingFor, placementVerdict, capacitySummary, countPlaced, fleetCapacity,
+} from '../modules/provisioning/capacity.js';
+import { MEMINFO_CMD, capacityPreflight, statusCapacityLine } from '../scripts/gds/provision-capacity.js';
+
+const require = createRequire(import.meta.url);
+const P = require('../scripts/gds/provision.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The live control plane on 2026-09-16 (1968 MiB total) and the ADR's 4 GB tier.
+const MEMINFO_2GB = 'MemTotal:        2015216 kB\nMemFree:          123456 kB\nMemAvailable:    1135180 kB\nSwapTotal:       4194300 kB\n';
+const MEMINFO_4GB = 'MemTotal:        4030432 kB\nMemAvailable:    2500000 kB\n';
+const MEMINFO_TIGHT = 'MemTotal:        2015216 kB\nMemAvailable:      120000 kB\n';   // 117 MB free — under the 256 MB floor
+
+// A fake db: answers the ceiling COUNT with `placed`, records every query, and
+// returns no rows for anything else (allocatePort etc.).
+function fakeDb(placed) {
+  const queries = [];
+  return {
+    queries,
+    query: async (sql, params) => {
+      queries.push({ sql, params });
+      if (/count\(\*\)/.test(sql)) return { rows: [{ n: placed }] };
+      return { rows: [] };
+    },
+  };
+}
+
+console.log('the arithmetic (ADR 0285):');
+
+t('parseMeminfo: MemTotal / MemAvailable in MiB; absent fields read null, never 0', () => {
+  assert.deepEqual(parseMeminfo(MEMINFO_2GB), { memTotalMb: 1967, memAvailableMb: 1108 }, 'the ADR\'s own "1967 MiB RAM" reading');
+  assert.deepEqual(parseMeminfo(''), { memTotalMb: null, memAvailableMb: null });
+  assert.deepEqual(parseMeminfo(null), { memTotalMb: null, memAvailableMb: null });
+  assert.deepEqual(parseMeminfo('MemTotal:  4030432 kB\n'), { memTotalMb: 3935, memAvailableMb: null });
+});
+
+t('ceilingFor reproduces the ADR 0285 table from MemTotal: 15 / 39 / 41 — and a resize raises it with no knob', () => {
+  assert.deepEqual(ceilingFor({ memTotalMb: 1968, fixedMb: 750 }), { ceiling: 15, source: 'measured' }, 's-1vcpu-2gb control plane');
+  assert.deepEqual(ceilingFor({ memTotalMb: 3936, fixedMb: 750 }), { ceiling: 39, source: 'measured' }, 's-2vcpu-4gb control plane');
+  assert.deepEqual(ceilingFor({ memTotalMb: 3936, fixedMb: 630 }), { ceiling: 41, source: 'measured' }, 's-2vcpu-4gb overflow box');
+});
+
+t('ceilingFor: an explicit override wins; an unmeasured box falls to the ADR smallest-tier default and SAYS so', () => {
+  assert.deepEqual(ceilingFor({ override: 20, memTotalMb: 1968 }), { ceiling: 20, source: 'env' });
+  assert.deepEqual(ceilingFor({}), { ceiling: DEFAULT_CEILING, source: 'default' });
+  assert.deepEqual(ceilingFor({ memTotalMb: 500, fixedMb: 750 }), { ceiling: DEFAULT_CEILING, source: 'default' }, 'a box smaller than its fixed base cannot be measured into a ceiling');
+  assert.equal(DEFAULT_CEILING, 15);
+});
+
+t('placementBox: standalone → control plane always; co-tenant → the remote box only under remote-exec; dedicated → no shared box', () => {
+  assert.deepEqual(placementBox('standalone', {}), { box: 'control-plane', shapes: ['standalone', 'co-tenant'], fixedMb: 750 });
+  assert.deepEqual(placementBox('standalone', { remoteHost: 'cohost' }), { box: 'control-plane', shapes: ['standalone'], fixedMb: 750 });
+  assert.deepEqual(placementBox('co-tenant', {}), { box: 'control-plane', shapes: ['standalone', 'co-tenant'], fixedMb: 750 });
+  assert.deepEqual(placementBox('co-tenant', { remoteHost: 'cohost' }), { box: 'overflow', shapes: ['co-tenant'], fixedMb: 630 });
+  assert.equal(placementBox('dedicated', {}), null);
+});
+
+t('placementVerdict: the ceiling refuses at N of N, the floor refuses under 256 MB free, an unmeasured floor cannot refuse', () => {
+  const full = placementVerdict({ placed: 15, ceiling: 15, memAvailableMb: 1108 });
+  assert.equal(full.ok, false); assert.equal(full.wall, 'ceiling');
+  assert.match(full.reason, /15 of 15 project slots/, 'names N of M for the owner');
+  assert.match(full.reason, /Nothing was placed/);
+  assert.match(full.reason, /task 1003923/, 'points at the resize');
+  const tight = placementVerdict({ placed: 10, ceiling: 15, memAvailableMb: 117 });
+  assert.equal(tight.ok, false); assert.equal(tight.wall, 'memory');
+  assert.match(tight.reason, /117 MB of memory free, under the 256 MB/);
+  assert.deepEqual(placementVerdict({ placed: 10, ceiling: 15, memAvailableMb: 1108 }), { ok: true, wall: null, reason: null });
+  assert.equal(placementVerdict({ placed: 14, ceiling: 15, memAvailableMb: null }).ok, true, 'unmeasured memory: the ceiling alone decides');
+  assert.equal(placementVerdict({ placed: 16, ceiling: 15 }).ok, false, 'past the ceiling is still full');
+  assert.equal(DEFAULT_MEM_FLOOR_MB, 256);
+});
+
+t('capacitySummary: resize_due at 80% (12 of 15), remaining never negative, verdict carried', () => {
+  const eleven = capacitySummary({ box: 'control-plane', placed: 11, ceiling: 15, source: 'measured', memAvailableMb: 1108 });
+  assert.equal(eleven.resize_at, 12); assert.equal(eleven.resize_due, false); assert.equal(eleven.remaining, 4);
+  const twelve = capacitySummary({ box: 'control-plane', placed: 12, ceiling: 15, source: 'measured', memAvailableMb: 1108 });
+  assert.equal(twelve.resize_due, true, 'the ADR schedules the resize at 12');
+  assert.equal(twelve.verdict.ok, true, 'due for a resize is not yet full');
+  const over = capacitySummary({ box: 'control-plane', placed: 16, ceiling: 15, source: 'env' });
+  assert.equal(over.remaining, 0); assert.equal(over.verdict.ok, false);
+  assert.equal(over.mem_floor_mb, DEFAULT_MEM_FLOOR_MB);
+});
+
+await ta('countPlaced counts ONLY provisioning + active rows of the box\'s shapes, and can exclude the row being re-run', async () => {
+  const db = fakeDb(10);
+  assert.equal(await countPlaced(db, ['standalone']), 10);
+  assert.deepEqual(db.queries[0].params, [['standalone'], PLACED_STATES]);
+  assert.deepEqual(PLACED_STATES, ['provisioning', 'active'], 'error rows hold no running unit (live fleet, 2026-09-16) and must not take a slot');
+  assert.doesNotMatch(db.queries[0].sql, /id <>/, 'no exclusion unless asked');
+  await countPlaced(db, ['standalone', 'co-tenant'], { excludeId: 42 });
+  assert.match(db.queries[1].sql, /id <> \$3/);
+  assert.deepEqual(db.queries[1].params, [['standalone', 'co-tenant'], PLACED_STATES, 42]);
+  assert.equal(await countPlaced({ query: async () => ({ rows: [] }) }, ['standalone']), 0, 'a recording fake with no rows reads 0, not NaN');
+});
+
+await ta('fleetCapacity (the API + CLI summary) measures THIS host and counts the control plane\'s shapes', async () => {
+  delete process.env.PROVISION_BOX_CEILING;
+  const db = fakeDb(10);
+  const c = await fleetCapacity(db, { meminfo: MEMINFO_2GB, remoteHost: null });
+  assert.equal(c.box, 'control-plane'); assert.equal(c.placed, 10); assert.equal(c.ceiling, 15); assert.equal(c.source, 'measured');
+  assert.equal(c.mem_available_mb, 1108); assert.equal(c.resize_due, false); assert.equal(c.verdict.ok, true);
+  assert.deepEqual(db.queries[0].params[0], ['standalone', 'co-tenant']);
+  const remote = await fleetCapacity(fakeDb(3), { meminfo: MEMINFO_4GB, remoteHost: 'cohost' });
+  assert.equal(remote.ceiling, 39, 'the control plane\'s own 4 GB ceiling, not the overflow box\'s');
+  // The env override reaches the summary, and is read per call.
+  process.env.PROVISION_BOX_CEILING = '9';
+  const pinned = await fleetCapacity(fakeDb(10), { meminfo: MEMINFO_2GB, remoteHost: null });
+  assert.deepEqual([pinned.ceiling, pinned.source, pinned.verdict.ok], [9, 'env', false]);
+  delete process.env.PROVISION_BOX_CEILING;
+});
+
+console.log('\nthe runner preflight (scripts/gds/provision-capacity.js):');
+
+const standalone = { id: 7, slug: 'lantern', hosting_shape: 'standalone', status: 'requested', owner_builder_id: 3, port: null, db_name: 'lantern', domain: null };
+
+// Recording deps: which executor was asked, what was logged, which events landed.
+function preflightDeps({ apply = true, placed = 10, controlMeminfo = MEMINFO_2GB, boxMeminfo = MEMINFO_4GB } = {}) {
+  const asked = [], logs = [], events = [];
+  return {
+    asked, logs, events,
+    deps: {
+      apply, log: (l) => logs.push(l),
+      db: fakeDb(placed),
+      provisioning: { recordEvent: async (_db, e) => { events.push(e); } },
+      exec: (cmd) => { asked.push(['box', cmd]); return { ok: true, stdout: boxMeminfo }; },
+      controlExec: (cmd) => { asked.push(['control', cmd]); return { ok: true, stdout: controlMeminfo }; },
+    },
+  };
+}
+
+await ta('a standalone with room: ok, measured on the CONTROL executor, the count excludes its own row', async () => {
+  const h = preflightDeps({ placed: 10 });
+  const r = await capacityPreflight(standalone, h.deps);
+  assert.equal(r.ok, true);
+  assert.deepEqual(h.asked, [['control', MEMINFO_CMD]], 'a standalone runs control-plane-local, so its box is measured there');
+  assert.equal(r.ceiling, 15); assert.equal(r.source, 'measured'); assert.equal(r.placed, 10);
+  assert.deepEqual(h.deps.db.queries[0].params[2], 7, 'the row being provisioned never counts itself');
+  assert.equal(h.events.length, 0, 'nothing to record when it fits');
+  assert.ok(h.logs.some((l) => /control-plane box at 10 of 15 slots \(measured, 1108 MB free\)/.test(l)), `logs the box line: ${h.logs.join(' | ')}`);
+});
+
+await ta('a full box REFUSES with the owner-readable reason, records placement-refused, and returns (never throws)', async () => {
+  const h = preflightDeps({ placed: 15 });
+  const r = await capacityPreflight(standalone, h.deps);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /15 of 15 project slots are taken/);
+  assert.equal(h.events.length, 1);
+  assert.equal(h.events[0].event, 'placement-refused');
+  assert.equal(h.events[0].instanceId, 7);
+  assert.equal(h.events[0].detail, r.error, 'the ledger carries the same sentence the card will');
+  assert.ok(h.logs.some((l) => /✖ \[preflight\].*refusing to place lantern \(ceiling wall\)/.test(l)));
+});
+
+await ta('the live memory floor refuses even with slots to spare (a stray unit the ledger cannot see)', async () => {
+  const h = preflightDeps({ placed: 10, controlMeminfo: MEMINFO_TIGHT });
+  const r = await capacityPreflight(standalone, h.deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.verdict.wall, 'memory');
+  assert.match(r.error, /117 MB of memory free/);
+  assert.equal(h.events[0].event, 'placement-refused');
+});
+
+await ta('at 80% it still places, but the log names the resize trigger', async () => {
+  const h = preflightDeps({ placed: 12 });
+  const r = await capacityPreflight(standalone, h.deps);
+  assert.equal(r.ok, true); assert.equal(r.resize_due, true);
+  assert.ok(h.logs.some((l) => /at or past 80%: schedule the resize \(task 1003923\)/.test(l)), h.logs.join(' | '));
+});
+
+await ta('a co-tenant under remote-exec is measured on the BOX executor against the overflow base (41 on 4 GB)', async () => {
+  const { CONFIG } = require('../scripts/gds/provision-config.js');
+  const prior = CONFIG.remoteHost;
+  CONFIG.remoteHost = 'cohost';
+  try {
+    const h = preflightDeps({ placed: 40 });
+    const r = await capacityPreflight({ ...standalone, hosting_shape: 'co-tenant' }, h.deps);
+    assert.deepEqual(h.asked, [['box', MEMINFO_CMD]]);
+    assert.equal(r.box, 'overflow'); assert.equal(r.ceiling, 41); assert.equal(r.ok, true);
+    assert.deepEqual(h.deps.db.queries[0].params[0], ['co-tenant'], 'only the shapes that share that box count');
+  } finally { CONFIG.remoteHost = prior; }
+});
+
+await ta('a dedicated droplet is its own box: no measurement, no count, no refusal', async () => {
+  const h = preflightDeps({ placed: 99 });
+  const r = await capacityPreflight({ ...standalone, hosting_shape: 'dedicated' }, h.deps);
+  assert.deepEqual(r, { ok: true, skipped: 'dedicated' });
+  assert.equal(h.asked.length, 0); assert.equal(h.deps.db.queries.length, 0);
+});
+
+await ta('dry-run measures nothing and refuses nothing, even on a full box; an unmeasured --apply falls to the default and warns', async () => {
+  const dry = preflightDeps({ apply: false, placed: 15 });
+  const r = await capacityPreflight(standalone, dry.deps);
+  assert.equal(r.ok, true); assert.equal(r.dryRun, true);
+  assert.equal(dry.events.length, 0);
+  assert.ok(dry.logs.some((l) => /would refuse if full/.test(l)));
+  // --apply with an executor that answers no stdout (a fake, or a box without procfs)
+  const blind = preflightDeps({ placed: 3, controlMeminfo: '' });
+  const b = await capacityPreflight(standalone, blind.deps);
+  assert.equal(b.ok, true); assert.equal(b.source, 'default'); assert.equal(b.ceiling, DEFAULT_CEILING);
+  assert.ok(blind.logs.some((l) => /could not measure the box.*PROVISION_BOX_CEILING/.test(l)), blind.logs.join(' | '));
+  // …and an executor that throws is the same as one that answers nothing.
+  const throwing = preflightDeps({ placed: 3 });
+  throwing.deps.controlExec = () => { throw new Error('ssh down'); };
+  assert.equal((await capacityPreflight(standalone, throwing.deps)).source, 'default');
+});
+
+await ta('statusCapacityLine prints "box at N of M" for the CLI', async () => {
+  delete process.env.PROVISION_BOX_CEILING;
+  // fleetCapacity reads THIS host's /proc/meminfo (absent on a Windows dev box → default);
+  // the line must carry the count and the source whichever it is.
+  const line = await statusCapacityLine(fakeDb(12));
+  assert.match(line, /control-plane box: 12 of \d+ project slots taken \((measured|default)/);
+});
+
+console.log('\ncomposition into the runner (provisionInstance + the drain loop):');
+
+// The recorder from tests/provision.mjs, with a db that answers the ceiling count.
+function recorder({ apply, placed, meminfo = MEMINFO_2GB }) {
+  const cmds = [], writes = [], statuses = [], events = [];
+  const db = fakeDb(placed);
+  const deps = {
+    apply, log: () => {}, db,
+    provisioning: {
+      setInstanceStatus: async (_db, _id, s) => { statuses.push(s); },
+      recordEvent: async (_db, e) => { events.push(e); },
+      getInstanceBySlug: async () => null,
+    },
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: /meminfo/.test(cmd) ? meminfo : '' }; },
+    writeFile: (p) => { writes.push(p); return { ok: true }; },
+    doApi: null,
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'example.com' }),
+    getGithubToken: async () => null,
+  };
+  return { deps, cmds, writes, statuses, events };
+}
+
+await ta('provisionInstance(--apply) on a full box returns ok:false BEFORE any status write or standup command', async () => {
+  const h = recorder({ apply: true, placed: 15 });
+  const r = await P.provisionInstance(standalone, h.deps);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /15 of 15 project slots/);
+  assert.deepEqual(h.statuses, [], 'never flipped to provisioning — a project that was not placed is not "provisioning"');
+  assert.deepEqual(h.cmds, [MEMINFO_CMD], 'the ONLY command run was the measurement');
+  assert.deepEqual(h.writes, [], 'no unit, no env file, no Caddy block');
+  assert.deepEqual(h.events.map((e) => e.event), ['placement-refused']);
+});
+
+await ta('provisionInstance(--apply) with room proceeds into the runbook exactly as before', async () => {
+  const h = recorder({ apply: true, placed: 10 });
+  const r = await P.provisionInstance({ ...standalone, hosting_shape: 'co-tenant', port: 3003 }, h.deps);
+  assert.equal(r.ok, true);
+  assert.equal(h.statuses[0], 'provisioning');
+  assert.equal(h.cmds[0], MEMINFO_CMD, 'measured first');
+  assert.ok(h.cmds.some((c) => /createdb lantern/.test(c)), 'then the runbook');
+});
+
+await ta('provisionInstance(dry-run) on a full box still prints the whole plan — dry-run places nothing, so it refuses nothing', async () => {
+  const h = recorder({ apply: false, placed: 15 });
+  const r = await P.provisionInstance({ ...standalone, hosting_shape: 'co-tenant', port: 3003 }, h.deps);
+  assert.equal(r.ok, true);
+  assert.ok(h.cmds.some((c) => /createdb lantern/.test(c)));
+});
+
+// The drain loop's retirement path: MAX_INTENT_ATTEMPTS reached → the intent is
+// resolved 'error' and the reason lands on the instance WITHOUT changing its status.
+await ta('cmdRunIntents: a refused placement retires onto the card as error_note, status untouched, event recorded', async () => {
+  let claims = 0; const resolved = [], statusWrites = [], events = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: fakeDb(15),
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0 ? { id: 9, instance_id: 7, action: 'provision', attempts: P.MAX_INTENT_ATTEMPTS } : null),
+      getInstanceById: async () => ({ ...standalone }),
+      resolveIntent: async (_db, id, state, err) => { resolved.push({ id, state, err }); },
+      setInstanceStatus: async (_db, id, status, patch) => { statusWrites.push({ id, status, patch }); },
+      recordEvent: async (_db, e) => { events.push(e); },
+      claimNextOAuthManifest: async () => null,
+      resolveOAuthManifest: async () => {},
+    },
+    exec: (cmd) => ({ ok: true, stdout: /meminfo/.test(cmd) ? MEMINFO_2GB : '' }),
+    writeFile: () => ({ ok: true }), doApi: null,
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.errors, 1); assert.equal(r.ok, 0);
+  assert.equal(resolved[0].state, 'error');
+  assert.match(resolved[0].err, /15 of 15 project slots/, 'the intent carries the reason');
+  assert.equal(statusWrites.length, 1);
+  assert.equal(statusWrites[0].status, 'requested', 'the CURRENT status is passed back — never flipped to error');
+  assert.match(statusWrites[0].patch.error_note, /Nothing was placed/, 'the card reads why');
+  assert.deepEqual(events.map((e) => e.event), ['placement-refused']);
+});
+
+await ta('cmdRunIntents: below the attempt cap a refusal goes back to pending with last_error — a teardown may free the slot', async () => {
+  let claims = 0; const updates = [];
+  const db = fakeDb(15);
+  const rawQuery = db.query;
+  db.query = async (sql, params) => { if (/SET state='pending'/.test(sql)) { updates.push(params); return { rows: [] }; } return rawQuery(sql, params); };
+  const deps = {
+    apply: true, log: () => {}, db,
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0 ? { id: 9, instance_id: 7, action: 'provision', attempts: 1 } : null),
+      getInstanceById: async () => ({ ...standalone }),
+      resolveIntent: async () => { throw new Error('must not resolve on a retryable refusal'); },
+      setInstanceStatus: async () => { throw new Error('must not touch the instance on a retryable refusal'); },
+      recordEvent: async () => {},
+      claimNextOAuthManifest: async () => null,
+      resolveOAuthManifest: async () => {},
+    },
+    exec: (cmd) => ({ ok: true, stdout: /meminfo/.test(cmd) ? MEMINFO_2GB : '' }),
+    writeFile: () => ({ ok: true }), doApi: null,
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.errors, 1);
+  assert.equal(updates.length, 1);
+  assert.equal(updates[0][0], 9);
+  assert.match(updates[0][1], /15 of 15 project slots/);
+});
+
+console.log('\nthe fleet API carries the same summary:');
+
+// Stub the route's data access at the same seams tests/provisioning_paid_shape_gate.mjs
+// uses; the capacity module object is shared with the route through the require cache.
+const provisioning = require('../modules/provisioning/provisioning.js');
+provisioning.listAllInstances = async () => [{ id: 1, owner_builder_id: 7, slug: 'lantern', status: 'active', hosting_shape: 'standalone', settings: {}, detail: {}, github_login: 'o', display_name: 'O', rank: 'archon' }];
+const api = require('../src/module-api.js');
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+api.requirePermission = () => (_req, _res, next) => next();
+const realFleetCapacity = capacityDefault.fleetCapacity;
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, ...(details || (typeof opts === 'object' ? opts : {})) } });
+  };
+  next();
+});
+app.use('/api/bongos', provisioningRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+function get(path) {
+  return new Promise((resolve, reject) => {
+    http.get(`${base}${path}`, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    }).on('error', reject);
+  });
+}
+
+await ta('GET /provisioning/fleet returns `capacity` beside the roster — placed, ceiling, source, resize_due', async () => {
+  capacityDefault.fleetCapacity = async (db) => fleetCapacity(fakeDb(12), { meminfo: MEMINFO_2GB, remoteHost: null });
+  try {
+    const res = await get('/provisioning/fleet');
+    assert.equal(res.status, 200, res.raw);
+    assert.equal(res.body.instances.length, 1);
+    const c = res.body.capacity;
+    assert.equal(c.box, 'control-plane'); assert.equal(c.placed, 12); assert.equal(c.ceiling, 15);
+    assert.equal(c.source, 'measured'); assert.equal(c.resize_due, true); assert.equal(c.remaining, 3);
+    assert.equal(c.verdict.ok, true);
+  } finally { capacityDefault.fleetCapacity = realFleetCapacity; }
+});
+
+await ta('a capacity read that fails never fails the roster: `capacity` is null, the instances still come back', async () => {
+  capacityDefault.fleetCapacity = async () => { throw new Error('count unavailable'); };
+  try {
+    const res = await get('/provisioning/fleet');
+    assert.equal(res.status, 200, res.raw);
+    assert.equal(res.body.instances.length, 1);
+    assert.equal(res.body.capacity, null);
+  } finally { capacityDefault.fleetCapacity = realFleetCapacity; }
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);