@bongos/core 1.19.121 → 1.19.122

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.121",
-  "core_contract": "1.19.121",
-  "source_commit": "5bc8620889777dfaeebdc0bef12a6ac24c036e61",
+  "core_version": "1.19.122",
+  "core_contract": "1.19.122",
+  "source_commit": "b8e5d6f6d62653ae415e42551ccb3c3c4e6c6f8a",
   "source_ref": "HEAD",
-  "built_at": "2026-08-14T20:40:48.360Z",
+  "built_at": "2026-08-14T21:05:40.247Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 303,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1243,
+    "functional_verbatim": 1244,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1567,
-  "tree_sha256": "c642320ac42a83f1863a48c74b443b0c761d83a85ad45114720ee0a9f60bc850",
+  "file_count": 1568,
+  "tree_sha256": "03f0574ec4219110a53d6b8faaa4b93bcc96f0371d85d2a2e412d06d21364892",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "167b7dcd701d2a23eec6dec515778e84cb262d95c070a5a749da642e5aada701"
+      "sha256": "eeb9b7bdf6054c92e3c605201c846d67ea20dd927355d2dc72479477c073fc7c"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -382,7 +382,7 @@
     {
       "path": "config/branding.neutral.json",
       "mode": "0000644",
-      "sha256": "48dc7ade227b763df5d9942930200042a3b76a7e1d00c281c43c2ab5304bf0da"
+      "sha256": "dc69c5c9e9041da9cd3c297c3e7c81c8311f42952524297d9f228cc1751af3ea"
     },
     {
       "path": "config/design-tokens.neutral.json",
@@ -1337,12 +1337,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "06954a3b30e235ef61a316d4f7414a2eaf2c0f2d3fe1063698e800f3655d1675"
+      "sha256": "b9af2341b7017c6e21b53a611a824b8d3a59653f967e6f83218c9f1d25d0ff58"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "3910ea26d65b5afc883d4b3488d605ee5786bda41ef86e280b5a180d6f6fa586"
+      "sha256": "35762381d39e1943558131e97d3541e28d47161a56ec0a3d664942c90fb9fa9b"
     },
     {
       "path": "docs/architecture.md",
@@ -1352,7 +1352,7 @@
     {
       "path": "docs/branding-contract.md",
       "mode": "0000644",
-      "sha256": "bda65bdc06badd4f426468941be2800fd3c50e2ed1dd8bdd4d37d94bc668b4bd"
+      "sha256": "f5918fa955f90ca30412ebce209bf2d51b67fa318f7f04d667262cd42c134745"
     },
     {
       "path": "docs/branding-fill-prompt.md",
@@ -3862,7 +3862,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "9163b2b0de80a648371d03f89e0da8ff234a1cd4f038a1279f6324ae0921e0f4"
+      "sha256": "59fd212df421b2bdcdfaef4871aa1927c371d3f7d6affafe44e810135acd12b6"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -3872,7 +3872,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "232d5ce81dc2821b9b953c7596ab385b89e2d5193891735e3220021437fd06db"
+      "sha256": "321db8769eda7c5f6f385e90edaeec70fc071f0bc2e53e6147705153b0d32d3a"
     },
     {
       "path": "modules/provisioning/tests/liveness.mjs",
@@ -4167,12 +4167,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "f4b51e6942ce9cd2f52b077f67e671feb4ac93e03d08a2fc487981205fc362b9"
+      "sha256": "969a257b3ae8148774d7d64cef01f68be0eec703043a129ae34984f3399208d9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1d7889d13a0d5ab2930528a5b8efdde5e9b28cb1467f5f0b29dec2e60ce722f0"
+      "sha256": "904c4fce25eeb089d80da1a5a0cfced1a96b99aea4f2bc28e5ce07d66bd8a880"
     },
     {
       "path": "public-docs/index.html",
@@ -4427,7 +4427,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "576bc8fe1e3379dd2efa6323f889b65d9c4cbb5164b5e80716a6eee045bad002"
+      "sha256": "925e7964f66d59f2df260a611e602bdeafe3f8f3b73d3d16db7bdfa073b4163c"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -4892,7 +4892,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "e9fbb7ae477a445252f1171851be93fca14f58e4906d030c93d09b37d517ac20"
+      "sha256": "bde86f3f65cdd4a1ad0e143c58f6517328dd7cdee7c1194c0fa614aaf9df56f6"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -5037,7 +5037,7 @@
     {
       "path": "scripts/gds/onboard.js",
       "mode": "0000644",
-      "sha256": "2a8fd60c85b7ef4372a3325d44c9b939f394c5ab1a8364985f2278abfdb8aca4"
+      "sha256": "c6fb2c531c6d84dcb16daea50984e1b24021b6379cf992a01482951b119bf9e4"
     },
     {
       "path": "scripts/gds/onboarding-analyze.js",
@@ -5717,7 +5717,7 @@
     {
       "path": "src/bongos/serve-internal.js",
       "mode": "0000644",
-      "sha256": "c791369591627f89ff1755ea1d343159716b512e64f92286d27547209da88df7"
+      "sha256": "465211ef9e62fd74828d326ab427b0b21b7b73f6124e842b55f8b23d51660ebe"
     },
     {
       "path": "src/bongos/stealth-gate.js",
@@ -5752,7 +5752,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "180b8c272ae0895dc57e67f1a0558c603bb811e6bda5d0dee4d1547239851728"
+      "sha256": "79041166a496039eff11ecc00334671609fadace4a54645cf2b287a5b5ff1a53"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7294,10 +7294,15 @@
       "mode": "0000644",
       "sha256": "edb6c5da9ec32536d50f7cb648b81b026b7926f73f891feb0906fc7343b5b11d"
     },
+    {
+      "path": "tests/provisioning_default_domain.mjs",
+      "mode": "0000644",
+      "sha256": "1403cc764270e796b985cc0dc38cbf498001e4726b2bfe53020cc55d12d1ca66"
+    },
     {
       "path": "tests/provisioning_domain_attach.mjs",
       "mode": "0000644",
-      "sha256": "241e1b208abbd54a625af050d541344186d93806846a1e7f1cbb0f93dfbab802"
+      "sha256": "fbbd7397fd03181e9c2ea58ed8accb1a9d9d66d4c904a09265161e1034b02f9f"
     },
     {
       "path": "tests/provisioning_github_app_routes.mjs",
@@ -7312,7 +7317,7 @@
     {
       "path": "tests/provisioning_teardown_intent.mjs",
       "mode": "0000644",
-      "sha256": "c5ebacf7e29be4e6afecedf5b8593eef750d497e0c502cfa2be92a89b2cff0a1"
+      "sha256": "68d328b69cd8b981e8454d679c00a757abeeafb4e083249489eec744cdd4898d"
     },
     {
       "path": "tests/pruned_lockfile_integrity.mjs",

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

@@ -252,7 +252,7 @@ export interface PostProvisioningInstancesIdForceTeardownResponse { ok: boolean;
 export interface PostProvisioningInstancesIdGithubAppRequest { account?: string }
 export interface PostProvisioningInstancesIdGithubAppResponse { state: unknown; account: unknown; post_url: unknown; personal_url: unknown; org_url: unknown; org_login: unknown; manifest: unknown; redirect_url: unknown; expires_at: unknown }
 export interface PostProvisioningInstancesIdTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; superseded: unknown; message: unknown }
-export interface PostProvisioningInstancesRequest { slug: string; target_ref?: string; hosting_shape?: string; domain?: string; tier?: string; onboard_mode?: string; type?: string }
+export interface PostProvisioningInstancesRequest { slug: string; target_ref?: string; hosting_shape?: string; domain?: string; no_address?: boolean; tier?: string; onboard_mode?: string; type?: string }
 export interface PostSearchMarkRequest { chunk_id?: StringifiableId; useful?: unknown }
 export interface PostSearchRequest { expand?: unknown; q?: string; source_kind?: string; limit?: unknown }
 export interface PostSearchResponse { expand?: unknown; chunk?: unknown; query?: unknown; count?: unknown; total_full_tokens?: unknown; results?: unknown }

package/config/branding.neutral.json

@@ -15,6 +15,7 @@
     "oauthOrigin": "http://localhost:3000",
     "devBoxBase": "",
     "sshBoxBase": "",
+    "instanceBase": "",
     "sandboxPrefix": "sandbox-",
     "termPrefix": "term-"
   },

package/docs/api/openapi.json

@@ -15826,6 +15826,9 @@
             "type": "string",
             "maxLength": 253
           },
+          "no_address": {
+            "type": "boolean"
+          },
           "tier": {
             "type": "string",
             "maxLength": 40

package/docs/api-reference.md

@@ -368,7 +368,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/provisioning/github-app/status` | `public` | — | GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup… |
 | GET | `/api/bongos/provisioning/health` | `public` | — | GET /provisioning/health — liveness + the core version this module mounted against. |
 | GET | `/api/bongos/provisioning/instances` | `any-builder` | — | GET /provisioning/instances — the caller's own instances + each open intent. |
-| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `tier`, `onboard_mode`, `type` | POST /provisioning/instances — request a new instance. |
+| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `no_address`, `tier`, `onboard_mode`, `type` | POST /provisioning/instances — request a new instance. |
 | GET | `/api/bongos/provisioning/instances/:id` | `any-builder` | — | GET /provisioning/instances/:id — read one of the caller's own instances. |
 | POST | `/api/bongos/provisioning/instances/:id/domain` | `any-builder` | `domain` | POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domai… |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |

package/docs/branding-contract.md

@@ -31,6 +31,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `domains.provisioningOrigin` | **Optional.** Control-plane front-door origin the [provisioning module](../../modules/provisioning/CLAUDE.md) uses to build a new customer's GitHub-App `redirect_url`. Set it when the control plane co-hosts a game whose `publicOrigin` is the game's own domain (OTB = customer 0) so the customer's App carries the PLATFORM brand (e.g. `https://get.cloudbongos.com`), not the game's. **Falls back to `publicOrigin` when unset** — an instance whose `publicOrigin` is already the platform needs no override. Env-overridable: `<PREFIX>_PROVISIONING_ORIGIN`. ([#2101](https://example.com/builders#/task/2101)) |
 | `domains.devBoxBase` | Apex zone the **proxied** browser-terminal + sandbox hosts ride (`term-<login>.<devBoxBase>`, `sandbox-<login>.<devBoxBase>`). Must be a one-label-under-apex zone so free edge TLS (`*.<apex>`) covers it — a two-label host fails edge TLS (the [#771](https://example.com/builders#/task/771) lesson). Empty ⇒ no managed boxes. |
 | `domains.sshBoxBase` | Zone for the **legacy direct-IP SSH** box host (`box-<login>.<sshBoxBase>`, unproxied). Deliberately distinct from `devBoxBase` (one proxied/edge-TLS, one direct-IP). |
+| `domains.instanceBase` | Apex zone new projects get their **auto-assigned** address under (`<slug>.<instanceBase>`, task 1002704 — every project's hall reachable day one; `no_address: true` on the create call opts out). Same one-label-under-apex/edge-TLS constraint as `devBoxBase`. Deliberately NOT derived from `publicOrigin` (on a co-hosting control plane that is the game's domain). Empty ⇒ no auto-assign — creates are domainless unless the caller brings a domain. |
 | `domains.sandboxPrefix` / `termPrefix` | Subdomain prefixes for the sandbox-preview + browser-terminal hosts. |
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name the GDS pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |

package/modules/provisioning/provisioning.js

@@ -111,6 +111,42 @@ function normalizeHostname(h) {
   return s;
 }
 
+// The auto-assigned address for a new project: <slug>.<apex> (task 1002704 — the
+// owner's auto-assign/opt-out decision; every project's hall reachable day one).
+// The apex is branding domains.instanceBase; blank or unparseable → null, so a
+// self-host or unconfigured instance keeps creating domainless instead of
+// guessing (the client's location.hostname guess stays client-side only). PURE.
+function defaultDomainForSlug(slug, apex) {
+  if (!isValidSlug(slug)) return null;
+  const a = String(apex == null ? '' : apex).trim();
+  if (!a) return null;
+  return normalizeHostname(`${slug}.${a}`) || null;
+}
+
+// Labels the platform itself occupies (or has planned) directly under the instance
+// apex, plus the dev-box hostname prefixes. The runner's DNS write is an UPSERT,
+// so a project claiming one of these would overwrite platform records — refuse at
+// the API layer instead (task 1002704; the guard applies to auto-assigned AND
+// bring-your-own hostnames, on create and on attach). Anything deeper than one
+// label under the apex is also refused: it breaks the wildcard-cert rule (one
+// label under the apex — the #771 lesson) and nothing legitimate creates it.
+const RESERVED_APEX_LABELS = new Set([
+  'www', 'api', 'get', 'status', 'builders', 'docs', 'mail', 'admin', 'app',
+  'cdn', 'ns1', 'ns2', 'demo', 'gate', 'downloads',
+]);
+const RESERVED_APEX_PREFIXES = ['term-', 'sandbox-'];
+function isReservedHostname(domain, apex) {
+  const host = normalizeHostname(domain);
+  const zone = normalizeHostname(apex);
+  if (!host || !zone) return false;
+  if (host === zone) return true;
+  if (!host.endsWith(`.${zone}`)) return false;
+  const label = host.slice(0, -(zone.length + 1));
+  if (label.includes('.')) return true;
+  if (RESERVED_APEX_LABELS.has(label)) return true;
+  return RESERVED_APEX_PREFIXES.some((p) => label.startsWith(p));
+}
+
 // The instance lifecycle states for which an on-demand TLS cert may be minted: a
 // host mid-standup ('provisioning' — Caddy's first handshake can land here, while
 // the snippet is written + reloaded) or live ('active'). NOT 'requested' (nothing
@@ -658,6 +694,7 @@ module.exports = {
   PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
+  defaultDomainForSlug, isReservedHostname,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl,
   // data access

package/modules/provisioning/routes/provisioning.js

@@ -55,6 +55,16 @@ function mothershipOrigin() {
   catch { return ''; }
 }
 
+// The apex under which new projects get their auto-assigned <slug>.<apex> address
+// (task 1002704). A dedicated branding key — NOT publicOrigin, which on a control
+// plane that co-hosts a game is the GAME's domain (see mothershipOrigin above), so
+// deriving from it would assign customers under the wrong zone. Blank/absent →
+// no auto-assign: self-host and unconfigured instances keep creating domainless.
+function instanceApex() {
+  try { return (api.branding().domains || {}).instanceBase || ''; }
+  catch { return ''; }
+}
+
 // The provisioning mothership's product brand (e.g. "Cloud Bongos" on the control plane),
 // used to brand-qualify the auto GitHub App name so a common project slug ("demo") does
 // not collide with an existing GitHub App (task 2093). Portable — reads THIS instance's
@@ -311,6 +321,7 @@ module.exports = function provisioningRoutes() {
       target_ref: { type: 'string', maxLength: 200 },
       hosting_shape: { type: 'string', maxLength: 20 },
       domain: { type: 'string', maxLength: 253 },
+      no_address: { type: 'boolean' },
       tier: { type: 'string', maxLength: 40 },
       onboard_mode: { type: 'string', maxLength: 20 },
       // the declared project Type (task 1002772) — optional, closed vocabulary
@@ -337,10 +348,57 @@ module.exports = function provisioningRoutes() {
       });
     }
     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 —
+      // a "Try again" on a pre-existing reserved-label row, or domain_taken fired
+      // against the row's own address. Birth-time rules run at birth only.
+      const existing = await provisioning.getInstanceBySlug(pool, slug);
+      // Resolve the address (task 1002704 — auto-assign, opt-out). An explicit
+      // domain (bring-your-own) wins; `no_address: true` is the deliberate opt-out;
+      // otherwise default to <slug>.<instanceBase> so an API-first caller inherits
+      // the same day-one address the wizard promises. An omitted domain is NOT an
+      // opt-out. Explicit domains are normalized + refused when malformed — the
+      // same bar the attach route has always applied (create inserted them raw).
+      let domain;
+      const assignedDefault = provisioning.defaultDomainForSlug(slug, instanceApex());
+      if (!existing) {
+        if (String(body.domain || '').trim()) {
+          domain = provisioning.normalizeHostname(body.domain);
+          if (!domain) {
+            return res.fail('bad_domain', 400, { reason: 'not a plausible hostname (letters/digits/dashes, at least two labels)' });
+          }
+        } else if (!body.no_address) {
+          domain = assignedDefault || undefined;
+        }
+        if (domain && provisioning.isReservedHostname(domain, instanceApex())) {
+          return res.fail('domain_reserved', {
+            status: 400,
+            message: `${domain} is a platform-reserved address — pick a different handle or bring your own domain.`,
+          });
+        }
+        // Inside the platform apex, the only address a project can hold is its own
+        // <slug>.<apex> — any other label under the apex is a squat on another
+        // handle's address space. Domains outside the apex are the real BYO path.
+        const apexZone = provisioning.normalizeHostname(instanceApex());
+        if (domain && apexZone && domain.endsWith(`.${apexZone}`) && domain !== assignedDefault) {
+          return res.fail('domain_reserved', {
+            status: 400,
+            message: `Inside ${apexZone}, a project's address is its own <handle>.${apexZone} — bring a domain you own instead.`,
+          });
+        }
+        // The same uniqueness bar as the attach route: one owner's address can
+        // never silently shadow another's.
+        if (domain) {
+          const holder = await provisioning.getInstanceByDomain(pool, domain);
+          if (holder && holder.slug !== slug) {
+            return res.fail('domain_taken', { status: 409, message: 'That address is already held by another instance.' });
+          }
+        }
+      }
       const { instance, created } = await provisioning.createInstance(pool, {
         ownerBuilderId: req.builder.id, slug,
         targetRef: body.target_ref, hostingShape: shape,
-        domain: body.domain, tier: body.tier, onboardMode,
+        domain, tier: body.tier, onboardMode,
         type: body.type,
       });
       // Slug already taken by ANOTHER builder — refuse (never reassign ownership).
@@ -360,7 +418,7 @@ module.exports = function provisioningRoutes() {
       if (created) {
         await provisioning.recordEvent(pool, {
           instanceId: instance.id, ownerBuilderId: req.builder.id, event: 'request',
-          detail: `provision requested (shape=${shape}, mode=${onboardMode}${body.domain ? `, domain=${body.domain}` : ''})`,
+          detail: `provision requested (shape=${shape}, mode=${onboardMode}${domain ? `, domain=${domain} (${domain === assignedDefault ? 'assigned' : 'byo'})` : ', no address'})`,
           actor: 'api:self',
         }).catch(() => {});
       }
@@ -376,6 +434,15 @@ module.exports = function provisioningRoutes() {
           };
         }
       }
+      // …and a re-request cannot REMOVE one either (task 1002704's opt-out only
+      // applies at birth) — same honesty, opposite direction.
+      let noAddressIgnored;
+      if (!created && body.no_address && instance.domain) {
+        noAddressIgnored = {
+          current: instance.domain,
+          hint: "a re-request never removes an existing instance's address",
+        };
+      }
       // Same honesty for a changed Type (task 1002772): a re-request keeps the
       // original declaration, and unlike domain there is no mutation route yet —
       // say so rather than silently dropping the new answer.
@@ -392,6 +459,7 @@ module.exports = function provisioningRoutes() {
         queued: intentCreated,
         created,
         ...(domainIgnored ? { domain_ignored: domainIgnored } : {}),
+        ...(noAddressIgnored ? { no_address_ignored: noAddressIgnored } : {}),
         ...(typeIgnored ? { type_ignored: typeIgnored } : {}),
       });
     } catch (err) {
@@ -497,16 +565,38 @@ module.exports = function provisioningRoutes() {
       if (!domain) {
         return res.fail('bad_domain', 400, { reason: 'a real multi-label hostname (e.g. myproject.example.com) — no scheme, path, or bare TLD' });
       }
+      // The runner's DNS write is an UPSERT, so an attach may not claim a
+      // platform-reserved name any more than a create may (task 1002704).
+      if (provisioning.isReservedHostname(domain, instanceApex())) {
+        return res.fail('domain_reserved', {
+          status: 400,
+          message: `${domain} is a platform-reserved address — bring a domain of your own instead.`,
+        });
+      }
       const inst = await provisioning.getInstanceById(pool, id);
       if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
         return res.fail('instance_not_found', 404);
       }
+      // Same rule as create: inside the platform apex the only address an instance
+      // can hold is its own <slug>.<apex> — anything else is a squat (task 1002704).
+      const apexZone = provisioning.normalizeHostname(instanceApex());
+      const assignedDefault = provisioning.defaultDomainForSlug(inst.slug, instanceApex());
+      if (apexZone && domain.endsWith(`.${apexZone}`) && domain !== assignedDefault) {
+        return res.fail('domain_reserved', {
+          status: 400,
+          message: `Inside ${apexZone}, an instance's address is its own <handle>.${apexZone} — bring a domain you own instead.`,
+        });
+      }
       const current = provisioning.normalizeHostname(inst.domain);
       if (current && current === domain) {
         return res.json({ ok: true, changed: false, queued: false, domain: inst.domain,
           message: 'This instance already has that address.' });
       }
-      if (current) {
+      // A platform-ASSIGNED address may be upgraded away to a bring-your-own
+      // domain — that upgrade path is half the task-1002704 decision (the old
+      // record lingers in DNS, the idea-1000710 class). A genuine BYO address
+      // stays un-re-pointable, as before.
+      if (current && current !== assignedDefault) {
         return res.fail('domain_already_set', { status: 409,
           message: `This instance is already addressed as '${inst.domain}' — re-pointing an existing address is not supported here.`,
           details: { current: inst.domain } });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.121",
+  "version": "1.19.122",
   "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/projects.html

@@ -5,6 +5,10 @@
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>{{productName}} — projects</title>
 <meta name="description" content="{{tagline}} Browse the map of what is being built, manage your own projects, and start a new one.">
+<!-- the apex new projects are addressed under (server-stamped, task 1002704) —
+     the wizard's address preview reads this so it matches what the server will
+     actually assign; blank/unstamped → fall back to guessing from the host -->
+<meta name="instance-base" content="{{instanceBase}}">
 <!-- Fonts: the production instance also injects these from the branding pack
      (config/branding.json theme.ui.fonts.links); kept here so the page reads
      correctly when viewed standalone. -->
@@ -2054,6 +2058,12 @@ h1[tabindex="-1"]:focus{outline:none;}
        dotless/local host (localhost, an IP) there is nothing sane to assign, so
        the step degrades to the old optional-domain form. ── */
     function apexBase() {
+      /* the server-stamped apex wins — it is what POST /provisioning/instances
+         will actually assign; the host guess below can disagree on a subdomain
+         hub (e.g. get.<apex>) and would then preview an address that 400s */
+      var meta = document.querySelector('meta[name="instance-base"]');
+      var stamped = meta ? String(meta.content || '').toLowerCase() : '';
+      if (stamped && stamped.indexOf('{{') < 0 && stamped.indexOf('.') > 0) return stamped;
       var h = String(location.hostname || '').toLowerCase().replace(/^www\./, '');
       if (!h || h.indexOf('.') < 0) return null;
       if (/^(localhost|127\.|\d+\.\d+\.\d+\.\d+$|\[)/.test(h)) return null;
@@ -2479,6 +2489,9 @@ h1[tabindex="-1"]:focus{outline:none;}
       var code = err && err.data && err.data.error && (err.data.error.code || '');
       if (code === 'slug_taken') return 'That handle is already taken by another project. Pick a different one.';
       if (code === 'bad_slug') return 'The handle didn’t pass the server’s checks — 2–40 lowercase letters, numbers, or dashes.';
+      if (code === 'domain_reserved') return 'That address is reserved for the platform itself. Pick a different handle, or bring a domain you own.';
+      if (code === 'domain_taken') return 'That address is already held by another project. Pick a different handle or domain.';
+      if (code === 'bad_domain') return 'The domain didn’t parse as a real hostname — use something like myproject.example.com.';
       return 'Couldn’t file the request: ' + (err && err.message ? err.message : 'something went sideways. Try again.');
     }
 
@@ -2532,6 +2545,10 @@ h1[tabindex="-1"]:focus{outline:none;}
             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". */
+            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
                render (task 1002562): 'adopt' makes it clone + layer onto the repo's
@@ -2554,6 +2571,7 @@ h1[tabindex="-1"]:focus{outline:none;}
         try {
           sessionStorage.setItem(CREATED_KEY, JSON.stringify({
             id: data.instance && data.instance.id, slug: state.slug, domain: resolvedDomain(),
+            noaddr: !!state.noAddress,
             mode: state.mode, name: state.name, at: Date.now()
           }));
           sessionStorage.removeItem(DRAFT_KEY);
@@ -2973,6 +2991,9 @@ h1[tabindex="-1"]:focus{outline:none;}
            blank wizard */
         state.name = created.name || created.slug; state.slug = created.slug || '';
         state.domain = created.domain || ''; state.mode = created.mode || 'greenfield';
+        /* restore the opt-out too — without it resolvedDomain() re-derives the
+           assigned address and the done panel promises one that doesn't exist */
+        state.noAddress = !!created.noaddr;
         renderDone();
         show(6, !!focus);
         startProgress(created.id);
@@ -3155,7 +3176,21 @@ h1[tabindex="-1"]:focus{outline:none;}
     return inst.status === 'provisioning' || inst.status === 'active';
   }
   /* client mirror of provisioning.DOMAIN_ATTACH_FROM */
-  function canAttachDomain(inst) { return !inst.domain && (inst.status === 'requested' || inst.status === 'error' || inst.status === 'active'); }
+  /* the platform-assigned <slug>.<apex> for this instance, from the server-stamped
+     apex only — no host guessing here: the upgrade door below must never show for
+     an address the server would refuse to re-point (task 1002704) */
+  function assignedDefaultFor(inst) {
+    var meta = document.querySelector('meta[name="instance-base"]');
+    var base = meta ? String(meta.content || '').toLowerCase() : '';
+    if (!base || base.indexOf('{{') >= 0 || base.indexOf('.') <= 0) return null;
+    return inst.slug + '.' + base;
+  }
+  /* domainless instances get their first address; an assigned default may be
+     upgraded to a bring-your-own domain (the server allows exactly that re-point) */
+  function canAttachDomain(inst) {
+    return (!inst.domain || inst.domain === assignedDefaultFor(inst)) &&
+      (inst.status === 'requested' || inst.status === 'error' || inst.status === 'active');
+  }
   /* re-enqueue doors: Try again on snagged, Bring it back on torn down —
      both re-POST the slug (the server's PROVISION_ENQUEUE_FROM gate) */
   function canRetry(inst) { return inst.status === 'error' && !inst.open_intent; }
@@ -3292,7 +3327,8 @@ h1[tabindex="-1"]:focus{outline:none;}
     if (canAttachDomain(inst)) {
       body += '<div class="attach">' +
         '<input type="text" id="dom-' + iid + '" placeholder="myproject.example.com" autocomplete="off" spellcheck="false" maxlength="253">' +
-        '<button type="button" class="btn small" data-attach="' + iid + '">Give it an address</button></div>';
+        '<button type="button" class="btn small" data-attach="' + iid + '">' +
+        (inst.domain ? 'Use your own domain' : 'Give it an address') + '</button></div>';
     }
     if (inst.status === 'error' && !inst.open_intent) {
       /* once a retry is queued the strip tells the story — the stale error

package/scripts/gds/init.js

@@ -521,7 +521,7 @@ async function interview({ adopt = false } = {}) {
     const wantProv = (await ask(rl, '  Provision production hosting now? (y/N)', 'N')).toLowerCase();
     if (wantProv === 'y' || wantProv === 'yes') {
       const shape = (await ask(rl, '  Hosting shape? (co-tenant = share an existing box, $0 / dedicated = its own droplet / standalone = its own repo + pinned @bongos/core, ADR 0108)', 'co-tenant')).toLowerCase();
-      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = none yet)?');
+      const domain = await ask(rl, '  Domain you own — bring-your-own (blank = the platform assigns <slug>.<its apex> when configured)?');
       const targetRef = await ask(rl, '  Target credential ref? (which control-plane creds the runner should use; optional)');
       let tier = '';
       if (shape === 'dedicated') tier = await ask(rl, '  Droplet tier? (e.g. s-1vcpu-2gb; optional)');
@@ -780,7 +780,13 @@ async function seedViaApi(spec, { dryRun, log = console.log, api = apiCall } = {
       provisioned = true;
       const inst = (pres.data && pres.data.instance) || {};
       const cost = Number(inst.cost_estimate_usd || 0);
-      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${pr.domain ? `, ${pr.domain}` : ''})` +
+      // Report the ROW's domain, not the request's: the server may have
+      // auto-assigned <slug>.<instanceBase> to a domainless request (task
+      // 1002704) — the operator must hear the address they actually got.
+      const addr = inst.domain
+        ? `, ${inst.domain}${pr.domain ? '' : ' (auto-assigned — attach your own domain any time to replace it)'}`
+        : ', no address yet';
+      log(`  ✓ requested provisioning of instance "${pr.slug}" (${pr.hosting_shape}${addr})` +
           `${cost ? ` — est. $${cost}/mo` : ''} — a provision intent is queued for the control-plane runner`);
     } else {
       const why = pres.status === 404

package/scripts/gds/onboard.js

@@ -88,7 +88,7 @@ async function run() {
     a.repoName = await ask(rl, 'GitHub repo name?');
     a.firstAdmin = await ask(rl, 'First admin (GitHub login — the founding Archon)?', a.repoOwner);
     a.slug = await ask(rl, 'Instance slug? (DNS/db-safe, e.g. mercury)');
-    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = decide later)?');
+    a.domain = await ask(rl, 'Domain you own (bring-your-own; blank = the platform assigns <slug>.<its apex> when configured)?');
 
     // Step 2 — human: the GitHub repo (create empty for greenfield; use existing for adopt)
     if (adopt) {

package/src/bongos/serve-internal.js

@@ -162,7 +162,7 @@ function injectBrandingGlobal(html, brand = clientBranding(), mods = clientModul
 // fill cannot reach them, and a baked one would make every instance advertise
 // whichever instance happened to author the file (task 1002748, direction C5/C6).
 // Pure + exported for the test; both origins are injectable so it drives with zero I/O.
-function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOrigin(), hallOrigin = safeBuildersOrigin(), sourceRepo = safeSourceRepoUrl()) {
+function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOrigin(), hallOrigin = safeBuildersOrigin(), sourceRepo = safeSourceRepoUrl(), instanceBase = safeInstanceBase()) {
   const world = (brand.identity && brand.identity.worldName) || '';
   const product = (brand.identity && brand.identity.productName) || '';
   const tagline = (brand.copy && brand.copy.tagline) || '';
@@ -178,7 +178,8 @@ function applyBrandTokens(html, brand = clientBranding(), origin = safePublicOri
     // a pack that names no hall of its own resolves to its OWN apex — never to
     // whichever instance authored the file
     .split('{{buildersOrigin}}').join(esc(hallOrigin || origin || ''))
-    .split('{{sourceRepoUrl}}').join(esc(sourceRepo || ''));
+    .split('{{sourceRepoUrl}}').join(esc(sourceRepo || ''))
+    .split('{{instanceBase}}').join(esc(instanceBase || ''));
 }
 // Every token lands in HTML — as element text, or inside a double-quoted
 // attribute (href/content). Escaping is defence in depth, not a live fix: the
@@ -206,6 +207,14 @@ function safePublicOrigin() {
 function safeBuildersOrigin() {
   try { return branding().domains.buildersOrigin || ''; } catch { return ''; }
 }
+// The apex new projects get their auto-assigned <slug>.<apex> address under
+// (task 1002704) — same server-only `domains` source. Stamped into markup (a
+// <meta> content attribute, never a <script>) so the create wizard's address
+// preview matches what the server will actually assign instead of guessing
+// from location.hostname. Empty = no auto-assign; the wizard falls back.
+function safeInstanceBase() {
+  try { return branding().domains.instanceBase || ''; } catch { return ''; }
+}
 // The instance's own source repo, from the pack's `repo: {owner, name}` binding —
 // another server-only field (the branding contract keeps repo off clientBranding
 // alongside domains). A page that wants to link "read the source" must take it

package/src/module-api.js

@@ -669,8 +669,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.119 with no explicit bump. run 31836959112. (task 1002620)
 //   1.19.121 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.120 with no explicit bump. run 31838955115. (task 1002620)
+//   1.19.122 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.121 with no explicit bump. run 31840810826. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.121'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.122'; // 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/provisioning_default_domain.mjs

@@ -0,0 +1,331 @@
+// tests/provisioning_default_domain.mjs
+//
+// Auto-assign at creation (task 1002704, the owner's 2026-08-12 decision): every
+// new project gets <slug>.<instanceBase> at creation so its hall is reachable day
+// one; `no_address: true` is the explicit opt-out; an explicit body.domain
+// (bring-your-own) wins. Also closes the create path's validation gap — the
+// attach route normalized + uniqueness-checked its domain (task 1002692) while
+// create inserted body.domain raw — and adds the reserved-name guard that keeps
+// a project slug ('www', 'get', …) from UPSERTing over the platform's own DNS
+// once every create carries an address.
+//
+// Covers:
+//   • defaultDomainForSlug / isReservedHostname — the pure helpers
+//   • POST /provisioning/instances — assign-by-default, opt-out, BYO-wins,
+//     bad_domain, domain_taken, domain_reserved, blank-apex degradation,
+//     re-request honesty (no phantom domain_ignored from the derived default;
+//     no_address_ignored when the opt-out can't apply)
+//   • POST /provisioning/instances/:id/domain — the same reserved-name refusal
+//
+// DB-free: data-access fns are stubbed on the cached module object (the
+// provisioning_domain_attach.mjs harness). No network.
+//
+// Run:  node tests/provisioning_default_domain.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;
+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}`); }
+}
+
+console.log('pure helpers — defaultDomainForSlug / isReservedHostname:');
+
+t('defaultDomainForSlug: <slug>.<apex>, normalized', () => {
+  assert.equal(provisioning.defaultDomainForSlug('spike', 'cloudbongos.com'), 'spike.cloudbongos.com');
+  assert.equal(provisioning.defaultDomainForSlug('spike', 'CloudBongos.com.'), 'spike.cloudbongos.com');
+});
+
+t('defaultDomainForSlug: blank/absent apex → null (self-host degrades to domainless)', () => {
+  assert.equal(provisioning.defaultDomainForSlug('spike', ''), null);
+  assert.equal(provisioning.defaultDomainForSlug('spike', null), null);
+  assert.equal(provisioning.defaultDomainForSlug('spike', undefined), null);
+});
+
+t('defaultDomainForSlug: invalid slug or unparseable apex → null', () => {
+  assert.equal(provisioning.defaultDomainForSlug('', 'cloudbongos.com'), null);
+  assert.equal(provisioning.defaultDomainForSlug('-bad-', 'cloudbongos.com'), null);
+  assert.equal(provisioning.defaultDomainForSlug('spike', '???'), null);
+});
+
+t('isReservedHostname: platform labels + box prefixes under the apex are reserved', () => {
+  for (const h of ['www.cloudbongos.com', 'get.cloudbongos.com', 'status.cloudbongos.com',
+    'term-alice.cloudbongos.com', 'sandbox-bob.cloudbongos.com', 'cloudbongos.com']) {
+    assert.equal(provisioning.isReservedHostname(h, 'cloudbongos.com'), true, `${h} should be reserved`);
+  }
+});
+
+t('isReservedHostname: ordinary one-label projects and foreign zones are not reserved', () => {
+  assert.equal(provisioning.isReservedHostname('spike.cloudbongos.com', 'cloudbongos.com'), false);
+  assert.equal(provisioning.isReservedHostname('www.example.com', 'cloudbongos.com'), false, 'BYO on a foreign zone is fine');
+  assert.equal(provisioning.isReservedHostname('spike.cloudbongos.com', ''), false, 'no apex configured → nothing to protect');
+});
+
+t('isReservedHostname: deeper than one label under the apex is reserved (breaks the wildcard cert; nothing legitimate creates it)', () => {
+  assert.equal(provisioning.isReservedHostname('a.b.cloudbongos.com', 'cloudbongos.com'), true);
+});
+
+// ── the create route, over a real mounted router (stubbed data access) ───────────
+let domainHolder = null;         // what getInstanceByDomain returns
+let existingRow = null;          // what getInstanceBySlug returns (re-request tests)
+let createCalls = [];            // what createInstance was asked to insert
+let createResult = null;         // what createInstance reports
+let enqueueCalls = [];
+provisioning.getInstanceByDomain = async (_db, _d) => domainHolder;
+provisioning.getInstanceBySlug = async (_db, _s) => existingRow;
+provisioning.getInstanceById = async () => null;
+provisioning.updateInstanceDomain = async (_db, id, domain) => ({ id, domain });
+provisioning.createInstance = async (_db, args) => { createCalls.push(args); return createResult; };
+provisioning.enqueueIntent = async (_db, id, action, requestedBy) => {
+  enqueueCalls.push({ id, action, requestedBy });
+  return { intent: { id: 9, action, state: 'pending' }, created: true };
+};
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+
+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();
+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');
+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());
+
+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 post(path, body = {}) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    }, (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 }); });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+const freshRow = (over = {}) => ({
+  id: 41, owner_builder_id: 7, slug: 'spike', status: 'requested', hosting_shape: 'standalone',
+  domain: 'spike.cloudbongos.com', onboard_mode: 'greenfield', type: null, created_at: '', updated_at: '', ...over,
+});
+
+function reset() {
+  domainHolder = null;
+  existingRow = null;
+  createCalls = [];
+  enqueueCalls = [];
+  createResult = { instance: freshRow(), created: true };
+}
+
+console.log('\nPOST /provisioning/instances — auto-assign, opt-out, BYO wins:');
+
+await ta('no domain in the body → the assigned <slug>.<instanceBase> is created (the API-first gap, N2)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(createCalls[0].domain, 'spike.cloudbongos.com');
+});
+
+await ta('no_address: true → deliberately domainless (the opt-out survives the server default)', async () => {
+  reset();
+  createResult = { instance: freshRow({ domain: null }), created: true };
+  const res = await post('/provisioning/instances', { slug: 'spike', no_address: true });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(createCalls[0].domain == null, true, 'no domain may be assigned');
+});
+
+await ta('an explicit domain (bring-your-own) wins over the default, normalized', async () => {
+  reset();
+  createResult = { instance: freshRow({ domain: 'spike.example.com' }), created: true };
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'Spike.Example.com.' });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(createCalls[0].domain, 'spike.example.com');
+});
+
+await ta('a malformed explicit domain → 400 bad_domain, nothing created (create now matches attach)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'not a hostname' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_domain');
+  assert.equal(createCalls.length, 0);
+});
+
+await ta("an address held by ANOTHER instance → 409 domain_taken (create had no uniqueness check)", async () => {
+  reset();
+  domainHolder = freshRow({ id: 99, slug: 'other' });
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_taken');
+  assert.equal(createCalls.length, 0);
+});
+
+await ta('the holder being this slug’s own row (a re-request) is not a collision', async () => {
+  reset();
+  domainHolder = freshRow();
+  createResult = { instance: freshRow(), created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 200, res.raw);
+});
+
+await ta('a BYO domain under the apex that is not the slug’s own address → 400 (squat on another handle)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'victim.cloudbongos.com' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'domain_reserved');
+  assert.equal(createCalls.length, 0);
+});
+
+await ta('an explicit domain equal to the slug’s own assigned address is fine (the wizard sends exactly this)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(createCalls[0].domain, 'spike.cloudbongos.com');
+});
+
+await ta('a reserved label under the apex → 400 domain_reserved (auto-assign path)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'www' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'domain_reserved');
+  assert.equal(createCalls.length, 0);
+});
+
+await ta('a reserved hostname as BYO → 400 domain_reserved (same guard, explicit path)', async () => {
+  reset();
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'GET.cloudbongos.com' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'domain_reserved');
+});
+
+await ta('a reserved slug WITH no_address is fine — no hostname is being claimed', async () => {
+  reset();
+  createResult = { instance: freshRow({ slug: 'www', domain: null }), created: true };
+  const res = await post('/provisioning/instances', { slug: 'www', no_address: true });
+  assert.equal(res.status, 201, res.raw);
+});
+
+await ta('blank instanceBase (self-host / unconfigured) → domainless create, no guessing', async () => {
+  reset();
+  brandingDomains = { publicOrigin: 'http://localhost:3000' };
+  createResult = { instance: freshRow({ domain: null }), created: true };
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(createCalls[0].domain == null, true, 'no apex → nothing to assign');
+  brandingDomains = { publicOrigin: 'https://cb.test', instanceBase: 'cloudbongos.com' };
+});
+
+console.log('\nre-requests skip the birth-time guards (Try again / Bring it back must keep working):');
+
+await ta('a re-request of an EXISTING reserved-label row → 200 with its provision intent (not domain_reserved)', async () => {
+  reset();
+  existingRow = freshRow({ slug: 'demo', domain: 'demo.cloudbongos.com', status: 'error' });
+  createResult = { instance: existingRow, created: false };
+  const res = await post('/provisioning/instances', { slug: 'demo', domain: 'demo.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.deepEqual(enqueueCalls.map((c) => c.action), ['provision'], "the 'error' row re-enqueues its provision intent");
+});
+
+await ta('a re-request is never 409ed against its own (or anyone’s) address — createInstance won’t write one', async () => {
+  reset();
+  existingRow = freshRow();
+  domainHolder = freshRow({ id: 99, slug: 'other' });
+  createResult = { instance: freshRow(), created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 200, res.raw);
+});
+
+console.log('\nre-request honesty:');
+
+await ta('a re-request with NO explicit domain never reports domain_ignored (the derived default is not an ask)', async () => {
+  reset();
+  createResult = { instance: freshRow({ domain: 'custom.example.com' }), created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.domain_ignored, undefined);
+});
+
+await ta('a re-request with an explicit different domain still reports domain_ignored', async () => {
+  reset();
+  createResult = { instance: freshRow({ domain: 'custom.example.com' }), created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike', domain: 'spike.other.org' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.domain_ignored.requested, 'spike.other.org');
+});
+
+await ta("a re-request with no_address on an addressed instance says so (no_address_ignored)", async () => {
+  reset();
+  domainHolder = freshRow();
+  createResult = { instance: freshRow(), created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike', no_address: true });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.no_address_ignored.current, 'spike.cloudbongos.com');
+});
+
+console.log('\nPOST /provisioning/instances/:id/domain — the reserved guard applies to attach too:');
+
+await ta('attaching a reserved hostname under the apex → 400 domain_reserved', async () => {
+  reset();
+  provisioning.getInstanceById = async (_db, id) => freshRow({ id, domain: null, status: 'active' });
+  const res = await post('/provisioning/instances/41/domain', { domain: 'www.cloudbongos.com' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'domain_reserved');
+});
+
+await ta('attaching another handle’s address under the apex → 400 (squat, same rule as create)', async () => {
+  reset();
+  provisioning.getInstanceById = async (_db, id) => freshRow({ id, domain: null, status: 'active' });
+  const res = await post('/provisioning/instances/41/domain', { domain: 'victim.cloudbongos.com' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'domain_reserved');
+});
+
+console.log('\nthe assigned default may be upgraded to a bring-your-own domain (the decision’s upgrade path):');
+
+await ta('re-pointing AWAY from the platform-assigned address → recorded + domain-attach intent', async () => {
+  reset();
+  provisioning.getInstanceById = async (_db, id) => freshRow({ id, domain: 'spike.cloudbongos.com', status: 'active' });
+  const res = await post('/provisioning/instances/41/domain', { domain: 'spike.example.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.domain, 'spike.example.com');
+  assert.deepEqual(enqueueCalls.map((c) => c.action), ['domain-attach']);
+});
+
+await ta('a genuine bring-your-own address still refuses to re-point (unchanged)', async () => {
+  reset();
+  provisioning.getInstanceById = async (_db, id) => freshRow({ id, domain: 'spike.example.com', status: 'active' });
+  const res = await post('/provisioning/instances/41/domain', { domain: 'another.example.com' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_already_set');
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provisioning_domain_attach.mjs

@@ -91,6 +91,7 @@ provisioning.enqueueIntent = async (_db, id, action, requestedBy) => {
 };
 provisioning.getOpenIntent = async () => null;
 provisioning.createInstance = async () => createResult;
+provisioning.getInstanceBySlug = async () => null;   // the task-1002704 birth-time pre-check
 provisioning.recordEvent = async () => {};
 provisioning.createOAuthManifest = async (_db, row) => { manifestRows.push(row); return { id: 1, ...row }; };
 provisioning.getLatestOAuthManifestForInstance = async () => null;

package/tests/provisioning_teardown_intent.mjs

@@ -148,6 +148,7 @@ provisioning.enqueueIntent = async (_db, id, action, requestedBy) => {
 };
 provisioning.getOpenIntent = async () => null;
 provisioning.createInstance = async () => createResult;
+provisioning.getInstanceBySlug = async () => null;   // the task-1002704 birth-time pre-check
 provisioning.recordEvent = async () => {};
 
 const api = require('../src/module-api.js');