@bongos/core 1.19.60 → 1.19.61

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.60",
-  "core_contract": "1.19.60",
-  "source_commit": "ce8873473b894cf991da712833f18dc9e5f3f88c",
+  "core_version": "1.19.61",
+  "core_contract": "1.19.61",
+  "source_commit": "073b10995781fbdfae0a9da943fa8755002e51bf",
   "source_ref": "HEAD",
-  "built_at": "2026-08-11T23:51:23.264Z",
+  "built_at": "2026-08-12T00:24:52.611Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 291,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1218,
+    "functional_verbatim": 1220,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1530,
-  "tree_sha256": "acefccdf8f346aff9dfc425d717f82bc3d87cc5c680d303bd19ffc334dc9b195",
+  "file_count": 1532,
+  "tree_sha256": "c4d2ff9c96e88bf23e2c2c1acf1593d174589a1b9beeb7b3b12d61c65bb84113",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -347,12 +347,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "8aeb1aaf87db169788d5e17a671846526a1c89f184ee6ff0425730ecea71fb8a"
+      "sha256": "36eb537043097dc8e05307adc06d893a2c5ceb8cceb63f24b64ade001a0a2640"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "724bfb1a3647a316226f32b1b62f56e30dba8df28a2ccfadb1dcbaaff65e7197"
+      "sha256": "ad598bf38511e3e7bd9f25a82987126cd71cfe76ac8275ddee2bcd90eb8e6a11"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -362,17 +362,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "e4efb5ad8e209a5c27c9a85f42e920915a7d7b91491197b03a52f85091319247"
+      "sha256": "43823273ec587b104f3e0296614ae8ea6c4dc5c96261dbbb359ae39c21cf4e79"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "34b9ebfa393ad892c959bf356c1727188e71c61a8ff9ee0d0eca66433a51614e"
+      "sha256": "4deeae55ba58483557310d768a63df7cd75a1219137539b7ccbbf4481f09f5d9"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "ff501fe93dd31785d2acb8e55c9b664128065d7acf2862fb91af0800274619de"
+      "sha256": "6d441799f948513f840394bd382dba7e601e79a07fb7591bcb0e05aea2edd2a9"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1307,12 +1307,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "27e9c0ab46db5386833b9e03bcff0dae31f4606882e845e7e830f9ef6f2550b5"
+      "sha256": "a30007778606ce90b8e31470d926047a372c72b93022f54023937cfd4c5b5fc0"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "bad0bdd6cdd07d66ed8b3bbc2bb2751ce1d6a0a819bc2d455952f5b0c18cea64"
+      "sha256": "0e7646ee148453ef5d6d51b3434253b76f35628ee6c36681dbf6e7b27dd20c6f"
     },
     {
       "path": "docs/architecture.md",
@@ -2552,7 +2552,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "e4efb5ad8e209a5c27c9a85f42e920915a7d7b91491197b03a52f85091319247"
+      "sha256": "43823273ec587b104f3e0296614ae8ea6c4dc5c96261dbbb359ae39c21cf4e79"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -3719,6 +3719,11 @@
       "mode": "0000644",
       "sha256": "c25101daed13fc22ba3f132b2dac59c782fa564fa4bc22a6a5169e6644109b3a"
     },
+    {
+      "path": "modules/provisioning/migrations/provisioning_005_domain_attach.sql",
+      "mode": "0000644",
+      "sha256": "230e8a9df147495ee5113c1400c582e9e39e3286baab7e01ce7684e1b1c7860c"
+    },
     {
       "path": "modules/provisioning/module.json",
       "mode": "0000644",
@@ -3732,7 +3737,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "655d7e07f8a50cd12420c67e0cb12ff4f94098e53b218b0985f866b9433e409f"
+      "sha256": "48c047c48579a1cb5cc6b36c2148bcab5c1736a16c4c73c0741a8998bfe922cd"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -3742,7 +3747,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "c0a1a015e20c446513ae435075379e1c46cfe0e492574ff9f64d9ef39b081e4b"
+      "sha256": "a490a4b4b607a302533bac6fedbc39a0153d57e35a086bcc20079fbefc6815e5"
     },
     {
       "path": "modules/provisioning/tests/provisioning.mjs",
@@ -4032,12 +4037,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "862808e3b9e59ac80baa7bcdda60a08dc8f0f31152750ea99264a5aac24c1140"
+      "sha256": "9b320dfef27bca09c1ab23bb85c04b499724208dad01a608763f18b9c4e1d1b4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "51b6e2905a863ad6c9d25eecf376a8db1f61ee960e00dd5b12f4d5aefcf36625"
+      "sha256": "d1720c6790a6aa61a091335cf8873dac1e75dfbb1250c7d484395c95fd8825c6"
     },
     {
       "path": "public-docs/index.html",
@@ -5007,7 +5012,7 @@
     {
       "path": "scripts/gds/provision.js",
       "mode": "0000644",
-      "sha256": "93a5c4a6d6f76cf1fa8ca4c902b19d6ef94f9147488f1c01d3413f692a196942"
+      "sha256": "e4108117dbe8dd6493ba41ed053fe8648424ca127b1c26505aa6f6702b2dd94c"
     },
     {
       "path": "scripts/gds/publish-manifest.js",
@@ -5657,7 +5662,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "dd71e36bfd25965ca6b720f1fdbd94ba47553260915176d693f5246fdaac8d2e"
+      "sha256": "0126fe1e9af95f3daee985c7a9859e19b5937e023d6a54927b6c5dd7055a83ec"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -7137,7 +7142,12 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "6f47c2a9c43fbef9b26090c9ca794a67bbca279f5bc79db625f26fa43775d4b7"
+      "sha256": "bd8e111c2d5614f79086c5f8298cec6ffdcb7ab57b94565457520d85df0c24a8"
+    },
+    {
+      "path": "tests/provisioning_domain_attach.mjs",
+      "mode": "0000644",
+      "sha256": "241e1b208abbd54a625af050d541344186d93806846a1e7f1cbb0f93dfbab802"
     },
     {
       "path": "tests/provisioning_github_app_routes.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`)
-- 268 operations across 45 resource groups
+- 269 operations across 45 resource groups
 
 ## Install
 

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

@@ -523,6 +523,8 @@ function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
+      postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app

package/clients/bongos-client/index.cjs

@@ -522,6 +522,8 @@ function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
+      postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app

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

@@ -246,6 +246,8 @@ export interface PostOverrideRequestsIdDecideRequest { decision: string; note?:
 export interface PostProjectsInviteRequest { client_id: string; github_login: string }
 export interface PostProjectsRequest { origin: string; name: string; tagline?: string; art_url?: string }
 export interface PostProjectsResponse { project: unknown }
+export interface PostProvisioningInstancesIdDomainRequest { domain: string }
+export interface PostProvisioningInstancesIdDomainResponse { ok: boolean; changed: boolean; queued: unknown; domain: unknown; message: unknown }
 export interface PostProvisioningInstancesIdForceTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; superseded: unknown; message: unknown }
 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 }
@@ -756,6 +758,8 @@ export interface BongosClient {
     postProvisioningInstances(args: RequestArgs & { body: PostProvisioningInstancesRequest }): Promise<ApiResponse>;
     /** GET /provisioning/instances/{id} — rank: any-builder */
     getProvisioningInstancesId(args?: RequestArgs): Promise<GetProvisioningInstancesIdResponse>;
+    /** POST /provisioning/instances/{id}/domain — rank: any-builder */
+    postProvisioningInstancesIdDomain(args: RequestArgs & { body: PostProvisioningInstancesIdDomainRequest }): Promise<PostProvisioningInstancesIdDomainResponse>;
     /** POST /provisioning/instances/{id}/force-teardown — rank: metic+archon */
     postProvisioningInstancesIdForceTeardown(args?: RequestArgs): Promise<PostProvisioningInstancesIdForceTeardownResponse>;
     /** POST /provisioning/instances/{id}/github-app — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -519,6 +519,8 @@ export function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
+      postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app

package/docs/api/openapi.json

@@ -8493,6 +8493,69 @@
         ]
       }
     },
+    "/provisioning/instances/{id}/domain": {
+      "post": {
+        "operationId": "post_provisioning_instances_id_domain",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "POST /provisioning/instances/:id/domain",
+        "description": "POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domain after creation). Validates + records the domain; for an already-ACTIVE instance it also enqueues a 'domain-attach' intent the control-plane runner drains (web tier holds no cloud tokens — ADR 0111 §2). A requested/error instance only records it: the (re)provision run wires the domain itself. Re-pointing an existing address is out of scope — refuse truthfully. Body: { domain (required) }.\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",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `id`."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostProvisioningInstancesIdDomainRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostProvisioningInstancesIdDomainResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/provisioning/instances/{id}/force-teardown": {
       "post": {
         "operationId": "post_provisioning_instances_id_force_teardown",
@@ -15628,6 +15691,40 @@
           "project"
         ]
       },
+      "PostProvisioningInstancesIdDomainRequest": {
+        "type": "object",
+        "properties": {
+          "domain": {
+            "type": "string",
+            "maxLength": 253
+          }
+        },
+        "required": [
+          "domain"
+        ],
+        "additionalProperties": false
+      },
+      "PostProvisioningInstancesIdDomainResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "changed": {
+            "type": "boolean"
+          },
+          "queued": {},
+          "domain": {},
+          "message": {}
+        },
+        "required": [
+          "ok",
+          "changed",
+          "queued",
+          "domain",
+          "message"
+        ]
+      },
       "PostProvisioningInstancesIdForceTeardownResponse": {
         "type": "object",
         "properties": {
@@ -16875,9 +16972,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 268,
-  "x-schema-count": 300,
+  "x-endpoint-count": 269,
+  "x-schema-count": 302,
   "x-undocumented-bodies": 8,
-  "x-response-schemas": 203,
+  "x-response-schemas": 204,
   "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. 268 endpoints across 44 route files.
+> **Generated from the live route files** — the route file is authoritative. 269 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` (13)
+## `provisioning` (14)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -370,6 +370,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | 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` | 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. |
 | 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. |

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

@@ -522,6 +522,8 @@ function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
+      postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown
       postProvisioningInstancesIdForceTeardown: (args) => request("POST", "/provisioning/instances/{id}/force-teardown", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/github-app — rank: any-builder — POST /provisioning/instances/:id/github-app

package/modules/provisioning/migrations/provisioning_005_domain_attach.sql

@@ -0,0 +1,20 @@
+-- provisioning_005_domain_attach.sql — the domain-attach intent action
+-- (task 1002692, gap 5 of the creation-flow audit / idea 1000677).
+--
+-- WHY. No path existed to give an EXISTING instance its address: a slug re-request
+-- silently dropped the domain in the body, and a domainless instance stayed
+-- domainless forever — which also blocked GitHub sign-in (the github-app manifest
+-- route requires a domain). The new owner-scoped POST /provisioning/instances/:id/
+-- domain records the domain and, for an already-ACTIVE instance, enqueues a
+-- 'domain-attach' intent; the control-plane runner (the sole token-holder, ADR 0111
+-- §2) re-asserts the domain-dependent standup legs (web.env origins + service
+-- restart, Cloudflare A-record UPSERT, Caddy snippet + reload, healthz). The web
+-- tier still only ENQUEUES — the trust boundary is unchanged.
+--
+-- Widening a CHECK enum is additive (permits MORE values; no row changes) — the
+-- provisioning_003 precedent. Applied only when the provisioning module is enabled.
+-- Safe to re-run. Keep INTENT_ACTIONS in provisioning.js in lockstep.
+
+ALTER TABLE provisioning_intents DROP CONSTRAINT IF EXISTS provisioning_intents_action_check;
+ALTER TABLE provisioning_intents ADD CONSTRAINT provisioning_intents_action_check
+  CHECK (action IN ('provision', 'teardown', 'oauth-manifest', 'domain-attach'));

package/modules/provisioning/provisioning.js

@@ -33,7 +33,10 @@ const ONBOARD_MODES = ['greenfield', 'adopt'];
 // conversion. Today the runner drains it by scanning provisioning_oauth_manifests
 // (drainOAuthManifests), not the intent queue, but it stays a valid action so the
 // widened CHECK (migration provisioning_003) and this list never drift.
-const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest'];
+// 'domain-attach' (task 1002692, migration provisioning_005): re-assert the
+// domain-dependent standup legs for an already-ACTIVE instance that was just
+// given its address via POST /provisioning/instances/:id/domain.
+const INTENT_ACTIONS = ['provision', 'teardown', 'oauth-manifest', 'domain-attach'];
 // The states from which a teardown is meaningful (there is something to reclaim).
 // Mirrors dev-box canTransition('deprovision', …): a requested/torn_down/error
 // instance has nothing running to tear down via the happy path.
@@ -44,6 +47,11 @@ const TEARDOWN_FROM = new Set(['provisioning', 'active', 'tearing_down']);
 // teardown on the action-blind ux_provisioning_intents_open (task 1002691);
 // 'tearing_down' is mid-reclaim (any open slot belongs to the teardown).
 const PROVISION_ENQUEUE_FROM = new Set(['requested', 'provisioning', 'error', 'torn_down']);
+// The states from which attaching a domain is meaningful (task 1002692): 'active'
+// needs a 'domain-attach' intent (the runner re-asserts the domain legs);
+// 'requested'/'error' only record it — the (re)provision run wires the domain
+// itself. Mid-flight or torn-down states refuse truthfully.
+const DOMAIN_ATTACH_FROM = new Set(['requested', 'error', 'active']);
 
 // Monthly cost estimate (USD) for a dedicated droplet tier — VISIBILITY only
 // (ADR 0111 §6), never a bill. A small local table so this module needs no
@@ -254,6 +262,29 @@ async function getInstanceBySlug(db, slug) {
   return rows[0] || null;
 }
 
+// The instance currently holding `domain` (case-insensitive), if any — backs the
+// domain-attach route's uniqueness check so one owner's address can never silently
+// shadow another's (task 1002692). Caller normalizes; matching is defensive anyway.
+async function getInstanceByDomain(db, domain) {
+  if (!domain) return null;
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_instances WHERE lower(domain) = $1 LIMIT 1`,
+    [String(domain).toLowerCase()]
+  );
+  return rows[0] || null;
+}
+
+// Record an instance's domain — the ONLY column this touches (task 1002692). Status
+// changes stay setInstanceStatus's job; keeping this narrow means the domain-attach
+// route can never drift an instance's lifecycle as a side effect.
+async function updateInstanceDomain(db, id, domain) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances SET domain = $2, updated_at = now() WHERE id = $1 RETURNING *`,
+    [id, domain]
+  );
+  return rows[0] || null;
+}
+
 // The caller's own instances, newest first.
 async function listInstancesForOwner(db, ownerBuilderId) {
   const { rows } = await db.query(
@@ -571,15 +602,15 @@ async function costLedger(db, { limit = 500 } = {}) {
 module.exports = {
   // constants
   INSTANCE_STATES, HOSTING_SHAPES, ONBOARD_MODES, INTENT_ACTIONS, TEARDOWN_FROM,
-  PROVISION_ENQUEUE_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
+  PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl,
   // data access
   isProvisionedHostname,
-  getInstanceById, getInstanceBySlug, listInstancesForOwner, listAllInstances,
-  createInstance, setInstanceStatus,
+  getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
+  createInstance, setInstanceStatus, updateInstanceDomain,
   enqueueIntent, enqueueTeardown, getOpenIntent, claimNextIntent, resolveIntent,
   recordEvent, instanceStateForSlug, costLedger,
   // data access — GitHub App Manifest attempts (task 2080)

package/modules/provisioning/routes/provisioning.js

@@ -361,11 +361,24 @@ module.exports = function provisioningRoutes() {
           actor: 'api:self',
         }).catch(() => {});
       }
+      // A re-request cannot change an existing instance's domain — SAY so instead of
+      // silently dropping it (task 1002692); the domain route is the real path.
+      let domainIgnored;
+      if (!created && body.domain) {
+        const asked = provisioning.normalizeHostname(body.domain);
+        if (asked && asked !== provisioning.normalizeHostname(instance.domain)) {
+          domainIgnored = {
+            requested: asked, current: instance.domain || null,
+            hint: `a re-request never changes an existing instance's address — POST /provisioning/instances/${instance.id}/domain instead`,
+          };
+        }
+      }
       res.status(created ? 201 : 200).json({
         instance: provisioning.publicInstance(instance),
         open_intent: intent ? { action: intent.action, state: intent.state } : null,
         queued: intentCreated,
         created,
+        ...(domainIgnored ? { domain_ignored: domainIgnored } : {}),
       });
     } catch (err) {
       console.error('[provisioning] POST /provisioning/instances', err);
@@ -454,6 +467,84 @@ module.exports = function provisioningRoutes() {
     }
   });
 
+  // POST /provisioning/instances/:id/domain — give the caller's OWN instance its
+  // address (task 1002692, gap 5: no path existed to add a domain after creation).
+  // Validates + records the domain; for an already-ACTIVE instance it also enqueues
+  // a 'domain-attach' intent the control-plane runner drains (web tier holds no
+  // cloud tokens — ADR 0111 §2). A requested/error instance only records it: the
+  // (re)provision run wires the domain itself. Re-pointing an existing address is
+  // out of scope — refuse truthfully. Body: { domain (required) }.
+  router.post('/provisioning/instances/:id/domain', auth.requireBuilder, async (req, res) => {
+    const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
+    if (!id) return;
+    if (validateOrRespond(req, res, { domain: { required: true, type: 'string', maxLength: 253 } })) return;
+    try {
+      const domain = provisioning.normalizeHostname((req.body || {}).domain);
+      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' });
+      }
+      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);
+      }
+      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) {
+        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 } });
+      }
+      const holder = await provisioning.getInstanceByDomain(pool, domain);
+      if (holder && String(holder.id) !== String(inst.id)) {
+        return res.fail('domain_taken', { status: 409, message: 'That address is already in use by another instance.' });
+      }
+      if (!provisioning.DOMAIN_ATTACH_FROM.has(inst.status)) {
+        return res.fail('domain_not_attachable', { status: 409,
+          message: `Instance is '${inst.status}' — an address can be attached once it settles ('active') or before standup ('requested').`,
+          details: { status: inst.status } });
+      }
+      // Record BEFORE enqueueing: the runner reads the row's domain, so the intent
+      // must never race ahead of the column it wires.
+      await provisioning.updateInstanceDomain(pool, id, domain);
+      let queued = false;
+      if (inst.status === 'active') {
+        const { intent, created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', 'api:self');
+        if (!created && intent.action !== 'domain-attach') {
+          // The open slot is held by other work (e.g. a teardown). The address IS
+          // recorded — say exactly what happened and what to do.
+          return res.fail('intent_conflict', { status: 409,
+            message: `The address was recorded, but a '${intent.action}' run is currently ${intent.state} for this instance — re-send this request once it settles to wire the address.`,
+            details: { action: intent.action, state: intent.state, recorded: true } });
+        }
+        queued = created;
+        if (!created) {
+          // an identical attach is already open — idempotent
+          await provisioning.recordEvent(pool, {
+            instanceId: id, ownerBuilderId: req.builder.id, event: 'domain',
+            detail: `domain ${domain} recorded (attach already queued)`, actor: 'api:self',
+          }).catch(() => {});
+          return res.json({ ok: true, changed: true, queued: false, domain,
+            message: 'That address is already being wired for this instance.' });
+        }
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: req.builder.id, event: 'domain',
+        detail: queued ? `domain ${domain} recorded + attach queued` : `domain ${domain} recorded (wired at provision)`,
+        actor: 'api:self',
+      }).catch(() => {});
+      res.json({ ok: true, changed: true, queued, domain,
+        message: queued
+          ? 'Your instance is being wired to its new address — it will answer there shortly.'
+          : 'Address recorded — it will be wired when the instance is provisioned.' });
+    } catch (err) {
+      console.error('[provisioning] POST /provisioning/instances/:id/domain', err);
+      res.fail('domain_attach_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding
   // link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated
   // builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target

package/package-lock.json

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

package/package.json

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

package/scripts/gds/provision.js

@@ -1510,6 +1510,90 @@ runcmd:
 `;
 }
 
+// ---------------------------------------------------------------------------
+// Attach a late-arriving domain to an ALREADY-ACTIVE instance (task 1002692):
+// re-assert exactly the domain-dependent runbook legs — web.env origins (+ a
+// service RESTART so the process re-reads them), the Cloudflare A-record UPSERT
+// (step 5), the Caddy site snippet (step 6) — then healthz. Expected failures
+// RETURN { ok:false } instead of throwing: the drain loop's catch flips the
+// instance to 'error', which must never happen to a healthy ACTIVE instance
+// over a domain hiccup.
+// ---------------------------------------------------------------------------
+async function domainAttachInstance(inst, deps) {
+  const { db, provisioning, exec, writeFile, log, apply, privileged } = deps;
+  const controlExec = deps.controlExec || exec;
+  // Same box routing as provisionInstance: a standalone runs control-plane-local
+  // (task 2074), so its env/caddy/service live HERE, not on the co-hosting box.
+  const standalone = inst.hosting_shape === 'standalone';
+  const boxExec = standalone ? controlExec : exec;
+  const boxWriteFile = standalone ? (deps.controlWriteFile || writeFile) : writeFile;
+  const sudoP = privileged ? 'sudo ' : '';
+  log(`domain-attach ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status}, domain=${inst.domain || '-'})`);
+
+  if (!inst.domain) return { ok: false, error: 'no domain recorded on the instance — nothing to wire' };
+  // Pre-active states are the provision run's job; post-active states have nothing
+  // to address. A clean no-op (not an error) so a raced teardown/re-request never
+  // burns the intent's retry budget.
+  if (inst.status !== 'active') {
+    log(`  instance is '${inst.status}' — nothing to wire now (provision owns pre-active domains)`);
+    return { ok: true, noop: true };
+  }
+  if (inst.hosting_shape === 'dedicated') {
+    return { ok: false, error: `domain-attach for a dedicated instance is not automated yet — point an A record for ${inst.domain} at the droplet's IP and reload its Caddy` };
+  }
+
+  // DNS preflight (the task-1980 stance): verify token reach BEFORE touching the box.
+  if (CONFIG.dnsHook && apply) {
+    const scope = await (deps.checkDnsTokenScope || checkDnsTokenScope)(inst.domain);
+    if (!scope.reachable) {
+      return { ok: false, error: `DNS preflight failed for ${inst.domain}: ${scope.reason}. ${scope.guidance}` };
+    }
+    log(`  [preflight] DNS token can reach zone ${scope.zone} ✓`);
+  }
+
+  // The A-record target — the same derivation as provisionInstance step 1.
+  const recordIp = standalone
+    ? (CONFIG.controlPlaneIp || (CONFIG.remoteHost ? null : CONFIG.publicIp))
+    : CONFIG.publicIp;
+
+  log('  [config] re-write per-instance web.env (origins now carry the domain)');
+  boxWriteFile(webEnvPath(inst), webEnvBody(inst, { federation: null }), { mode: 0o600, sudo: true });
+  log('  [service] restart to pick up the new origins');
+  boxExec(`${sudoP}systemctl restart ${inst.slug}`);
+
+  // DNS A-record UPSERT — mirrors provisionInstance step 5 (control-plane exec only:
+  // the hook needs the Cloudflare token, which never leaves the control plane).
+  if (CONFIG.dnsHook) {
+    if (!recordIp) {
+      const ipEnvHint = standalone ? 'PROVISION_CONTROL_PLANE_IP (standalone)' : 'PROVISION_PUBLIC_IP (co-tenant)';
+      if (apply) return { ok: false, error: `cannot UPSERT DNS for ${inst.domain}: no target IP — set ${ipEnvHint} in the control-plane box.env` };
+      log(`  [dns] would upsert A ${inst.domain} once the target IP is known (set ${ipEnvHint})`);
+    } else {
+      const dnsEnv = dnsUpsertEnv(inst, { publicIp: recordIp, proxied: standalone });
+      log(`  [dns] upsert A ${inst.domain} -> ${recordIp} (zone ${dnsEnv.CLOUDFLARE_ZONE}, proxied=${dnsEnv.BOX_PROXIED === '1'}) via ${CONFIG.dnsHook}`);
+      controlExec(CONFIG.dnsHook, { env: dnsEnv });
+    }
+  } else {
+    log('  [dns] skipped (BOX_DNS_HOOK unset) — point the A record manually');
+  }
+
+  log('  [caddy] write site snippet + reload');
+  boxWriteFile(caddySnippetPath(inst), caddyBlock(inst), { mode: 0o644, sudo: true });
+  boxExec(`${sudoP}systemctl reload caddy`, { allowFail: true });
+
+  log('  [healthz] verify the instance answers');
+  boxExec(healthzCmd(inst), { allowFail: true });
+
+  if (apply) {
+    await provisioning.recordEvent(db, {
+      instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'domain-attached',
+      detail: `domain ${inst.domain} wired (env + DNS + caddy re-asserted)`, actor: 'runner',
+    }).catch(() => {});
+  }
+  log(`  ✓ ${inst.slug} addressed as ${inst.domain}`);
+  return { ok: true };
+}
+
 // ---------------------------------------------------------------------------
 // Teardown one instance (reverse the runbook; idempotent).
 // ---------------------------------------------------------------------------
@@ -1735,9 +1819,13 @@ async function cmdRunIntents(deps) {
     try {
       const inst = await provisioning.getInstanceById(db, intent.instance_id);
       if (!inst) { await provisioning.resolveIntent(db, intent.id, 'error', 'instance row vanished'); errors++; continue; }
-      const result = intent.action === 'provision'
-        ? await provisionInstance(inst, deps)
-        : await teardownInstance(inst, deps);
+      // Dispatch EXPLICITLY per action — an unrecognized action must surface as an
+      // error, never fall through to the destructive teardown leg (task 1002692).
+      let result;
+      if (intent.action === 'provision') result = await provisionInstance(inst, deps);
+      else if (intent.action === 'teardown') result = await teardownInstance(inst, deps);
+      else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, deps);
+      else result = { ok: false, error: `unknown intent action '${intent.action}' — refusing to guess` };
       if (result && result.ok === false) {
         if (intent.attempts >= MAX_INTENT_ATTEMPTS) await provisioning.resolveIntent(db, intent.id, 'error', result.error || 'op failed');
         else await db.query(`UPDATE provisioning_intents SET state='pending', last_error=$2, updated_at=now() WHERE id=$1`, [intent.id, result.error || 'op failed']);
@@ -1907,7 +1995,7 @@ module.exports = {
   caddyBlock, caddySnippetPath, healthzCmd, dedicatedUserData, nextFreePort,
   // executors + orchestration (injectable deps for tests)
   makeExec, makeWriteFile, allocatePort, boundLocalPorts, provisionInstance, teardownInstance,
-  cmdRunIntents, cmdReconcile, cmdStatus,
+  domainAttachInstance, cmdRunIntents, cmdReconcile, cmdStatus,
   // GitHub App Manifest flow (task 2080, ADR 0133)
   convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
   // cross-site identity federation (ADR 0141 §4, task #1002109)

package/src/module-api.js

@@ -547,8 +547,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.58 with no explicit bump. run 31547103265. (task 1002620)
 //   1.19.60 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.59 with no explicit bump. run 31548021746. (task 1002620)
+//   1.19.61 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.60 with no explicit bump. run 31550061440. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.60'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.61'; // 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/provision.mjs

@@ -1421,5 +1421,139 @@ await ta('provisionInstance(standalone, hub-configured): still NOT federated —
   });
 });
 
+console.log('\ndomain-attach leg (task 1002692 — give an ACTIVE instance its late-arriving address):');
+
+// Recorder for the attach leg: captures commands (with env), file writes (with
+// bodies), and recorded events. No status writes to capture — domain-attach must
+// never touch the instance lifecycle.
+function attachRecorder({ apply = false } = {}) {
+  const cmds = [], envs = [], writes = [], events = [];
+  const deps = {
+    apply, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: { recordEvent: async (_db, e) => { events.push(e); } },
+    exec: (cmd, opts = {}) => { cmds.push(cmd); envs.push((opts && opts.env) || null); return { ok: true, stdout: '' }; },
+    writeFile: (p, body) => { writes.push({ path: p, body }); return { ok: true }; },
+    doApi: null,
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'cloudbongos.com' }),
+  };
+  return { deps, cmds, envs, writes, events };
+}
+
+const activeStandalone = {
+  id: 18, slug: 'spike', hosting_shape: 'standalone', status: 'active', owner_builder_id: 7,
+  port: 3010, db_name: 'spike', domain: 'spike.cloudbongos.com', target_ref: 'jaxri/spike-harbor',
+};
+
+await ta('domainAttachInstance(active standalone): env re-write → restart → DNS upsert → caddy → healthz', async () => {
+  const savedPub = P.CONFIG.publicIp, savedHook = P.CONFIG.dnsHook;
+  P.CONFIG.publicIp = '203.0.113.5';
+  P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps, cmds, envs, writes } = attachRecorder();
+    const r = await P.domainAttachInstance(activeStandalone, deps);
+    assert.equal(r.ok, true);
+    const env = writes.find((w) => /\/spike\/web\.env$/.test(w.path));
+    assert.ok(env, 're-writes web.env');
+    assert.match(env.body, /https:\/\/spike\.cloudbongos\.com/, 'the new address reaches the origins');
+    const joined = cmds.join('\n');
+    assert.match(joined, /systemctl restart spike/, 'RESTART (not reload) so the process re-reads its env');
+    const di = cmds.indexOf('/opt/infra/box-dns-cloudflare.sh');
+    assert.ok(di >= 0, 'DNS hook invoked by path');
+    assert.equal(envs[di].BOX_HOSTNAME, 'spike.cloudbongos.com');
+    assert.equal(envs[di].BOX_PROXIED, '1', 'standalone rides the CF proxy (task 2077)');
+    assert.ok(writes.some((w) => /\/spike\.caddy$/.test(w.path)), 'writes the Caddy site snippet');
+    assert.match(joined, /reload caddy/);
+    assert.match(joined, /healthz/);
+    const idx = (re) => cmds.findIndex((c) => re.test(c));
+    assert.ok(idx(/restart spike/) < idx(/reload caddy/), 'service restart before caddy reload');
+  } finally { P.CONFIG.publicIp = savedPub; P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('domainAttachInstance: no domain recorded → ok:false, nothing runs', async () => {
+  const { deps, cmds } = attachRecorder();
+  const r = await P.domainAttachInstance({ ...activeStandalone, domain: null }, deps);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /no domain/i);
+  assert.equal(cmds.length, 0);
+});
+
+await ta('domainAttachInstance: instance no longer active → clean no-op (provision owns pre-active wiring; never burns the retry budget)', async () => {
+  for (const status of ['requested', 'provisioning', 'tearing_down', 'torn_down', 'error']) {
+    const { deps, cmds } = attachRecorder();
+    const r = await P.domainAttachInstance({ ...activeStandalone, status }, deps);
+    assert.equal(r.ok, true, status);
+    assert.equal(r.noop, true, status);
+    assert.equal(cmds.length, 0, `${status}: nothing ran`);
+  }
+});
+
+await ta('domainAttachInstance: dedicated is not automated — ok:false with guidance, box untouched', async () => {
+  const { deps, cmds } = attachRecorder();
+  const r = await P.domainAttachInstance({ ...activeStandalone, hosting_shape: 'dedicated' }, deps);
+  assert.equal(r.ok, false);
+  assert.match(r.error, /dedicated/);
+  assert.equal(cmds.length, 0);
+});
+
+await ta('domainAttachInstance(--apply): a DNS preflight failure returns ok:false — never THROWS (a throw would flip the ACTIVE instance to error in the drain loop)', async () => {
+  const savedHook = P.CONFIG.dnsHook; P.CONFIG.dnsHook = '/opt/infra/box-dns-cloudflare.sh';
+  try {
+    const { deps, cmds } = attachRecorder({ apply: true });
+    deps.checkDnsTokenScope = async () => ({ reachable: false, zone: 'z', reason: 'not in scope', guidance: 'widen the token' });
+    const r = await P.domainAttachInstance(activeStandalone, deps);
+    assert.equal(r.ok, false);
+    assert.match(r.error, /preflight.*not in scope/);
+    assert.ok(!cmds.some((c) => /restart/.test(c)), 'stops before touching the service');
+  } finally { P.CONFIG.dnsHook = savedHook; }
+});
+
+await ta('cmdRunIntents (--apply) routes a domain-attach intent to the attach leg and resolves it done', async () => {
+  let claims = 0; const resolved = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0 ? { id: 6, instance_id: 18, action: 'domain-attach', attempts: 1 } : null),
+      getInstanceById: async () => ({ ...activeStandalone }),
+      resolveIntent: async (_db, id, state) => { resolved.push({ id, state }); },
+      setInstanceStatus: async () => {},
+      recordEvent: async () => {},
+      claimNextOAuthManifest: async () => null,
+      resolveOAuthManifest: async () => {},
+    },
+    exec: () => ({ ok: true }), writeFile: () => ({ ok: true }), doApi: null,
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'cloudbongos.com' }),
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.ran, 1);
+  assert.equal(r.ok, 1);
+  assert.deepEqual(resolved, [{ id: 6, state: 'done' }]);
+});
+
+await ta('cmdRunIntents (--apply): an UNKNOWN intent action never falls through to teardown', async () => {
+  let claims = 0; const resolved = []; const cmds = [];
+  const deps = {
+    apply: true, log: () => {},
+    db: { query: async () => ({ rows: [] }) },
+    provisioning: {
+      claimNextIntent: async () => (claims++ === 0 ? { id: 7, instance_id: 18, action: 'oauth-manifest', attempts: P.MAX_INTENT_ATTEMPTS } : null),
+      getInstanceById: async () => ({ ...activeStandalone }),
+      resolveIntent: async (_db, id, state, err) => { resolved.push({ id, state, err }); },
+      setInstanceStatus: async () => {},
+      recordEvent: async () => {},
+      claimNextOAuthManifest: async () => null,
+      resolveOAuthManifest: async () => {},
+    },
+    exec: (c) => { cmds.push(c); return { ok: true }; },
+    writeFile: () => ({ ok: true }), doApi: null,
+  };
+  const r = await P.cmdRunIntents(deps);
+  assert.equal(r.errors, 1, 'surfaced as an error, not silently executed');
+  assert.equal(resolved.length, 1);
+  assert.equal(resolved[0].state, 'error');
+  assert.ok(!cmds.some((c) => /systemctl (stop|disable)/.test(c)), 'no teardown commands ran');
+});
+
 console.log(`\nprovision: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/provisioning_domain_attach.mjs

@@ -0,0 +1,289 @@
+// tests/provisioning_domain_attach.mjs
+//
+// The domain-attach path (task 1002692, gap 5 of the creation-flow audit / idea
+// 1000677): before this, NO route could give an EXISTING instance its address — a
+// slug re-request silently dropped the domain in the body, and a domainless
+// instance (e.g. Spike Harbor, instance 18) was stuck domainless forever, which
+// also blocked GitHub sign-in (the github-app manifest route 409s without a domain).
+//
+// Covers:
+//   • updateInstanceDomain / getInstanceByDomain — the service slice (recording fakes)
+//   • INTENT_ACTIONS lockstep — 'domain-attach' rides the intent queue (migration 005)
+//   • POST /provisioning/instances/:id/domain — validate + record + enqueue, with
+//     truthful answers for every refusal (bad domain, taken domain, wrong state,
+//     open-intent conflict) — driven over the real mounted router
+//   • POST /provisioning/instances — a slug re-request carrying a domain now SAYS
+//     the domain was ignored instead of silently dropping it
+//   • POST /provisioning/instances/:id/github-app — accepts the newly-addressed
+//     instance (the domain_required 409 clears once a domain is recorded)
+//
+// DB-free: data-access fns are stubbed on the cached module object (the
+// provisioning_onboard_mode.mjs pattern). No network.
+//
+// Run:  node tests/provisioning_domain_attach.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('service slice — updateInstanceDomain / getInstanceByDomain:');
+
+await ta('updateInstanceDomain: parameterized UPDATE of only the domain (+updated_at), returns the row', async () => {
+  const calls = [];
+  const db = { query: async (sql, params) => {
+    calls.push({ sql, params });
+    return { rows: [{ id: 18, domain: params[1] }] };
+  } };
+  const row = await provisioning.updateInstanceDomain(db, 18, 'spike.cloudbongos.com');
+  assert.equal(row.domain, 'spike.cloudbongos.com');
+  assert.match(calls[0].sql, /UPDATE provisioning_instances/);
+  assert.match(calls[0].sql, /SET domain = \$2, updated_at = now\(\)/, 'touches ONLY the domain column');
+  assert.deepEqual(calls[0].params, [18, 'spike.cloudbongos.com']);
+});
+
+await ta('getInstanceByDomain: case-insensitive exact match, parameterized', async () => {
+  const calls = [];
+  const db = { query: async (sql, params) => {
+    calls.push({ sql, params });
+    return { rows: params[0] === 'spike.cloudbongos.com' ? [{ id: 18 }] : [] };
+  } };
+  const hit = await provisioning.getInstanceByDomain(db, 'SPIKE.cloudbongos.com');
+  assert.equal(hit.id, 18, 'matches regardless of stored/asked case');
+  assert.match(calls[0].sql, /lower\(domain\) = \$1/);
+  assert.equal(await provisioning.getInstanceByDomain(db, 'other.example.com'), null);
+});
+
+t("INTENT_ACTIONS includes 'domain-attach' (lockstep with the provisioning_005 CHECK)", () => {
+  assert.ok(provisioning.INTENT_ACTIONS.includes('domain-attach'));
+});
+
+// ── the routes, over a real mounted router (stubbed data access) ──────────────────
+let instance = null;             // what getInstanceById returns
+let domainHolder = null;         // what getInstanceByDomain returns
+let updateCalls = [];
+let enqueueCalls = [];
+let enqueueResult = null;        // what enqueueIntent reports
+let createResult = null;         // what createInstance reports (re-request tests)
+let manifestRows = [];
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.getInstanceByDomain = async (_db, d) => domainHolder;
+provisioning.updateInstanceDomain = async (_db, id, domain) => {
+  updateCalls.push({ id, domain });
+  instance = { ...instance, domain };
+  return { ...instance, id };
+};
+provisioning.enqueueIntent = async (_db, id, action, requestedBy) => {
+  enqueueCalls.push({ id, action, requestedBy });
+  return enqueueResult || { intent: { id: 9, action, state: 'pending' }, created: true };
+};
+provisioning.getOpenIntent = async () => null;
+provisioning.createInstance = async () => createResult;
+provisioning.recordEvent = async () => {};
+provisioning.createOAuthManifest = async (_db, row) => { manifestRows.push(row); return { id: 1, ...row }; };
+provisioning.getLatestOAuthManifestForInstance = async () => null;
+
+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();
+api.branding = () => ({
+  domains: { publicOrigin: 'https://cb.test' },
+  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);
+  });
+}
+
+function reset({ inst } = {}) {
+  instance = inst || null;
+  domainHolder = null;
+  updateCalls = [];
+  enqueueCalls = [];
+  enqueueResult = null;
+  createResult = null;
+  manifestRows = [];
+}
+
+console.log('\nPOST /provisioning/instances/:id/domain — give an existing instance its address:');
+
+await ta('ACTIVE domainless instance: domain is validated, recorded, and a domain-attach intent queues', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', hosting_shape: 'standalone', domain: null } });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'Spike.CloudBongos.com.' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.ok, true);
+  assert.equal(res.body.domain, 'spike.cloudbongos.com', 'normalized before storing');
+  assert.deepEqual(updateCalls, [{ id: 18, domain: 'spike.cloudbongos.com' }]);
+  assert.deepEqual(enqueueCalls.map((c) => c.action), ['domain-attach']);
+  assert.equal(res.body.queued, true);
+});
+
+await ta('a malformed domain is refused 400 before anything is written', async () => {
+  for (const bad of ['not a host', 'com', '', '-x.example.com']) {
+    reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: null } });
+    const res = await post('/provisioning/instances/18/domain', { domain: bad });
+    assert.equal(res.status, 400, `${JSON.stringify(bad)}: ${res.raw}`);
+    assert.equal(res.body.error.code, 'bad_domain');
+    assert.equal(updateCalls.length, 0, 'nothing recorded');
+    assert.equal(enqueueCalls.length, 0, 'nothing queued');
+  }
+});
+
+await ta("another instance already holding the domain is a truthful 409 domain_taken (never a silent shadow)", async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: null } });
+  domainHolder = { id: 99, slug: 'other' };
+  const res = await post('/provisioning/instances/18/domain', { domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_taken');
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('same domain again is idempotent — 200, changed:false, nothing re-queued', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: 'spike.cloudbongos.com' } });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'SPIKE.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.changed, false);
+  assert.equal(updateCalls.length, 0);
+  assert.equal(enqueueCalls.length, 0);
+});
+
+await ta('a DIFFERENT domain already set is a truthful 409 domain_already_set (re-pointing is not this route)', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: 'old.cloudbongos.com' } });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'new.cloudbongos.com' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'domain_already_set');
+  assert.equal(res.body.error.details.current, 'old.cloudbongos.com', 'names the current address');
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('REQUESTED instance: domain records with NO intent — the provision run wires it', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'fresh', status: 'requested', domain: null } });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'fresh.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.queued, false);
+  assert.deepEqual(updateCalls, [{ id: 18, domain: 'fresh.cloudbongos.com' }]);
+  assert.equal(enqueueCalls.length, 0, 'provision will wire it — no separate intent');
+});
+
+await ta('an instance mid-flight (provisioning / tearing_down / torn_down) is a truthful 409', async () => {
+  for (const status of ['provisioning', 'tearing_down', 'torn_down']) {
+    reset({ inst: { owner_builder_id: 7, slug: 'spike', status, domain: null } });
+    const res = await post('/provisioning/instances/18/domain', { domain: 'spike.cloudbongos.com' });
+    assert.equal(res.status, 409, `${status}: ${res.raw}`);
+    assert.equal(res.body.error.code, 'domain_not_attachable');
+    assert.equal(res.body.error.details.status, status, 'names the real state');
+    assert.equal(updateCalls.length, 0, `${status}: nothing recorded`);
+  }
+});
+
+await ta('an open non-domain intent (e.g. a teardown) is a truthful 409 intent_conflict, not a false success', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: null } });
+  enqueueResult = { intent: { id: 5, action: 'teardown', state: 'pending' }, created: false };
+  const res = await post('/provisioning/instances/18/domain', { domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 409, res.raw);
+  assert.equal(res.body.error.code, 'intent_conflict');
+  assert.equal(res.body.error.details.action, 'teardown', 'names the real blocker');
+});
+
+await ta('an already-open domain-attach intent is idempotent — 200 queued:false "already being wired"', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: null } });
+  enqueueResult = { intent: { id: 5, action: 'domain-attach', state: 'pending' }, created: false };
+  const res = await post('/provisioning/instances/18/domain', { domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.queued, false);
+  assert.match(res.body.message, /already/i);
+});
+
+await ta('not the owner → 404 (own-scoped; existence not leaked)', async () => {
+  reset({ inst: { owner_builder_id: 42, slug: 'theirs', status: 'active', domain: null } });
+  const res = await post('/provisioning/instances/18/domain', { domain: 'x.cloudbongos.com' });
+  assert.equal(res.status, 404, res.raw);
+});
+
+console.log('\nPOST /provisioning/instances — slug re-requests are truthful about the domain:');
+
+await ta('re-request with a domain on an existing instance SAYS the domain was ignored (and where to send it)', async () => {
+  reset();
+  createResult = { instance: { id: 18, owner_builder_id: 7, slug: 'spike', status: 'active', domain: null }, created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike', hosting_shape: 'standalone', domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.ok(res.body.domain_ignored, 'the drop is surfaced, not silent');
+  assert.equal(res.body.domain_ignored.requested, 'spike.cloudbongos.com');
+  assert.match(res.body.domain_ignored.hint, /\/domain/, 'points at the domain-attach route');
+});
+
+await ta('re-request with the SAME domain the instance already has → no ignored flag (nothing was dropped)', async () => {
+  reset();
+  createResult = { instance: { id: 18, owner_builder_id: 7, slug: 'spike', status: 'active', domain: 'spike.cloudbongos.com' }, created: false };
+  const res = await post('/provisioning/instances', { slug: 'spike', hosting_shape: 'standalone', domain: 'spike.cloudbongos.com' });
+  assert.equal(res.status, 200, res.raw);
+  assert.equal(res.body.domain_ignored, undefined);
+});
+
+await ta('a fresh create with a domain is untouched (the domain is stored at creation — nothing ignored)', async () => {
+  reset();
+  createResult = { instance: { id: 43, owner_builder_id: 7, slug: 'new', status: 'requested', domain: 'new.cloudbongos.com' }, created: true };
+  const res = await post('/provisioning/instances', { slug: 'new', hosting_shape: 'standalone', domain: 'new.cloudbongos.com' });
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(res.body.domain_ignored, undefined);
+});
+
+console.log('\nPOST /provisioning/instances/:id/github-app — accepts the newly-addressed instance:');
+
+await ta('domainless instance still 409s domain_required; once addressed, the manifest mints', async () => {
+  reset({ inst: { owner_builder_id: 7, slug: 'spike', status: 'active', domain: null } });
+  const before = await post('/provisioning/instances/18/github-app', {});
+  assert.equal(before.status, 409, before.raw);
+  assert.equal(before.body.error.code, 'domain_required');
+
+  instance = { ...instance, domain: 'spike.cloudbongos.com' };
+  const after = await post('/provisioning/instances/18/github-app', {});
+  assert.equal(after.status, 200, after.raw);
+  assert.equal(manifestRows.length, 1, 'a manifest attempt row was recorded');
+  assert.match(after.body.manifest.url, /spike\.cloudbongos\.com/, 'the manifest points at the new address');
+});
+
+server.close();
+console.log(`\nprovisioning_domain_attach: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);