@bongos/core 1.19.142 → 1.19.143

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.142",
-  "core_contract": "1.19.142",
-  "source_commit": "34ee06f88922e1b277d1d8780b0da9c9fa7edd2a",
+  "core_version": "1.19.143",
+  "core_contract": "1.19.143",
+  "source_commit": "31df926208597154ce684504f0aa15d6b1dde113",
   "source_ref": "HEAD",
-  "built_at": "2026-08-15T15:39:26.241Z",
+  "built_at": "2026-08-15T15:52:12.410Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 303,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1250,
+    "functional_verbatim": 1251,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1574,
-  "tree_sha256": "c544fb023102eaf104fa988b33f2cb9c70a2d8817edf0549e3e5608ba47be6e4",
+  "file_count": 1575,
+  "tree_sha256": "a9a3320aae0cbec4eb5ec01e7b50675d69a50814017d7f4658efa4e52493deb4",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -347,12 +347,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "36eb537043097dc8e05307adc06d893a2c5ceb8cceb63f24b64ade001a0a2640"
+      "sha256": "0942508db8fb6f31b9e095d197f8b4cdd4efdc4e754c46629ea299ff10d895a1"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "ad598bf38511e3e7bd9f25a82987126cd71cfe76ac8275ddee2bcd90eb8e6a11"
+      "sha256": "5a4a95386b5a2ec9bc59334a35b09b5701b2ca5eabc99baf2305c7b82d920342"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -362,17 +362,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "43823273ec587b104f3e0296614ae8ea6c4dc5c96261dbbb359ae39c21cf4e79"
+      "sha256": "2c199a1ad61c8ca8a015b0918368da4c3bf4a8e6196edfd46b93048dda8e9eb5"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "eeb9b7bdf6054c92e3c605201c846d67ea20dd927355d2dc72479477c073fc7c"
+      "sha256": "e1359174cf948616e95a03232a8fe3f7a56e66aa94d578c786b6e7a258ce0221"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "6d441799f948513f840394bd382dba7e601e79a07fb7591bcb0e05aea2edd2a9"
+      "sha256": "e0e5672aafc56bfec2b6d0b3d90a73c984a5f3cf6b745025f5d9a37d8f09d7e6"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1337,12 +1337,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "b9af2341b7017c6e21b53a611a824b8d3a59653f967e6f83218c9f1d25d0ff58"
+      "sha256": "e88714b1178d43ff8aea451807a0a6095a3e90d4a592babc4ffb5c1baccac4ba"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "35762381d39e1943558131e97d3541e28d47161a56ec0a3d664942c90fb9fa9b"
+      "sha256": "0a3bf7cc757082f1764b926f72e24a14e8f22e07f0e0a5085ab6ff9d64e74ba8"
     },
     {
       "path": "docs/architecture.md",
@@ -2652,7 +2652,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "43823273ec587b104f3e0296614ae8ea6c4dc5c96261dbbb359ae39c21cf4e79"
+      "sha256": "2c199a1ad61c8ca8a015b0918368da4c3bf4a8e6196edfd46b93048dda8e9eb5"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -3877,12 +3877,12 @@
     {
       "path": "modules/provisioning/rate-limit.js",
       "mode": "0000644",
-      "sha256": "7741c4ba99f687fd02e33682a541320064aecb4fb7a7dc6b492583acc20db9a3"
+      "sha256": "27046325beffad5d1edfcc91c331048038900ef7d32f1d38796755c7990ba202"
     },
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "903a3324337f8c1f123f81ca176550df0afbdeeea1f18254d41489dc3c4fed5d"
+      "sha256": "17f6adb4edd7dee2ab339f5d302b61ecfbcf45db2ba4d0315eeeffbad87a9dce"
     },
     {
       "path": "modules/provisioning/tests/liveness.mjs",
@@ -4177,12 +4177,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "9c082e0279aa72767e3167df6277a3f34247a7d600bc184f00a4ca9380b97da5"
+      "sha256": "5f68e2c2d9e7f46d2884dce06d8bc7a5ed71f7716800c1815d550e43bd896176"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b3d152773025a6478d933888ade55e094a55016f8260989361ef426838700d03"
+      "sha256": "51affa4342af5f89f0cfda20e74bb4120338ef58c2d0309c706a7dbdb25c4d8f"
     },
     {
       "path": "public-docs/index.html",
@@ -4422,7 +4422,7 @@
     {
       "path": "public-landing/assets/cosmos.css",
       "mode": "0000644",
-      "sha256": "0e023e2e98babfd7d748b2f7542af13c41be96cbcc84f2853110410a57fe7816"
+      "sha256": "06ed45b09cb35cc8b2e20816416c45a07dd6ca47f418ac9c239ab8c949796f8b"
     },
     {
       "path": "public-landing/buddha.png",
@@ -4437,7 +4437,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "eb36261b21198d9217d96408de5ee898083aaf0d5f62368f1be3b4af9a908dcb"
+      "sha256": "aa37e8e5b14f169f593a55eb71a0c21117c818a07d34d23a35c45219c646a5dd"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -5767,7 +5767,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6eaa713a395bf793d4e07c0d68ae86a29473e410d393b859dcfd1d52bacb2811"
+      "sha256": "7ac4130655324a65c52dfd04a7b57c72371904149e8a126a16d341f82d3d1625"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6277,7 +6277,7 @@
     {
       "path": "tests/cosmos_token_contrast.mjs",
       "mode": "0000644",
-      "sha256": "15ebf10ea627a32e943d139f1a713ff46cfda14fa1a39a12d87bcc78934516c0"
+      "sha256": "6343c10b95c8ed1da86ae32367882a9970f19266bccedb26b3e15b73c5bdd37a"
     },
     {
       "path": "tests/cost.mjs",
@@ -7339,6 +7339,11 @@
       "mode": "0000644",
       "sha256": "7749df454ac3cca7c7e5ea1acc94ead15d1c9f87b38fe2028a1c93c8adf31bcf"
     },
+    {
+      "path": "tests/provisioning_slug_available.mjs",
+      "mode": "0000644",
+      "sha256": "1623d2dff20d7b5843f9fd39dd91c35e4a8ebe10b60cf798e01a7fbc4b0202cf"
+    },
     {
       "path": "tests/provisioning_teardown_intent.mjs",
       "mode": "0000644",
@@ -7352,7 +7357,7 @@
     {
       "path": "tests/public_landing_projects.mjs",
       "mode": "0000644",
-      "sha256": "d7998f770254f2c0179a6269d408f571c8757a97defd2543462b8496cb5f3e23"
+      "sha256": "ea3fc3b311115c765e7734e11cc33750a5ffde9f492d4635460b04cfc2108ad3"
     },
     {
       "path": "tests/public_mirror_export.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 269 operations across 45 resource groups
+- 270 operations across 45 resource groups
 
 ## Install
 

package/clients/bongos-client/bongos-client.global.js

@@ -533,6 +533,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
+      // GET /provisioning/slug-available — rank: any-builder — GET /provisioning/slug-available
+      getProvisioningSlugAvailable: (args) => request("GET", "/provisioning/slug-available", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

package/clients/bongos-client/index.cjs

@@ -532,6 +532,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
+      // GET /provisioning/slug-available — rank: any-builder — GET /provisioning/slug-available
+      getProvisioningSlugAvailable: (args) => request("GET", "/provisioning/slug-available", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

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

@@ -75,6 +75,7 @@ export interface GetProvisioningHealthResponse { module: unknown; ok: boolean; c
 export interface GetProvisioningInstancesIdResponse { instance: unknown; open_intent: unknown }
 export interface GetProvisioningInstancesResponse { instances: unknown }
 export interface GetProvisioningOnboardPlanResponse { mode: unknown; steps: unknown }
+export interface GetProvisioningSlugAvailableResponse { slug: unknown; available: unknown; reason: unknown; address: unknown }
 export interface GetPublicBlockersIdResponse { blocker: unknown }
 export interface GetPublicBountyTableResponse { table: unknown; currency: unknown }
 export interface GetPublicGradesResponse { window_days: unknown; rolling: unknown; trend: unknown; attempts: unknown; threshold: unknown; grader_version: unknown }
@@ -768,6 +769,8 @@ export interface BongosClient {
     postProvisioningInstancesIdTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdTeardownResponse>;
     /** GET /provisioning/onboard-plan — rank: public */
     getProvisioningOnboardPlan(args?: RequestArgs): Promise<GetProvisioningOnboardPlanResponse>;
+    /** GET /provisioning/slug-available — rank: any-builder */
+    getProvisioningSlugAvailable(args?: RequestArgs): Promise<GetProvisioningSlugAvailableResponse>;
     /** GET /provisioning/tls-check — rank: public */
     getProvisioningTlsCheck(args?: RequestArgs): Promise<ApiResponse>;
   };

package/clients/bongos-client/index.mjs

@@ -529,6 +529,8 @@ export function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
+      // GET /provisioning/slug-available — rank: any-builder — GET /provisioning/slug-available
+      getProvisioningSlugAvailable: (args) => request("GET", "/provisioning/slug-available", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

package/docs/api/openapi.json

@@ -8754,6 +8754,44 @@
         "security": []
       }
     },
+    "/provisioning/slug-available": {
+      "get": {
+        "operationId": "get_provisioning_slug_available",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/slug-available",
+        "description": "GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the create route it previews; deliberately NOT public — the answer is a yes/no about every project slug on the instance, so it is an enumeration oracle and carries its own per-IP limiter). It ADVISORY-previews the create route and must agree with it exactly, so the normalization and the bar below are lifted from POST /provisioning/instances: trim+lowercase → isValidSlug → getInstanceBySlug (the byte-exact `slug text UNIQUE` in provisioning_001_tables.sql, which is what the 23505 catch in createInstance reflects — so no lower(slug) here, or we would over-report taken). The three refusals mirror the three ways create actually answers: 'taken' — another builder holds it → create 409s slug_taken 'yours' — the CALLER holds it → create is an idempotent re-request (200, created:false), not a new project, so it is not free to create under 'reserved' — the row is free but <slug>.<apex> is a platform-reserved address → create 400s domain_reserved on the DEFAULT (assigned-address) path. A no_address create would still succeed; the wizard only asks about the default path, and reporting it distinctly keeps that recoverable. NARROWS the TOCTOU window, never closes it: another builder can take the slug between this answer and the create. The 409 at POST /provisioning/instances remains the ONLY authority — this exists so a collision is seen while the owner is still typing instead of at the final Create click.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/provisioning.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningSlugAvailableResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/tls-check": {
       "get": {
         "operationId": "get_provisioning_tls_check",
@@ -13109,6 +13147,21 @@
           "steps"
         ]
       },
+      "GetProvisioningSlugAvailableResponse": {
+        "type": "object",
+        "properties": {
+          "slug": {},
+          "available": {},
+          "reason": {},
+          "address": {}
+        },
+        "required": [
+          "slug",
+          "available",
+          "reason",
+          "address"
+        ]
+      },
       "GetPublicBlockersIdResponse": {
         "type": "object",
         "properties": {
@@ -16983,9 +17036,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 269,
-  "x-schema-count": 302,
+  "x-endpoint-count": 270,
+  "x-schema-count": 303,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 204,
+  "x-response-schemas": 205,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 269 endpoints across 44 route files.
+> **Generated from the live route files** — the route file is authoritative. 270 endpoints across 44 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -358,7 +358,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/projects/featured` | `public` | — | a curated public showcase; no auth by design. |
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | invite a builder into a project (ADR 0141 §5, task #1002115). |
 
-## `provisioning` (14)
+## `provisioning` (15)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -375,6 +375,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
 | POST | `/api/bongos/provisioning/instances/:id/teardown` | `any-builder` | — | POST /provisioning/instances/:id/teardown — request teardown of the caller's OWN instance. |
 | GET | `/api/bongos/provisioning/onboard-plan` | `public` | — | GET /provisioning/onboard-plan?mode=greenfield\|adopt&domain=<host> — the CANONICAL onboarding step sequence (task 2085; goal 35 / criteri… |
+| GET | `/api/bongos/provisioning/slug-available` | `any-builder` | — | GET /provisioning/slug-available?slug=<handle> — is this handle free to create under? rank: any authenticated builder (same gate as the c… |
 | GET | `/api/bongos/provisioning/tls-check` | `public` | — | GET /provisioning/tls-check?domain=<host> — the Caddy on-demand-TLS ALLOW-LIST (ADR 0111 §4, task P4 task 1945). |
 
 ## `public` (18)

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -532,6 +532,8 @@ function createClient(opts = {}) {
       postProvisioningInstancesIdTeardown: (args) => request("POST", "/provisioning/instances/{id}/teardown", { hasBody: true }, args),
       // GET /provisioning/onboard-plan — rank: public — GET /provisioning/onboard-plan
       getProvisioningOnboardPlan: (args) => request("GET", "/provisioning/onboard-plan", { hasBody: false }, args),
+      // GET /provisioning/slug-available — rank: any-builder — GET /provisioning/slug-available
+      getProvisioningSlugAvailable: (args) => request("GET", "/provisioning/slug-available", { hasBody: false }, args),
       // GET /provisioning/tls-check — rank: public — GET /provisioning/tls-check
       getProvisioningTlsCheck: (args) => request("GET", "/provisioning/tls-check", { hasBody: false }, args),
     },

package/modules/provisioning/rate-limit.js

@@ -12,14 +12,24 @@
 //
 // In-memory + per-process (the core limiter's model too). `now` is injectable so the
 // window logic is unit-testable without a real clock.
+//
+// `key` picks the bucket, and defaults to the caller's IP — the only identity a PUBLIC
+// endpoint has. An AUTHENTICATED route should key on the builder instead (task 1002898):
+// per-IP starves co-located builders behind one office/CGNAT address for each other,
+// and it is the weaker key anyway once a session is required, since an attacker rotates
+// IPs far more easily than accounts. Keying on a bounded id also bounds the Map.
 'use strict';
 
-function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now } = {}) {
-  const buckets = new Map(); // ip -> array of recent hit timestamps within the window
+function clientIp(req) {
+  return req.ip || (req.socket && req.socket.remoteAddress) || 'unknown';
+}
+
+function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now, key = clientIp } = {}) {
+  const buckets = new Map(); // key -> array of recent hit timestamps within the window
   return function askRateLimit(req, res, next) {
     const t = now();
-    const ip = req.ip || (req.socket && req.socket.remoteAddress) || 'unknown';
-    // Prune this IP's bucket to the window, then decide.
+    const ip = key(req) || 'unknown';
+    // Prune this caller's bucket to the window, then decide.
     const hits = (buckets.get(ip) || []).filter((ts) => ts > t - windowMs);
     if (hits.length >= max) {
       const retryAfter = Math.max(1, Math.ceil((hits[0] + windowMs - t) / 1000));
@@ -32,4 +42,4 @@ function makeAskRateLimiter({ windowMs = 60_000, max = 60, now = Date.now } = {}
   };
 }
 
-module.exports = { makeAskRateLimiter };
+module.exports = { makeAskRateLimiter, clientIp };

package/modules/provisioning/routes/provisioning.js

@@ -33,7 +33,7 @@ const auth = api;
 const { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { onboardPlan, stepsForShape } = require('../onboard-plan');
-const { makeAskRateLimiter } = require('../rate-limit');
+const { makeAskRateLimiter, clientIp } = require('../rate-limit');
 
 // How long a GitHub-App-Manifest `state` token is valid — the owner must click the
 // pre-filled link + approve on GitHub within this window (task 2080). Comfortably
@@ -242,6 +242,18 @@ module.exports = function provisioningRoutes() {
   // higher than tls-check's one-shot ask. 120/min/IP gives comfortable headroom while
   // still shedding a flood; in-memory, own bucket (does not share tls-check's budget).
   const statusRateLimit = makeAskRateLimiter({ max: 120 });
+  // Limiter for the slug-availability check (task 1002898 N10). Signed-in-only, but a
+  // session is cheap and the route answers a yes/no about EVERY project slug on the
+  // instance — an enumeration oracle if left unthrottled. A wizard debouncing one handle
+  // field fires a handful per minute, so 30 is roomy for a human and tight for a crawler.
+  // Keyed on the BUILDER, not the IP (unlike the public limiters above): the route is
+  // authenticated, so per-IP would starve co-located builders behind one office address
+  // for each other while an attacker just rotates IPs. Own bucket either way — it must
+  // not spend, or be starved by, tls-check's budget.
+  const slugCheckRateLimit = makeAskRateLimiter({
+    max: 30,
+    key: (req) => (req.builder ? `b:${req.builder.id}` : clientIp(req)),
+  });
 
   // Route ORDER is deliberate (the box.js precedent): the Archon-gated routes are
   // declared FIRST, then the any-builder routes. The route-rank auditor
@@ -358,6 +370,16 @@ module.exports = function provisioningRoutes() {
         reason: 'adopt layers onto an existing repo, so target_ref (owner/repo) is required',
       });
     }
+    // KNOWN GAP — the credential preflight belongs HERE, and is deliberately absent.
+    // This route validates that target_ref is PRESENT but never that the owner holds a
+    // usable repo credential for it, so an API caller can queue a standup that dies
+    // ~2 minutes later in raw git stderr (the task-1002697 walk did exactly that; the
+    // web wizard is only incidentally protected because it 403s earlier). Carved out of
+    // task 1002898 as N3 and tracked by task 1002909, which is BLOCKED on task 1002735
+    // deciding what credential a private-repo standup actually needs: written against
+    // the wrong definition, a preflight would refuse valid creates or keep admitting
+    // doomed ones. Greenfield must stay exempt when it lands — the platform creates
+    // that repo itself, so there is no pre-existing repo to hold a credential for.
     try {
       // A re-request must not re-litigate the address: createInstance never updates
       // an existing row's domain, so for one the guards below could only misfire —
@@ -479,6 +501,54 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // GET /provisioning/slug-available?slug=<handle> — is this handle free to create
+  // under? rank: any authenticated builder (same gate as the create route it previews;
+  // deliberately NOT public — the answer is a yes/no about every project slug on the
+  // instance, so it is an enumeration oracle and carries its own per-IP limiter).
+  //
+  // It ADVISORY-previews the create route and must agree with it exactly, so the
+  // normalization and the bar below are lifted from POST /provisioning/instances:
+  // trim+lowercase → isValidSlug → getInstanceBySlug (the byte-exact `slug text
+  // UNIQUE` in provisioning_001_tables.sql, which is what the 23505 catch in
+  // createInstance reflects — so no lower(slug) here, or we would over-report taken).
+  // The three refusals mirror the three ways create actually answers:
+  //   'taken'    — another builder holds it → create 409s slug_taken
+  //   'yours'    — the CALLER holds it → create is an idempotent re-request (200,
+  //                created:false), not a new project, so it is not free to create under
+  //   'reserved' — the row is free but <slug>.<apex> is a platform-reserved address →
+  //                create 400s domain_reserved on the DEFAULT (assigned-address) path.
+  //                A no_address create would still succeed; the wizard only asks about
+  //                the default path, and reporting it distinctly keeps that recoverable.
+  //
+  // NARROWS the TOCTOU window, never closes it: another builder can take the slug
+  // between this answer and the create. The 409 at POST /provisioning/instances
+  // remains the ONLY authority — this exists so a collision is seen while the owner
+  // is still typing instead of at the final Create click.
+  router.get('/provisioning/slug-available', auth.requireBuilder, slugCheckRateLimit, async (req, res) => {
+    const slug = String((req.query && req.query.slug) || '').trim().toLowerCase();
+    if (!provisioning.isValidSlug(slug)) {
+      return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
+    }
+    try {
+      const apex = instanceApex();
+      const address = provisioning.defaultDomainForSlug(slug, apex);
+      const holder = await provisioning.getInstanceBySlug(pool, slug);
+      let reason = null;
+      if (holder) {
+        reason = String(holder.owner_builder_id) === String(req.builder.id) ? 'yours' : 'taken';
+      } else if (address && provisioning.isReservedHostname(address, apex)) {
+        reason = 'reserved';
+      }
+      // Only the verdict travels — never the holder's row. A signed-in stranger
+      // learning WHO owns a handle (or anything about their instance) would be a
+      // disclosure this route has no reason to make.
+      res.json({ slug, available: reason === null, reason, address: address || null });
+    } catch (err) {
+      console.error('[provisioning] GET /provisioning/slug-available', err);
+      res.fail('check_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // GET /provisioning/instances — the caller's own instances + each open intent.
   // rank: any authenticated builder (own resource read).
   router.get('/provisioning/instances', auth.requireBuilder, async (req, res) => {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.142",
+  "version": "1.19.143",
   "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/public-landing/assets/cosmos.css

@@ -273,7 +273,16 @@ h1{font-family:var(--font-display);font-weight:700;font-size:clamp(24px,3.4vw,32
 /* ── project cards ── */
 .projects{list-style:none;display:flex;flex-direction:column;gap:18px;}
 .proj{border:2px solid var(--line);border-radius:18px;padding:18px 20px;background:var(--bg-card);display:flex;gap:16px;align-items:flex-start;}
-.proj.gone{opacity:0.78;}
+/* torn down = muted TOKENS, not a subtree dim. opacity multiplies AFTER every
+   token resolves, so .78 dimmed the WHOLE card — meta to 3.72:1 light / 4.16:1
+   dark, address to 4.35:1 light, and the chips and buttons with them (task
+   1002823, the .humanSteps>li.slocked pattern from 1002751). Only the name needs
+   an override: .projMeta is already --ink-faint and measures once the multiply
+   is gone. The chip, the "Torn down" line and the actions keep full strength —
+   a dead project's last known state and its Bring-it-back button are what the
+   card is there for — and the ghosted .orb stays the graphic cue. */
+.proj.gone{border-color:color-mix(in srgb,var(--line) 55%,var(--bg-card));}
+.proj.gone .projName{color:var(--ink-soft);}
 /* click-to-manage landing glow: the sky's owned orb hands focus to this card */
 .proj.anchored{border-color:var(--accent);box-shadow:0 0 0 3px color-mix(in srgb,var(--accent) 30%,transparent);}
 .projBody{flex:1;min-width:0;}
@@ -662,7 +671,14 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
   border:2px solid var(--line);border-radius:999px;padding:7px 14px;white-space:nowrap;}
 .filters button:hover{border-color:var(--accent);color:var(--accent-deep);}
 .filters button[aria-pressed="true"]{background:var(--accent);border-color:var(--accent);color:#fff;}
-.filters .n{font-family:var(--font-mono);font-weight:500;font-size:11.5px;opacity:.75;}
+/* muted by TOKEN, not opacity — .75 multiplied after the ink resolved and took
+   the count to 4.05:1 on a resting pill and 3.23:1 on the pressed one (task
+   1002823). The pressed pill is excluded on purpose: its ground is the saturated
+   --accent fill, where no ink token clears 4.5:1 (--ink is the best at 3.70
+   light / 4.05 dark) — only the button's own #fff does, at 4.61, so the count
+   inherits it there. Size, weight and the mono face already say "secondary". */
+.filters .n{font-family:var(--font-mono);font-weight:500;font-size:11.5px;}
+.filters button:not([aria-pressed="true"]) .n{color:var(--ink-faint);}
 .mineEmpty{font-size:14.5px;font-weight:600;color:var(--ink-soft);padding:10px 0 22px;}
 
 /* ── the create rail ── */

package/public-landing/projects.html

@@ -255,6 +255,10 @@ h1[tabindex="-1"]:focus{outline:none;}
 .addrConfirm.optedOut{border-color:var(--line);background:var(--bg);}
 .addrConfirm.optedOut .addrBig{color:var(--ink-soft);}
 .addrConfirm.optedOut>p{color:var(--ink-faint);}
+/* the handle is not free (task 1002898 N10) — a refusal must not be painted into the
+   green confirmation box that means "yours" */
+.addrConfirm.unavailable{border-color:color-mix(in srgb,var(--err) 45%,var(--bg-card));background:var(--bg);}
+.addrConfirm.unavailable .addrBig{color:var(--err);}
 .addrBig{font-family:var(--font-display);font-weight:700;font-size:19px;letter-spacing:-0.3px;line-height:1.4;}
 .addrBig code{font-family:var(--font-mono);font-size:15px;background:var(--bg-deep);border-radius:8px;padding:2px 9px;color:var(--accent-deep);word-break:break-all;}
 .addrConfirm>p{font-size:13.5px;font-weight:500;color:var(--ink-soft);line-height:1.5;margin-top:6px;}
@@ -713,8 +717,14 @@ h1[tabindex="-1"]:focus{outline:none;}
           </section>
 
           <!-- step 4 · address — a CONFIRMATION, not a form (task 1002704: every project
-               gets its slug subdomain assigned up front; opt-out lives in the disclosure).
-               The domainless default was a proven dead-end (QA walk, task 1002702). -->
+               gets its slug subdomain assigned up front). The domainless default was a
+               proven dead-end (QA walk, task 1002702).
+               Three choices, all legible without opening anything (task 1002898 N8):
+               the assigned address is stated, and BOTH alternatives sit under it — the
+               bring-your-own domain behind its disclosure, the no-address opt-out in the
+               open. The opt-out used to live INSIDE the "domain I own" fold, i.e. the
+               choice for NO address was hidden under a fold labelled the opposite
+               choice; the owner read the step as "weird" and never found it. -->
           <section class="panel" id="panel-address" aria-labelledby="addr-h">
             <h1 id="addr-h">Its address in the sky</h1>
             <p class="lede">The handle names your project on the platform — and its address comes with it. Sign-in, sharing, everything just works from the moment it stands up.</p>
@@ -733,11 +743,11 @@ h1[tabindex="-1"]:focus{outline:none;}
                       <input type="text" id="f-domain" placeholder="mercury.example.com" autocomplete="off" maxlength="253" spellcheck="false">
                       <div class="hint" id="h-domain">&nbsp;</div>
                     </label>
-                    <label class="addrOpt"><input type="checkbox" id="f-noaddr">
-                      <span>Start without an address — possible, but sign-in on your project can’t be set up until it has one.</span>
-                    </label>
                   </div>
                 </details>
+                <label class="addrOpt"><input type="checkbox" id="f-noaddr">
+                  <span>Start without an address — possible, but sign-in on your project can’t be set up until it has one.</span>
+                </label>
               </div>
               <div class="nav">
                 <button type="button" class="btn ghost" data-back="3">← Back</button>
@@ -2113,30 +2123,101 @@ h1[tabindex="-1"]:focus{outline:none;}
       if (state.noAddress) return '';
       return assignedDomain() || '';
     }
+    /* What the create POST may CARRY, as opposed to what the panel displays: only a
+       bring-your-own domain. The assigned <slug>.<apex> default is the server's to
+       apply (task 1002704) and re-asserting it here is what task 1002898 N2 closes —
+       apexBase() falls back to guessing from location.hostname, and a guess that
+       disagrees with the server's apex (a subdomain hub like get.<apex>) is refused
+       as an under-apex squat. Omit it and the server assigns the right one. */
+    function byoDomain() {
+      return state.domain && looksLikeDomain(state.domain) ? state.domain : '';
+    }
+
+    /* ── slug availability (task 1002898 N10) ──
+       The panel promised '<slug>.<apex> — yours from the moment it stands up' on FORMAT
+       validation alone, so a collision surfaced only as a 409 at the final Create click.
+       GET /provisioning/slug-available answers the same question the create route will,
+       and the promise is now made only once the server has said the handle is free.
+       This NARROWS the race, it does not close it — the 409 at create is still the only
+       authority — so an unanswered check degrades to naming the address WITHOUT the
+       ownership promise, never to guessing in either direction. */
+    var slugAvail = { slug: '', state: 'unknown' };  /* unknown | checking | free | taken | yours | reserved */
+    var slugCheckT = 0;
+    var slugCheckGen = 0;
+    /* Only trust a verdict that belongs to the handle currently in the field. */
+    function slugAvailState() {
+      return slugAvail.slug === state.slug ? slugAvail.state : 'unknown';
+    }
+    /* Debounced, and generation-guarded because a cleared timer cannot cancel a chain
+       already mid-fetch — each chain carries the generation it was born under, so an
+       orphaned answer goes quiet instead of overwriting a newer one (the manifest-poll
+       idiom below). The caller re-renders; this only sets state. */
+    function checkSlugAvailable() {
+      clearTimeout(slugCheckT);
+      slugCheckGen += 1;
+      var slug = state.slug;
+      if (!validSlug(slug)) { slugAvail = { slug: slug, state: 'unknown' }; return; }
+      slugAvail = { slug: slug, state: 'checking' };
+      var myGen = slugCheckGen;
+      slugCheckT = setTimeout(function () {
+        fetch(API + '/provisioning/slug-available?slug=' + encodeURIComponent(slug), { credentials: 'same-origin' })
+          .then(function (res) { if (!res.ok) throw new Error('soft'); return res.json(); })
+          .then(function (d) {
+            if (myGen !== slugCheckGen) return;
+            slugAvail = { slug: slug, state: d.available ? 'free' : (d.reason || 'taken') };
+            renderAddrPanel();
+          })
+          .catch(function () {
+            if (myGen !== slugCheckGen) return;
+            /* no answer is NOT a free answer — back to the format-only wording */
+            slugAvail = { slug: slug, state: 'unknown' };
+            renderAddrPanel();
+          });
+      }, 400);
+    }
     function renderAddrPanel() {
       var box = $('addrConfirm');
       if (!box) return;
       var assigned = assignedDomain();
       var custom = state.domain && looksLikeDomain(state.domain) ? state.domain : '';
-      box.classList.toggle('optedOut', state.noAddress && !custom);
       var big = $('addrAssigned');
       var note = $('addrAssignedNote');
+      /* the verdict only bears on the ASSIGNED address — a chosen domain or the
+         opt-out settles the step without it */
+      var avail = !custom && !state.noAddress && assigned ? slugAvailState() : 'unknown';
+      box.classList.toggle('optedOut', state.noAddress && !custom);
+      box.classList.toggle('unavailable', avail === 'taken' || avail === 'yours' || avail === 'reserved');
       if (custom) {
         big.innerHTML = '<code>' + esc(custom) + '</code> — your own domain, wired up for you.';
         note.textContent = 'DNS pointing happens after the standup; the card on your projects page walks you through it.';
       } else if (state.noAddress) {
         big.textContent = 'Starting without an address.';
         note.textContent = 'Sign-in on your project can’t be set up until it has one — add it any time from your projects page.';
-      } else if (assigned) {
+      } else if (assigned && avail === 'free') {
         big.innerHTML = '<code>' + esc(assigned) + '</code> — yours from the moment it stands up.';
         note.textContent = 'Sign-in, sharing, everything just works. You can point a domain you own at it any time.';
+      } else if (assigned && avail === 'taken') {
+        big.innerHTML = '<code>' + esc(assigned) + '</code> — already taken.';
+        note.textContent = 'Another project on the platform holds that handle. Pick a different one.';
+      } else if (assigned && avail === 'yours') {
+        big.innerHTML = '<code>' + esc(assigned) + '</code> — you already have that one.';
+        note.textContent = 'That handle belongs to one of your own projects. Pick a different one to start something new.';
+      } else if (assigned && avail === 'reserved') {
+        big.innerHTML = '<code>' + esc(assigned) + '</code> — reserved by the platform.';
+        note.textContent = 'That address is the platform’s own. Pick a different handle, or bring a domain you own.';
+      } else if (assigned && avail === 'checking') {
+        big.innerHTML = '<code>' + esc(assigned) + '</code> — checking that it’s free…';
+        note.textContent = 'One moment.';
+      } else if (assigned) {
+        /* the check didn’t answer — name the address, promise nothing about it */
+        big.innerHTML = '<code>' + esc(assigned) + '</code> — the address it would take.';
+        note.textContent = 'We couldn’t check whether that handle is free just now — you’ll know for certain when you create it.';
       } else if (!validSlug(state.slug)) {
         big.textContent = 'Pick a handle above and the address comes with it.';
         note.textContent = '';
       } else {
         /* dotless host (local dev): nothing sane to auto-assign — the domain
-           field IS the step here, so unfold it (a folded disclosure made the
-           opt-out checkbox unreachable-by-default; owner walk, 2026-08-12) */
+           field IS the step here, so unfold it */
         big.textContent = 'No address is assigned on this host.';
         note.textContent = 'Add a domain you own below, or start without one.';
         $('addrCustom').open = true;
@@ -2202,7 +2283,10 @@ h1[tabindex="-1"]:focus{outline:none;}
          (a pre-auth probe 401s for strangers and, worse, could seed the
          draft's owner with myLogin()'s placeholder) */
       if (step === 3) { syncHome(); if (authKnown) ensureRepoAccess(); }
-      if (step === 4) renderAddrPanel();
+      /* re-check on every entry, not just on typing: a resumed draft arrives here with
+         a handle nobody has asked the server about, and a handle free ten minutes ago
+         may not be now (task 1002898 N10) */
+      if (step === 4) { checkSlugAvailable(); renderAddrPanel(); }
       if (step === 5) renderReview();
     }
 
@@ -2427,6 +2511,7 @@ h1[tabindex="-1"]:focus{outline:none;}
       if (!state.slug) { h.innerHTML = '&nbsp;'; h.className = 'hint'; this.classList.remove('bad'); }
       else if (validSlug(state.slug)) { h.textContent = 'Nice — that works.'; h.className = 'hint ok'; this.classList.remove('bad'); }
       else { h.textContent = '2–40 lowercase letters, numbers, or dashes; no leading/trailing/double dash.'; h.className = 'hint err'; this.classList.add('bad'); }
+      checkSlugAvailable();
       renderAddrPanel();
       saveDraft();
     });
@@ -2481,6 +2566,23 @@ h1[tabindex="-1"]:focus{outline:none;}
           return false;
         }
         if (state.domain && !looksLikeDomain(state.domain)) return false;
+        /* A handle the server has already said is not free would only 409 at Create —
+           stop here instead (task 1002898 N10). ONLY a definite negative blocks:
+           'unknown' and 'checking' must never gate the step, because the check is
+           advisory and the 409 remains the authority. A chosen domain or the opt-out
+           settles the address another way, so the block does not apply there. */
+        if (!state.domain && !state.noAddress) {
+          var av = slugAvailState();
+          if (av === 'taken' || av === 'yours' || av === 'reserved') {
+            $('h-slug').textContent = av === 'taken'
+              ? 'That handle is already taken — pick a different one.'
+              : av === 'yours'
+                ? 'You already have a project with that handle — pick a different one.'
+                : 'That handle is reserved by the platform — pick a different one.';
+            $('h-slug').className = 'hint err'; $('f-slug').classList.add('bad');
+            return false;
+          }
+        }
         /* no auto-assigned address (dotless host): going domainless must be an
            EXPLICIT choice — a domain, or the opt-out box. Never silent. */
         if (!resolvedDomain() && !state.noAddress) {
@@ -2593,10 +2695,15 @@ h1[tabindex="-1"]:focus{outline:none;}
             slug: state.slug,
             type: state.projType || undefined,
             hosting_shape: 'standalone',
-            domain: resolvedDomain() || undefined,
-            /* The server now defaults an omitted domain to the assigned address
-               (task 1002704), so the opt-out must travel explicitly — an absent
-               domain no longer means "none". */
+            /* ONLY a bring-your-own domain travels (task 1002898 N2). The server owns
+               the assigned <slug>.<apex> default (task 1002704) and applies it to an
+               omitted domain, so re-sending our own derived copy could only disagree
+               with it — apexBase() may be guessing from location.hostname, and a guess
+               that lands under the apex but isn't the server's assignment is refused
+               as a squat. Omitting it is how the default is now requested. */
+            domain: byoDomain() || undefined,
+            /* An absent domain means "assign me the default", so the opt-out must
+               travel explicitly — it is the only thing that means "none". */
             no_address: state.noAddress ? true : undefined,
             target_ref: state.owner + '/' + state.repo,
             /* LOAD-BEARING for the control-plane runner, not just for the checklist we
@@ -2618,9 +2725,14 @@ h1[tabindex="-1"]:focus{outline:none;}
         });
       }).then(function (data) {
         try {
+          /* The address the instance ACTUALLY holds, read off the create response —
+             not our preview of it (task 1002898 N2). The server owns the assigned
+             default, so its answer is the only one the done panel may promise; a
+             client-derived copy could name an address that was never assigned. */
+          var madeDomain = (data.instance && data.instance.domain) || '';
           sessionStorage.setItem(CREATED_KEY, JSON.stringify({
-            id: data.instance && data.instance.id, slug: state.slug, domain: resolvedDomain(),
-            noaddr: !!state.noAddress,
+            id: data.instance && data.instance.id, slug: state.slug, domain: madeDomain,
+            noaddr: !madeDomain,
             mode: state.mode, name: state.name, at: Date.now()
           }));
           sessionStorage.removeItem(DRAFT_KEY);

package/src/module-api.js

@@ -711,8 +711,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.140 with no explicit bump. run 31892484952. (task 1002620)
 //   1.19.142 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.141 with no explicit bump. run 31893298770. (task 1002620)
+//   1.19.143 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.142 with no explicit bump. run 31893905320. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.142'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.143'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/cosmos_token_contrast.mjs

@@ -207,6 +207,15 @@ const PAIRS = [
   // must still measure (19px/700 headline = large text, 3.0)
   ['optedOut .addrBig (large) on --bg', 'var(--ink-soft)',      'var(--bg)',            3.0],
   ['addrOpt warning on --bg',           'var(--warn)',          'var(--bg)',            4.5],
+  // ?view=mine (task 1002823) — both surfaces traded a subtree opacity for muted
+  // tokens, so the tokens themselves now carry the de-emphasis and must measure.
+  // The two pill rows are the pair that proves the split: one mute cannot serve
+  // both grounds, because on the pressed --accent fill no ink token clears 4.5
+  // (--ink is the best at 3.70 light / 4.05 dark) and only the button's #fff does.
+  ['.filters .n count, resting pill',   'var(--ink-faint)',     CARD,                   4.5],
+  ['.filters .n count, pressed pill',   '#ffffff',              'var(--accent)',        4.5],
+  ['.proj.gone name (muted)',           'var(--ink-soft)',      CARD,                   4.5],
+  ['.proj.gone meta (dim removed)',     'var(--ink-faint)',     CARD,                   4.5],
   // lifecycle strip: 12px/700
   ['.strip .slbl idle',                 'var(--ink-faint)',     CARD,                   4.5],
   ['.strip .slbl now/done',             'color-mix(in srgb,var(--sea) 40%,var(--ink))',       CARD, 4.5],
@@ -416,9 +425,12 @@ const dimsBelowFull = (body) => {
 
 test('text is never dimmed by subtree opacity', () => {
   // Two nets. (1) Anywhere in either sheet: a rule that declares BOTH a color
-  // and a sub-1 opacity is dimmed text by construction. (2) The create flow's
-  // known text containers may not carry opacity at all — this also catches
-  // ancestor dims (.createSplit) that net 1 can't see.
+  // and a sub-1 opacity is dimmed text by construction. (2) The known text
+  // containers may not carry opacity at all — this also catches ancestor dims
+  // (.createSplit, .proj.gone) and blocks that declare NO color of their own,
+  // which is exactly how .filters .n and .proj.gone survived net 1 into task
+  // 1002823. Graphics are deliberately absent from the list: .orb.ghost and
+  // .worldOrb.dim carry no text and their opacity IS the state cue.
   const offenders = [];
   for (const [where, text] of [['cosmos.css', cssSrc], ['projects.html', pageSrc]]) {
     for (const m of text.matchAll(/([^{}@]+)\{([^{}]*)\}/g)) {
@@ -427,7 +439,7 @@ test('text is never dimmed by subtree opacity', () => {
       }
     }
   }
-  for (const sel of ['\\.humanSteps', '\\.addrConfirm', '\\.prog\\b', '\\.choice', '\\.review', '\\.createSplit', '\\.chip \\.rec']) {
+  for (const sel of ['\\.humanSteps', '\\.addrConfirm', '\\.prog\\b', '\\.choice', '\\.review', '\\.createSplit', '\\.chip \\.rec', '\\.filters', '\\.proj\\b']) {
     for (const text of [cssSrc, pageSrc]) {
       for (const m of text.matchAll(new RegExp(`${sel}[^{}]*\\{([^}]*)\\}`, 'g'))) {
         if (dimsBelowFull(m[1])) offenders.push(`text container dimmed: ${m[0].slice(0, 90)}`);

package/tests/provisioning_slug_available.mjs

@@ -0,0 +1,243 @@
+// tests/provisioning_slug_available.mjs
+//
+// GET /provisioning/slug-available (task 1002898 N10). The create wizard declared
+// '<slug>.<apex> — yours from the moment it stands up' on FORMAT validation alone;
+// no availability route existed anywhere, so a collision surfaced only as a 409 at
+// the final Create click. This route answers the same question POST
+// /provisioning/instances will, and the panel now waits for it before promising.
+//
+// The contract under test is AGREEMENT with the create route — the route is only
+// worth having if its three refusals match the three ways create actually answers:
+//   taken    → another builder holds the slug   → create 409s slug_taken
+//   yours    → the CALLER holds it              → create is an idempotent re-request
+//   reserved → row free, <slug>.<apex> reserved → create 400s domain_reserved
+// plus the same trim+lowercase normalization and the same isValidSlug bar, and the
+// same byte-exact `slug text UNIQUE` lookup (no lower(slug), which would over-report).
+//
+// Also pinned: it requires a session (NOT public — the answer is a yes/no about every
+// project slug on the instance) and it is rate-limited (same reason).
+//
+// DB-free: data-access fns are stubbed on the cached module object (the
+// provisioning_default_domain.mjs harness). No network.
+//
+// Run:  node tests/provisioning_slug_available.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ── harness ─────────────────────────────────────────────────────────────────
+let slugHolder = null;        // what getInstanceBySlug returns
+let lookedUp = [];            // the exact string the route handed the lookup
+provisioning.getInstanceBySlug = async (_db, s) => { lookedUp.push(s); return slugHolder; };
+
+const api = require('../src/module-api.js');
+let authOk = true;            // flipped to prove the route is gated, not public
+api.requireBuilder = (req, res, next) => {
+  if (!authOk) return res.status(401).json({ error: { code: 'unauthenticated' } });
+  req.builder = { id: 7, github_login: 'owner' };
+  next();
+};
+api.requirePermission = () => (_req, _res, next) => next();
+let brandingDomains = { publicOrigin: 'https://cb.test', instanceBase: 'cloudbongos.com' };
+api.branding = () => ({ domains: brandingDomains, identity: { productName: 'Cloud Bongos' } });
+
+const express = require('express');
+const provisioningRoutes = require('../modules/provisioning/routes/provisioning.js');
+
+// Each app gets its OWN router — and therefore its own fresh rate-limit bucket, so
+// the limiter test cannot be starved (or starve) the correctness tests.
+function mount() {
+  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, ...(typeof opts === 'object' ? opts : {}), ...(details || {}) } });
+    };
+    next();
+  });
+  app.use('/api/bongos', provisioningRoutes());
+  return app;
+}
+
+const server = mount().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, origin = base) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${origin}${path}`, { method: 'GET' }, (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, headers: res.headers });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+const heldBy = (ownerId) => ({ id: 41, owner_builder_id: ownerId, slug: 'spike', status: 'active', domain: 'spike.cloudbongos.com' });
+
+function reset() {
+  slugHolder = null;
+  lookedUp = [];
+  authOk = true;
+  brandingDomains = { publicOrigin: 'https://cb.test', instanceBase: 'cloudbongos.com' };
+}
+
+// ── the answer, and its agreement with the create route ─────────────────────
+console.log('GET /provisioning/slug-available — the verdict:');
+
+await ta('a free handle → available, with the address create would assign', async () => {
+  reset();
+  const res = await get('/provisioning/slug-available?slug=spike');
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(res.body, { slug: 'spike', available: true, reason: null, address: 'spike.cloudbongos.com' });
+});
+
+await ta("held by ANOTHER builder → taken (the create route's 409 slug_taken)", async () => {
+  reset();
+  slugHolder = heldBy(99);
+  const res = await get('/provisioning/slug-available?slug=spike');
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.available, false);
+  assert.equal(res.body.reason, 'taken');
+});
+
+await ta("held by the CALLER → 'yours', never 'taken' — create re-requests it, it is not a new project", async () => {
+  reset();
+  slugHolder = heldBy(7);
+  const res = await get('/provisioning/slug-available?slug=spike');
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.available, false);
+  assert.equal(res.body.reason, 'yours', 'the caller must not be told a stranger holds it');
+});
+
+await ta('the holder row NEVER travels — only the verdict', async () => {
+  reset();
+  slugHolder = heldBy(99);
+  const res = await get('/provisioning/slug-available?slug=spike');
+  assert.deepEqual(Object.keys(res.body).sort(), ['address', 'available', 'reason', 'slug']);
+  assert.doesNotMatch(res.raw, /owner_builder_id|status|"id"/, 'no instance shape may leak');
+});
+
+await ta("a free row whose <slug>.<apex> is platform-reserved → 'reserved' (create 400s domain_reserved)", async () => {
+  reset();
+  const res = await get('/provisioning/slug-available?slug=www');
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.available, false);
+  assert.equal(res.body.reason, 'reserved');
+  // agrees with the helper the create route itself calls
+  assert.equal(provisioning.isReservedHostname('www.cloudbongos.com', 'cloudbongos.com'), true);
+});
+
+await ta('a taken row wins over reserved — the row is the uniqueness rule', async () => {
+  reset();
+  slugHolder = heldBy(99);
+  const res = await get('/provisioning/slug-available?slug=www');
+  assert.equal(res.body.reason, 'taken');
+});
+
+// ── normalization: the same sequence the create route runs ──────────────────
+console.log('\nnormalization — must match the create route byte for byte:');
+
+await ta('trim + lowercase before the lookup, exactly as create does', async () => {
+  reset();
+  const res = await get('/provisioning/slug-available?slug=%20%20SPIKE%20%20');
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.slug, 'spike', 'the normalized handle is echoed back');
+  assert.deepEqual(lookedUp, ['spike'], 'the UNIQUE index is byte-exact — the lookup must be too');
+});
+
+await ta('an invalid handle → 400 bad_slug, the same bar and reason string as create', async () => {
+  for (const bad of ['a', '-bad', 'bad-', 'do--uble', 'Nope!', '', 'x'.repeat(41)]) {
+    reset();
+    const res = await get(`/provisioning/slug-available?slug=${encodeURIComponent(bad)}`);
+    assert.equal(res.status, 400, `${JSON.stringify(bad)} → ${res.raw}`);
+    assert.equal(res.body.error.code, 'bad_slug');
+    assert.match(res.body.error.reason, /lowercase, 2–40 chars/);
+  }
+});
+
+await ta('a missing slug param → 400 bad_slug, never a lookup', async () => {
+  reset();
+  const res = await get('/provisioning/slug-available');
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_slug');
+  assert.deepEqual(lookedUp, [], 'nothing may reach the database');
+});
+
+await ta('a blank apex (self-host) still answers availability, with no address to promise', async () => {
+  reset();
+  brandingDomains = { publicOrigin: 'https://cb.test', instanceBase: '' };
+  const res = await get('/provisioning/slug-available?slug=www');
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.address, null, 'nothing to assign → nothing to name');
+  assert.equal(res.body.available, true, 'with no apex there is no reserved address to collide with');
+});
+
+// ── the gate + the throttle ─────────────────────────────────────────────────
+console.log('\nthe gate and the throttle — it is an enumeration oracle:');
+
+await ta('requires a session — this route is NOT public', async () => {
+  reset();
+  authOk = false;
+  const res = await get('/provisioning/slug-available?slug=spike');
+  assert.equal(res.status, 401, res.raw);
+  assert.deepEqual(lookedUp, [], 'an unauthenticated caller learns nothing');
+});
+
+await ta('the limiter keys on the BUILDER, not the IP — one office address cannot starve itself', async () => {
+  reset();
+  const RL = require('../modules/provisioning/rate-limit.js');
+  // default key is still the IP (the public tls-check/status limiters depend on it)
+  assert.equal(RL.clientIp({ ip: '203.0.113.7' }), '203.0.113.7');
+  const seen = [];
+  const limiter = RL.makeAskRateLimiter({ max: 1, key: (req) => `b:${req.builder.id}` });
+  const runFor = (id) => new Promise((resolve) => {
+    const res = { set() {}, status(c) { this._c = c; return this; }, json(b) { resolve({ status: this._c, body: b }); } };
+    limiter({ ip: '203.0.113.7', builder: { id } }, res, () => { seen.push(id); resolve({ status: 200 }); });
+  });
+  assert.equal((await runFor(7)).status, 200, 'builder 7 gets its first call');
+  assert.equal((await runFor(7)).status, 429, 'and is throttled on its second');
+  assert.equal((await runFor(8)).status, 200,
+    'a DIFFERENT builder on the same IP still gets through — the bucket is per-builder');
+  assert.deepEqual(seen, [7, 8]);
+});
+
+await ta('rate-limited — a crawler is shed with 429 + Retry-After', async () => {
+  reset();
+  const rlServer = mount().listen(0);
+  await new Promise((r) => rlServer.once('listening', r));
+  const rlBase = `http://127.0.0.1:${rlServer.address().port}/api/bongos`;
+  try {
+    let limited = null;
+    // the limiter's cap is 30/min/IP; walk past it and the next answer must be 429
+    for (let i = 0; i < 40 && !limited; i++) {
+      const res = await get(`/provisioning/slug-available?slug=spike${i}`, rlBase);
+      if (res.status === 429) limited = res;
+    }
+    assert.ok(limited, 'the route must stop answering under a flood');
+    assert.equal(limited.body.error, 'rate_limited');
+    assert.ok(Number(limited.headers['retry-after']) > 0, 'Retry-After must tell the caller when');
+  } finally {
+    rlServer.close();
+  }
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/public_landing_projects.mjs

@@ -251,6 +251,124 @@ test('the create-repo response keeps the html_url it already returned', async ()
   assert.match(fn, /saveDraft\(\)/, 'the draft is persisted after the URL lands on state');
 });
 
+/* ── The address step's three choices (task 1002898 N2 / N8 / N10) ───────────
+   One root: the create path asserted things it had not verified. The step offered
+   an address it had not checked was free, hid the no-address opt-out under a fold
+   labelled the OPPOSITE choice, and re-sent a client-derived default the server
+   already owns. ── */
+
+test('the no-address opt-out is visible at the step, not folded under "a domain I own" (N8)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  const panel = (body.match(/<div class="addrConfirm" id="addrConfirm">([\s\S]*?)\n {14}<\/div>/) || [, ''])[1];
+  assert.ok(panel, 'the address confirmation box must be extractable');
+  const fold = (panel.match(/<details id="addrCustom">[\s\S]*?<\/details>/) || [''])[0];
+  assert.ok(fold, 'the bring-your-own-domain disclosure still exists');
+  assert.match(fold, /id="f-domain"/, 'the domain field is what the fold is FOR');
+  assert.doesNotMatch(fold, /f-noaddr/,
+    'the opt-out for NO address may not live under a fold labelled "use a domain I own"');
+  assert.match(panel, /<\/details>[\s\S]*id="f-noaddr"/,
+    'the opt-out sits after the disclosure, in the open');
+  // all three choices legible at once: assigned address, own domain, no address
+  assert.match(panel, /id="addrAssigned"/);
+  assert.match(fold, /Use a domain I own instead/);
+  assert.match(panel, /Start without an address/);
+});
+
+test('the ownership promise is gated on the availability answer, never on format (N10)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  const fn = (body.match(/function renderAddrPanel\(\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
+  assert.ok(fn, 'renderAddrPanel() must be extractable');
+  // the promise now rides a branch that requires the server's verdict
+  assert.match(fn, /avail === 'free'[\s\S]{0,200}yours from the moment it stands up/,
+    "'yours from the moment it stands up' must only render on a free verdict");
+  // and the honest alternatives exist rather than a single optimistic string
+  assert.match(fn, /already taken/, 'a taken handle is said, not confirmed');
+  assert.match(fn, /you already have that one/i, "the caller's own handle reads as theirs, not as a stranger's");
+  assert.match(fn, /reserved by the platform/, 'a platform-reserved address is said');
+  assert.match(fn, /checking that it’s free/, 'the in-flight state has its own calm rung');
+  // the degrade: an unanswered check names the address WITHOUT promising it
+  assert.match(fn, /the address it would take/, 'no answer degrades to naming, not promising');
+  assert.match(fn, /couldn’t check whether that handle is free/, 'and says so honestly');
+});
+
+test('the availability check is debounced, generation-guarded, and fails to "unknown" (N10)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  const fn = (body.match(/function checkSlugAvailable\(\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
+  assert.ok(fn, 'checkSlugAvailable() must be extractable');
+  assert.match(fn, /\/provisioning\/slug-available\?slug=/, 'it asks the real route');
+  assert.match(fn, /encodeURIComponent\(slug\)/, 'the handle is encoded into the query');
+  assert.match(fn, /clearTimeout\(slugCheckT\)[\s\S]*setTimeout\(/, 'debounced on a timer');
+  assert.match(fn, /myGen !== slugCheckGen/, 'a stale in-flight answer cannot overwrite a newer one');
+  assert.match(fn, /catch[\s\S]*state: 'unknown'/, 'a failed check is never read as free');
+  // a verdict only counts for the handle it was asked about
+  const guard = (body.match(/function slugAvailState\(\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
+  assert.match(guard, /slugAvail\.slug === state\.slug/, 'a verdict for another handle is not trusted');
+});
+
+test('only a DEFINITE negative blocks the step — unknown and checking never gate it (N10)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  const fn = (body.match(/function validateStep\(step\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
+  assert.ok(fn, 'validateStep() must be extractable');
+  const gate = (fn.match(/if \(!state\.domain && !state\.noAddress\) \{[\s\S]*?\n {8}\}/) || [''])[0];
+  assert.ok(gate, 'the availability gate must be extractable');
+  assert.match(gate, /av === 'taken' \|\| av === 'yours' \|\| av === 'reserved'/,
+    'exactly the three definite negatives block');
+  assert.doesNotMatch(gate, /'unknown'|'checking'/,
+    'an unanswered or in-flight check must never trap the owner on the step');
+});
+
+test("the wizard's validSlug() agrees with the server's isValidSlug(), handle for handle (N10)", async () => {
+  // The whole availability contract is "answer what create would answer" — but the
+  // page gates on its OWN hand-copied validSlug() before it even asks. If the two
+  // drift, the wizard promises (or refuses) an address the server would not, which is
+  // the exact class of dishonesty N10 exists to close. Run both over the same corpus.
+  const { body } = await request('/projects', 'game.test.local');
+  const src = (body.match(/(function validSlug\(s\)\s*\{[\s\S]*?\n    \})/) || [, ''])[1];
+  assert.ok(src, 'validSlug() must be extractable');
+  const clientValid = new Function('s', `${src}\nreturn validSlug(s);`);
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  const serverValid = require('../modules/provisioning/provisioning.js').isValidSlug;
+
+  const corpus = [
+    'mercury', 'a1', 'x'.repeat(40), 'has-dash', 'a-b-c', '0start', 'end0',
+    'a', '', 'x'.repeat(41), '-lead', 'trail-', 'do--uble', 'UPPER', 'sp ace',
+    'dot.ted', 'under_score', 'bang!', 'uni✦code', '--', '-', 'a--b',
+  ];
+  for (const s of corpus) {
+    assert.equal(clientValid(s), serverValid(s),
+      `validSlug(${JSON.stringify(s)}) disagrees: page=${clientValid(s)} server=${serverValid(s)}`);
+  }
+});
+
+test('the create POST lets the SERVER assign the default address (N2)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  // the wizard may only carry a bring-your-own domain; the <slug>.<apex> default is
+  // the server's (task 1002704), and re-asserting a client-derived copy could only
+  // disagree with it
+  assert.match(body, /domain: byoDomain\(\) \|\| undefined/,
+    'only a bring-your-own domain travels in the create body');
+  assert.doesNotMatch(body, /domain: resolvedDomain\(\) \|\| undefined/,
+    'the client-derived assigned default must no longer be re-sent');
+  const fn = (body.match(/function byoDomain\(\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
+  assert.ok(fn, 'byoDomain() must be extractable');
+  assert.match(fn, /looksLikeDomain\(state\.domain\)/, 'and only a domain that parses');
+  // the opt-out is still the only thing that means "no address"
+  assert.match(body, /no_address: state\.noAddress \? true : undefined/,
+    'the explicit opt-out shape must survive — an absent domain now means "assign one"');
+  // resolvedDomain() still drives what the page DISPLAYS; it just stops driving the wire
+  assert.match(body, /resolvedDomain\(\)/, 'the display path keeps its own resolver');
+});
+
+test('the done panel promises the address the SERVER assigned, not our preview (N2)', async () => {
+  const { body } = await request('/projects', 'game.test.local');
+  assert.match(body, /var madeDomain = \(data\.instance && data\.instance\.domain\) \|\| '';/,
+    'the created-instance stash reads the address off the create response');
+  assert.match(body, /domain: madeDomain/, 'and stashes that, not resolvedDomain()');
+  assert.match(body, /noaddr: !madeDomain/,
+    'no address on the row IS the no-address state — derived, not re-asserted');
+});
+
 test('the address row surfaces the manual-DNS note the runner recorded (F16)', async () => {
   const { body } = await request('/projects', 'game.test.local');
   assert.match(body, /inst\.dns_note/, 'the card reads the dns_note the runner writes');