@bongos/core 1.19.950 → 1.19.952

package/scripts/gds/init.js

@@ -87,7 +87,13 @@ const KNOWN_MODULES = ['game', 'art-pipeline', 'discord', 'dev-box'];
 // request (POST /provisioning/instances validates slug/shape, and returns 404 when
 // the module isn't enabled on the target instance — init then falls back to filing
 // the manual production-topology task). ADR 0111 §3.
-const HOSTING_SHAPES = ['co-tenant', 'dedicated', 'standalone'];
+// ADR 0323: 'byo-host' is the free front door and the default; 'co-tenant' is RETIRED
+// and the server refuses it outright, so it is absent here DELIBERATELY. Leaving it in
+// would let init write a spec the create route then 403s — a local list that accepts
+// more than the server does is worse than no list, because the refusal arrives a step
+// later with no useful message. Dropping it means `--shape co-tenant` fails here, naming
+// the shapes that work.
+const HOSTING_SHAPES = ['byo-host', 'dedicated', 'standalone'];
 
 // The Cloud Bongos core npm package an instance pins as a dependency (ADR 0108).
 // `bongos init --adopt` LAYERS this onto an existing repo's package.json; `bongos
@@ -205,11 +211,11 @@ function provisioningSlug(spec) {
 // block). THE ADR 0111 §3 ARM: infra answers become a real provisioning REQUEST (a
 // provisioning_intents row the control-plane runner drains) instead of only a manual
 // runbook task. Pure — no I/O; the caller POSTs it. Shape defaults to the cheapest
-// co-tenant ($0) per the budget DNA (ADR 0111 §6).
+// byo-host ($0 to us — the owner supplies the host) per the budget DNA (ADR 0323).
 function provisioningRequest(spec) {
   const p = spec && spec.provisioning;
   if (!isObj(p)) return null;
-  const shape = HOSTING_SHAPES.includes(p.shape) ? p.shape : 'co-tenant';
+  const shape = HOSTING_SHAPES.includes(p.shape) ? p.shape : 'byo-host';
   const body = { slug: provisioningSlug(spec), hosting_shape: shape };
   if (p.domain) body.domain = String(p.domain).trim();
   if (p.targetRef) body.target_ref = String(p.targetRef).trim();
@@ -334,12 +340,12 @@ function normalizeSpec(raw = {}) {
   spec.modules = Array.isArray(spec.modules) ? spec.modules.filter((m) => KNOWN_MODULES.includes(m)) : [];
   if (!spec.version.status) spec.version.status = 'building';
   // Provisioning (ADR 0111 §3) — a block ⇒ the owner opted in. Coerce the shape to a
-  // known value (default the cheapest co-tenant) and trim the free-text refs; drop the
+  // known value (default byo-host, the free front door) and trim the free-text refs; drop the
   // block entirely when absent so provisioningRequest() reads it as "not requested".
   if (isObj(spec.provisioning)) {
     const p = spec.provisioning;
     spec.provisioning = {
-      shape: HOSTING_SHAPES.includes(p.shape) ? p.shape : 'co-tenant',
+      shape: HOSTING_SHAPES.includes(p.shape) ? p.shape : 'byo-host',
       ...(p.slug ? { slug: String(p.slug).trim() } : {}),
       ...(p.domain ? { domain: String(p.domain).trim() } : {}),
       ...(p.targetRef ? { targetRef: String(p.targetRef).trim() } : {}),
@@ -446,13 +452,20 @@ async function interview({ adopt = false } = {}) {
     let provisioning;
     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();
+      // Describes each shape by WHAT IT DOES and never by its owner-facing product
+      // name. The stored value → owner-facing label translation lives in exactly one
+      // place — SHAPE_LABEL in modules/public-landing/public/projects.html (ADR 0323,
+      // and this module's CLAUDE.md says so) — so glossing '"cloud host"' here would
+      // be a second copy of it, in a file no designer renaming the product would
+      // think to open. A CLI prompt naming the stored value it is about to write is
+      // the right register anyway: this asks for a column value, not for a purchase.
+      const shape = (await ask(rl, '  Hosting shape? (byo-host = you run it on your own host / standalone = its own repo + pinned @bongos/core on the platform\'s box / dedicated = the same on its own droplet, priced by tier)', 'byo-host')).toLowerCase();
       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)');
       provisioning = {
-        shape: HOSTING_SHAPES.includes(shape) ? shape : 'co-tenant',
+        shape: HOSTING_SHAPES.includes(shape) ? shape : 'byo-host',
         domain: domain || undefined,
         targetRef: targetRef || undefined,
         tier: tier || undefined,
@@ -484,7 +497,8 @@ async function interview({ adopt = false } = {}) {
 // ---------------------------------------------------------------------------
 
 // PURE (exported for tests) — the root START-HERE guide (task 1002404, goal
-// 1000052). A freshly-CLONED instance must tell a human what to run FIRST: the
+// 1000052; task 1003881 made it LAYER onto an existing README instead of
+// skipping one — see layerReadme below). A freshly-CLONED instance must tell a human what to run FIRST: the
 // `bongos` CLI ships INSIDE the not-yet-installed @bongos/core package, so
 // `npm install` has to come before any `bongos` command (including `bongos dev`).
 // `bongos init` runs npm install during scaffolding, but a later `git clone` of
@@ -624,8 +638,9 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   log(`  ✓ wrote ${path.relative(dir, modulesPath)}`);
   log(`  ✓ wrote ${path.relative(dir, hierarchyPath)}`);
   log(`  ✓ wrote ${path.relative(dir, pkgPath)} (pins ${CORE_PKG} → ${pinNote})`);
-  // README START-HERE (task 1002404): mint it when absent, else APPEND the marked
-  // section. Never a blind overwrite — an owner's own README content always survives.
+  // README START-HERE (task 1002404, layering added by task 1003881): mint it when
+  // absent, else APPEND the marked section. Never a blind overwrite — an owner's own
+  // README content always survives, which is why the guide stopped being skipped.
   layerReadme(branding, { dir, dryRun: false, log });
   return { brandingPath, modulesPath, hierarchyPath, pkgPath, readmePath, wrote: true };
 }

package/scripts/gds/login.js

@@ -23,7 +23,7 @@
 const readline = require('node:readline');
 const { spawnSync } = require('node:child_process');
 const { saveSession, loadStoredSession, listStoredSessions } = require('./cli-lib');
-// The device-flow refusal detector + its plain-language cure (task 1003400). A leaf
+// The device-flow refusal detector + its plain-language cure (task 1003881). A leaf
 // module, NOT setup.js: setup requires this file for runDeviceFlow, so requiring it
 // back would close a require cycle. Both callers depend on the leaf instead.
 const { isDeviceFlowDisabled, deviceFlowFallbackLines } = require('./device-flow-help');

package/scripts/gds/provision-byo-host.js

@@ -0,0 +1,68 @@
+'use strict';
+
+// scripts/gds/provision-byo-host.js — the runner's answer for a 'byo-host' instance:
+// stand up NOTHING (ADR 0323, task 1004141).
+//
+// "Bring your own host" means the OWNER runs the instance — their machine, their VPS,
+// their own platform account. The platform's only job is to hold the record, so the
+// runner's job here is defined ENTIRELY BY WHAT IT MUST NOT DO: no port allocation, no
+// database or role, no `web.env` under /etc, no systemd unit, no Caddy snippet, no DNS
+// record, no cloud API call, no shell on anybody's box.
+//
+// WHY IT IS A GUARD AND NOT A CASE IN THE SWITCH. `provisionInstance` runs four
+// preflights before it mutates anything — box capacity, ingress, unix accounts, Caddy
+// wiring — and every one of them asks a question about a machine the platform owns. On
+// a byo-host row the honest answer to each is not "pass" or "fail" but "not ours to
+// ask", so the shape has to return ABOVE them, not be handled after them. That is why
+// the caller's line sits immediately under the already-active idempotency check.
+//
+// WHAT IT PREVENTED. Before this existed the shape fell through to the shared
+// co-tenant/standalone standup. `standalone` is false for it, so boxExec was the
+// CONTROL PLANE's own shell: the runner would have allocated a port, run createdb,
+// written env under /etc, installed a unit and a Caddy snippet and reloaded the proxy —
+// standing up, on our box, the one shape whose entire promise is that we never do.
+// Nothing would have errored. A silent success is the failure mode, which is why the
+// proof (`tests/provision_byo_host.mjs`) asserts ABSENCE — no exec, no write, no port,
+// no database — instead of asserting that the right steps ran.
+//
+// WHY THE ROW STILL GOES 'active'. `active` records that the platform has nothing left
+// to do, not that the platform is running it. Liveness for this shape is the ADR 0252
+// pull against the owner-supplied origin: the ~5-minute liveness sweep probes it by
+// domain and only ever writes the overlay columns, never `status`, so the card earns its
+// verdict from an observation rather than from our runner's say-so.
+//
+// Its own file because scripts/gds/provision.js sits at the 1500-line oversized-file
+// ratchet — the same reason provision-net.js, provision-units.js and
+// provision-core-upgrade.js were carved out.
+
+// The stored value. A literal, not a regex or a prefix match: a near-miss must reach the
+// standup's own validation rather than be quietly treated as the shape we skip.
+const BYO_HOST_SHAPE = 'byo-host';
+
+function isByoHost(hostingShape) {
+  return hostingShape === BYO_HOST_SHAPE;
+}
+
+// Record a byo-host instance as provisioned without touching any box. Reaches the
+// database ONLY through the injected `provisioning` port (the status flip + the audit
+// event) — it takes no executor and no writeFile, so there is nothing here that could
+// mutate a machine even by mistake.
+async function recordByoHost(inst, { db, provisioning, log, apply }) {
+  log('  [byo-host] the owner runs this one — no port, no database, no unit, no Caddy snippet, no DNS');
+  if (!apply) {
+    log('  [byo-host] would mark it active without touching any box');
+    return { ok: true, byoHost: true, stoodUp: false };
+  }
+  // error_note: null — a stale note from an earlier failed run must not ride into the
+  // active state (the same clearing the co-tenant/standalone tail does).
+  await provisioning.setInstanceStatus(db, inst.id, 'active', { error_note: null, provisioned_at: new Date().toISOString() });
+  await provisioning.recordEvent(db, {
+    instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'active',
+    detail: 'byo-host — the owner supplies the host; the platform stood up nothing',
+    actor: 'runner',
+  });
+  log(`  ✓ ${inst.slug} recorded (byo-host) — nothing was stood up`);
+  return { ok: true, byoHost: true, stoodUp: false };
+}
+
+module.exports = { BYO_HOST_SHAPE, isByoHost, recordByoHost };

package/scripts/gds/provision.js

@@ -59,6 +59,7 @@ const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
 const { coreUpgradeInstance, preflightCoreUpgrade, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
+const { isByoHost, recordByoHost } = require('./provision-byo-host.js'); // stand up NOTHING for a byo-host row, ADR 0323
 
 // WHAT supervises an instance's service (ADR 0306). systemd on every box we run — the
 // seam exists so a plane without systemd is not a dead end. Injectable for tests.
@@ -250,6 +251,7 @@ async function provisionInstance(inst, deps) {
   // Idempotency: an already-active instance is a no-op success (re-drained intent).
   if (inst.status === 'active') { log('  already active — nothing to do'); return { ok: true, already: true }; }
 
+  if (isByoHost(inst.hosting_shape)) return recordByoHost(inst, deps); // stand up NOTHING, ABOVE every preflight — reasoning in provision-byo-host.js's header (ADR 0323)
   // ── preflight: DNS token scope (task 1980) ─────────────────────────────────
   // BEFORE committing to the address (allocating a port / creating a droplet / the
   // step-5 DNS UPSERT), verify the control-plane Cloudflare token can actually reach

package/scripts/gds/setup.js

@@ -274,7 +274,7 @@ async function promptOnboardingConsent() {
 }
 
 // ── W1: the manifest-born App has Device Flow OFF (task 1003051) ─────────────
-// The detector + the guidance moved to ./device-flow-help (task 1003400) so
+// The detector + the guidance moved to ./device-flow-help (task 1003881) so
 // `bongos login` can use the same words without closing a require cycle back
 // through this file (setup requires login for runDeviceFlow). Re-exported here
 // because both are part of setup.js's tested public surface.

package/src/module-api.js

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

package/tests/adopt_preflight.mjs

@@ -101,7 +101,7 @@ t('preflightAdopt: a clean repo → no blocking; every category reports', () =>
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
-// ---- ignored-incoming: the check that was missing (task 1003400) ----------
+// ---- ignored-incoming: the check that was missing (task 1003881) ----------
 //
 // The failure it exists to stop: adopt onto a repo whose .gitignore already carries
 // `.claude/`. The skills/hooks/settings are written to disk, `git add` drops them, the

package/tests/bongos_login.mjs

@@ -45,7 +45,7 @@ test('pollDecision maps the /access-requests/status body to a loop action', () =
   assert.equal(pollDecision({}), 'wait');
 });
 
-// ---- the Device-Flow dead end (task 1003400) -------------------------------
+// ---- the Device-Flow dead end (task 1003881) -------------------------------
 //
 // Device Flow is OFF on every GitHub App created from a manifest and GitHub offers no
 // API to switch it on, so terminal sign-in is broken from birth on a fresh instance —

package/tests/discord_approvals.mjs

@@ -170,7 +170,7 @@ await t('a DB error returns {error}, never throws', async () => {
   assert.equal(r.outcome, 'error');
 });
 
-// ---- the outbound half must not outlive the inbound half (task 1003400) ----
+// ---- the outbound half must not outlive the inbound half (task 1003881) ----
 //
 // The 👍 this line invites is applied ONLY by discord-approvals.js, which lives in the
 // `discord` module. onboarding (which posts) is default-ON; discord is default-OFF; and

package/tests/init.mjs

@@ -239,14 +239,16 @@ test('provisioningSlug: derives from productName, clamps to 40, strips trailing
 test('provisioningRequest: null unless opted in; builds the POST body when opted in', () => {
   assert.equal(init.provisioningRequest(fullSpec()), null);              // no block → not requested
   const co = init.provisioningRequest(provSpec({}));                     // empty block = opted in, defaults
-  assert.deepEqual(co, { slug: 'cloud-bongos', hosting_shape: 'co-tenant' });
+  assert.deepEqual(co, { slug: 'cloud-bongos', hosting_shape: 'byo-host' });
   const full = init.provisioningRequest(provSpec({ shape: 'dedicated', domain: 'example.com', targetRef: 'do:main', tier: 's-1vcpu-2gb' }));
   assert.deepEqual(full, { slug: 'cloud-bongos', hosting_shape: 'dedicated', domain: 'example.com', target_ref: 'do:main', tier: 's-1vcpu-2gb' });
 });
 
-test('provisioningRequest: unknown shape falls back to the cheapest co-tenant', () => {
-  // normalizeSpec coerces a bad shape → co-tenant (the budget default, ADR 0111 §6).
-  assert.equal(init.provisioningRequest(provSpec({ shape: 'kubernetes' })).hosting_shape, 'co-tenant');
+test('provisioningRequest: unknown shape falls back to byo-host, the free front door', () => {
+  // normalizeSpec coerces a bad shape → byo-host (ADR 0323; was co-tenant, which that
+  // decision retired — the server now refuses it, so falling back to it would write a
+  // spec the create route rejects a step later).
+  assert.equal(init.provisioningRequest(provSpec({ shape: 'kubernetes' })).hosting_shape, 'byo-host');
 });
 
 test('kickoffTasks: provisioning requested → production-topology is AUTOMATED (dropped), manual steps stay', () => {
@@ -264,7 +266,7 @@ test('kickoffTasks: provisioning requested → production-topology is AUTOMATED
 test('normalizeSpec: coerces the provisioning block; drops it when absent', () => {
   assert.equal(init.normalizeSpec({}).provisioning, undefined);
   const n = init.normalizeSpec({ provisioning: { shape: 'DEDICATED', domain: '  Example.com  ', junk: 1 } });
-  assert.equal(n.provisioning.shape, 'co-tenant');                       // unknown shape (case) → default
+  assert.equal(n.provisioning.shape, 'byo-host');                        // unknown shape (case) → default
   assert.equal(n.provisioning.domain, 'Example.com');                    // trimmed
   assert.equal(n.provisioning.junk, undefined);                          // stray field dropped
 });
@@ -651,14 +653,14 @@ async function runSeedTests() {
 
   await at('seedViaApi: provisioning 404 (module off) → falls back to the manual production-topology task', async () => {
     const api = fakeApi([['/provisioning/instances', { ok: false, status: 404, data: { error: 'not_found' } }]]);
-    const out = await init.seedViaApi(provSpec({ shape: 'co-tenant' }), { log: () => {}, api });
+    const out = await init.seedViaApi(provSpec({ shape: 'byo-host' }), { log: () => {}, api });
     assert.equal(out.provisioned, false);
     assert.ok(findTaskPost(api, /Production topology/), 'filed the manual fallback task');
   });
 
   await at('seedViaApi: provisioning error → also files the fallback task', async () => {
     const api = fakeApi([['/provisioning/instances', { ok: false, status: 500, data: {} }]]);
-    const out = await init.seedViaApi(provSpec({ shape: 'co-tenant' }), { log: () => {}, api });
+    const out = await init.seedViaApi(provSpec({ shape: 'byo-host' }), { log: () => {}, api });
     assert.equal(out.provisioned, false);
     assert.ok(findTaskPost(api, /Production topology/), 'filed the manual fallback task on error');
   });

package/tests/module_api.mjs

@@ -48,7 +48,7 @@ const PUBLISHED_SURFACE = [
   'artistGate', // added by task 1003575 (ADR 0241): the artist gate — off | advisory | strict, plus the pure verdict helpers over it. Two modules ask it two different questions ("file this review?" and "does an open one hold the deploy?") and both must resolve the knob through this one reader, never branding().project
   'readApplicantProfileFromHub', // added by task 1002972 (privacy spec D7): the reviewer queue's LIVE per-render read of one applicant's hub profile view. NARROW by design — the underlying call is authenticated with this instance's hub client secret, and loadIdpConfig stays OFF the doorway so no module ever holds the credential that speaks for the whole project
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
-  'isModuleEnabled', // task 1003400: is ANOTHER module present? onboarding's Discord approve/decline control is only actionable when the `discord` module's reaction handler is loaded, so the posting half has to be able to ask
+  'isModuleEnabled', // task 1003881: is ANOTHER module present? onboarding's Discord approve/decline control is only actionable when the `discord` module's reaction handler is loaded, so the posting half has to be able to ask
   'registerProvider', 'hasProvider', 'resolve', 'resolveOptional', 'listPorts', 'verifyPortsSatisfied',
   'on', 'emit', 'emitAsync', 'listEvents', 'seamSnapshot',
   'contribute', 'contributions', 'collectContributions', 'listContributionPoints',

package/tests/projects_hub_pre_uat.mjs

@@ -237,7 +237,11 @@ test('no wall-clock promises, no operator vocabulary on the stranger’s path',
   assert.doesNotMatch(HUB, /about five minutes/, 'the empty state');
   assert.doesNotMatch(HUB, /a runner does the real work/, 'the mine fine print');
   assert.doesNotMatch(SCRIPT, /pinned platform core/, 'the review Shape row');
-  assert.match(SCRIPT, /\['Shape', 'Its own server, running the platform’s current release'\]/);
+  /* The wizard creates hosting_shape 'standalone', whose owner-facing name became
+     "cloud host" at ADR 0323 — "its own server" was ambiguous between that shape and
+     a dedicated one, and said nothing about WHO runs it. The assertion still guards the
+     same property this test is about: owner vocabulary, and no wall-clock promise. */
+  assert.match(SCRIPT, /\['Shape', 'Cloud host — we stand it up and run it for you, on the platform’s current release'\]/);
   assert.doesNotMatch(HUB, /\/new-project<\/code> assistant/, 'the done panel’s closing line');
   assert.match(HUB, /Sign-in switches on after the GitHub steps|switch sign-in on/, 'the address step does not promise sign-in "just works"');
   assert.doesNotMatch(HUB, /Sign-in, sharing, everything just works/);

package/tests/provision_byo_host.mjs

@@ -0,0 +1,122 @@
+// tests/provision_byo_host.mjs — the runner stands up NOTHING for a 'byo-host'
+// instance (ADR 0323, task 1004141).
+//
+// PROVES ABSENCE, not that the right steps ran, and that is the whole point. The
+// shape's promise is negative — the owner supplies the host, so the platform must
+// allocate no port, create no database, write no file, install no unit, touch no
+// proxy and publish no DNS record. Asserting "the byo-host path ran" would pass
+// just as happily if the co-tenant standup ran underneath it, which is exactly the
+// bug this file exists to catch: before the branch, 'byo-host' fell through to the
+// shared standup on the CONTROL PLANE's own shell and nothing errored.
+//
+// Hermetic: every executor is a spy that RECORDS instead of acting, so a single
+// stray command shows up as a failed assertion rather than as a mutated box.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const P = require('../scripts/gds/provision.js');
+
+const byoHost = {
+  id: 42, slug: 'mercury', hosting_shape: 'byo-host', status: 'requested',
+  owner_builder_id: 7, port: null, db_name: null, domain: 'mercury.example.com',
+};
+
+// Spies for every way provisionInstance can reach a machine or a record. `exec`
+// and `writeFile` THROW rather than return, so a leaked step fails loudly with the
+// command in the message instead of being silently collected and forgotten.
+function harness({ apply = true } = {}) {
+  const queries = [], statuses = [], events = [], logs = [];
+  const boom = (what) => (arg) => { throw new Error(`byo-host must not ${what}: ${String(arg).slice(0, 200)}`); };
+  const deps = {
+    apply, log: (m) => logs.push(String(m)), sleep: async () => {},
+    db: { query: async (sql, params) => { queries.push({ sql, params }); return { rows: [] }; } },
+    provisioning: {
+      setInstanceStatus: async (_db, id, status, patch = {}) => { statuses.push({ id, status, patch }); },
+      recordEvent: async (_db, e) => { events.push(e); },
+      recordLivenessProbe: async () => { throw new Error('byo-host must not record a loopback liveness probe'); },
+      recordDnsNote: async () => { throw new Error('byo-host must not write a DNS note'); },
+      clearReleasedDomains: async () => { throw new Error('byo-host must not release domains'); },
+      allocatePort: async () => { throw new Error('byo-host must not allocate a port'); },
+    },
+    exec: boom('run a command'),
+    controlExec: boom('run a control-plane command'),
+    writeFile: boom('write a file'),
+    controlWriteFile: boom('write a control-plane file'),
+    doApi: () => { throw new Error('byo-host must not call a cloud API'); },
+    checkDnsTokenScope: async () => { throw new Error('byo-host must not preflight a DNS zone'); },
+    checkCaddyWiring: () => { throw new Error('byo-host must not inspect Caddy'); },
+    ingressPlaneGap: () => { throw new Error('byo-host must not probe this plane for ingress'); },
+    accountPlaneGap: () => { throw new Error('byo-host must not probe this plane for unix accounts'); },
+    getGithubToken: async () => { throw new Error('byo-host must not need a repo credential'); },
+  };
+  return { deps, queries, statuses, events, logs };
+}
+
+test('a byo-host provision touches no box: no exec, no file, no port, no database, no DNS', async () => {
+  const h = harness();
+  const r = await P.provisionInstance(byoHost, h.deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.stoodUp, false, 'the result says plainly that nothing was stood up');
+  assert.equal(r.byoHost, true);
+  // Absence: the only DB work is the status flip + the event, both through the
+  // provisioning port. No raw query — a port allocation, a createdb or a
+  // capacity count would each have to go through db.query to happen at all.
+  assert.deepEqual(h.queries, [], 'no direct SQL — capacity counting, port allocation and the DB steps all query');
+  assert.equal(r.port, undefined, 'no port is reported because none is allocated');
+});
+
+test('the row reaches active with provisioned_at set, and nothing else is patched', async () => {
+  const h = harness();
+  await P.provisionInstance(byoHost, h.deps);
+  assert.equal(h.statuses.length, 1);
+  const [{ id, status, patch }] = h.statuses;
+  assert.equal(id, 42);
+  assert.equal(status, 'active', "'active' means the platform has nothing left to do, not that it runs it");
+  assert.equal(patch.error_note, null, 'a stale note from an earlier failed run must not ride into active');
+  assert.ok(patch.provisioned_at, 'the record carries when the platform finished with it');
+  assert.equal(patch.port, undefined, 'no port is stored');
+  assert.equal(patch.db_name, undefined, 'no database is named');
+  assert.equal(h.events.length, 1);
+  assert.equal(h.events[0].event, 'active');
+  assert.match(h.events[0].detail, /byo-host/, 'the audit trail says which shape, so the absence is readable later');
+  assert.equal(h.events[0].actor, 'runner');
+});
+
+test('a dry run writes nothing at all — not even the status', async () => {
+  const h = harness({ apply: false });
+  const r = await P.provisionInstance(byoHost, h.deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.stoodUp, false);
+  assert.deepEqual(h.statuses, []);
+  assert.deepEqual(h.events, []);
+  assert.ok(h.logs.some((l) => /would mark it active/.test(l)), 'a dry run still says what it would do');
+});
+
+test('the branch is keyed on the shape, not on a missing port — a domainless row behaves the same', async () => {
+  const h = harness();
+  const r = await P.provisionInstance({ ...byoHost, domain: null }, h.deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.stoodUp, false);
+  assert.equal(h.statuses[0].status, 'active');
+});
+
+test('an already-active byo-host row stays a plain idempotent no-op', async () => {
+  const h = harness();
+  const r = await P.provisionInstance({ ...byoHost, status: 'active' }, h.deps);
+  assert.deepEqual(r, { ok: true, already: true });
+  assert.deepEqual(h.statuses, [], 're-draining an intent must not re-stamp provisioned_at');
+});
+
+test('the shape is absent from the runner shapes that DO get stood up', () => {
+  // The guard is above every preflight, so the proof that it cannot be reordered
+  // by accident is that the co-tenant/standalone standup is unreachable for it.
+  // Any other shape still reaches the first executor — that is the control.
+  const h = harness();
+  return assert.rejects(
+    P.provisionInstance({ ...byoHost, hosting_shape: 'standalone', domain: null }, h.deps),
+    /byo-host must not/,
+    'a non-byo-host shape still reaches the box steps — the branch is shape-scoped, not a global off switch',
+  );
+});

package/tests/provisioning_capacity.mjs

@@ -84,6 +84,11 @@ t('placementBox: standalone → control plane always; co-tenant → the remote b
   assert.deepEqual(placementBox('co-tenant', {}), { box: 'control-plane', shapes: ['standalone', 'co-tenant'], fixedMb: 750 });
   assert.deepEqual(placementBox('co-tenant', { remoteHost: 'cohost' }), { box: 'overflow', shapes: ['co-tenant'], fixedMb: 630 });
   assert.equal(placementBox('dedicated', {}), null);
+  // ADR 0323: a byo-host runs on the owner's own machine, so it has no box of ours and
+  // no shared ceiling — null for a STRONGER reason than dedicated's (dedicated is our
+  // droplet, just not a shared one). remoteHost must not change that answer.
+  assert.equal(placementBox('byo-host', {}), null);
+  assert.equal(placementBox('byo-host', { remoteHost: 'cohost' }), null);
 });
 
 t('placementVerdict: the ceiling refuses at N of N, the floor refuses under 256 MB free, an unmeasured floor cannot refuse', () => {

package/tests/provisioning_capacity_gate.mjs

@@ -122,11 +122,21 @@ await ta('a box with one slot left admits the create', async () => {
   assert.equal(lastCreateArgs && lastCreateArgs.slug, 'lantern');
 });
 
-await ta('an absent shape (the co-tenant default) on a local box is counted too', async () => {
+await ta('an absent shape takes the byo-host default, so a full box does NOT refuse it', async () => {
+  // This assertion INVERTED at task 1004141 (ADR 0323), and the inversion is the point.
+  // The default used to be 'co-tenant', which lands on the control plane, so a shapeless
+  // create was counted against the ceiling and could be refused box_full. The default is
+  // now 'byo-host', which runs on the owner's own machine and consumes nothing here — so
+  // refusing it for OUR capacity would be refusing a project that costs us no memory.
+  //
+  // The real trap this pins: THREE places resolve an absent shape — createInstance's
+  // coercion, paid-shape-gate's authority lookup, and this gate's placement lookup. If
+  // they disagree, the gate prices a request against a shape the row will not take, and
+  // nothing errors; you just get a 409 on a create that should have succeeded.
   reset({ count: 15 });
   const res = await post({ slug: 'lantern', no_address: true });
-  assert.equal(res.status, 409, res.raw);
-  assert.equal(res.body.error.code, 'box_full');
+  assert.equal(res.status, 201, res.raw);
+  assert.equal(capacityReads, 0, 'a shape with no box of ours must not even read the count');
 });
 
 // ── boxes the web tier cannot count are the runner's ──────────────────────────────
@@ -138,15 +148,25 @@ await ta('dedicated is its own box: never refused here, and the count is never r
   assert.equal(capacityReads, 0);
 });
 
-await ta('a co-tenant under remote-exec lands on a box this host cannot measure: admitted', async () => {
+await ta('byo-host runs on the OWNER\'s machine: never refused here, and the count is never read', async () => {
+  // ADR 0323's new shape, and the strongest form of "not our box": there is no machine
+  // of ours to place it on at all, so a full control plane must not refuse it and the
+  // count must not even be read. A full box turning away the one shape that costs us
+  // nothing would be the worst possible refusal.
   reset({ count: 15 });
-  process.env.PROVISION_REMOTE_HOST = 'overflow.example';
-  const res = await post({ slug: 'lantern', hosting_shape: 'co-tenant', no_address: true });
+  const res = await post({ slug: 'lantern', hosting_shape: 'byo-host', no_address: true });
   assert.equal(res.status, 201, res.raw);
   assert.equal(capacityReads, 0);
-  delete process.env.PROVISION_REMOTE_HOST;
 });
 
+// The co-tenant-under-remote-exec case this file used to assert HERE is now unreachable
+// through the route: ADR 0323 retires that shape and paid-shape-gate.js refuses it
+// before the capacity gate runs, so a route-level assertion would only ever be proving
+// the 403. The placement rule itself is still live — the runner reads it for the rows
+// that already carry the shape — and stays pinned at unit level in
+// tests/provisioning_capacity.mjs ('placementBox: … co-tenant → the remote box only
+// under remote-exec'). Moved rather than deleted, per the live-code rule.
+
 await ta('the live-memory floor is left to the runner: slots free + memory tight still admits', async () => {
   reset({ count: 3, mem: MEMINFO_TIGHT });
   const res = await post(WIZARD);

package/tests/provisioning_module_selection.mjs

@@ -235,7 +235,7 @@ await ta('POST /instances: the picker\'s ids ride the create request through to
 
   // Act — the body the wizard files
   const res = await post('/provisioning/instances', {
-    slug: 'mercury', hosting_shape: 'co-tenant', type: 'game', modules: ['agents', 'discord'],
+    slug: 'mercury', hosting_shape: 'byo-host', type: 'game', modules: ['agents', 'discord'],
   });
 
   // Assert
@@ -245,7 +245,7 @@ await ta('POST /instances: the picker\'s ids ride the create request through to
 
 await ta('POST /instances: an omitted modules key is still a valid create — skipping is supported, not an error', async () => {
   lastCreateArgs = null; existingRow = null;
-  const res = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'co-tenant', type: 'game' });
+  const res = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'byo-host', type: 'game' });
   assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
   assert.equal(lastCreateArgs.modules, undefined, 'nothing is invented on the owner\'s behalf');
   // …and the receipt already carries the set they will actually get.
@@ -255,7 +255,7 @@ await ta('POST /instances: an omitted modules key is still a valid create — sk
 
 await ta('POST /instances: an explicit empty selection is accepted as an answer', async () => {
   lastCreateArgs = null; existingRow = null;
-  const res = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'co-tenant', type: 'game', modules: [] });
+  const res = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'byo-host', type: 'game', modules: [] });
   assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
   assert.deepEqual(lastCreateArgs.modules, []);
 });
@@ -266,7 +266,7 @@ await ta('POST /instances: an unknown module is REFUSED and named, never silentl
   // prevent, and the reason badProjectDetail was written beside this.
   existingRow = null;
   const res = await post('/provisioning/instances', {
-    slug: 'mercury', hosting_shape: 'co-tenant', modules: ['discrod'],
+    slug: 'mercury', hosting_shape: 'byo-host', modules: ['discrod'],
   });
   assert.equal(res.status, 400, res.raw);
   assert.equal(res.body.error.code, 'bad_modules');
@@ -277,7 +277,7 @@ await ta('POST /instances: an unknown module is REFUSED and named, never silentl
 await ta('POST /instances: naming an always-on module is refused with the reason, not the generic miss', async () => {
   existingRow = null;
   const res = await post('/provisioning/instances', {
-    slug: 'mercury', hosting_shape: 'co-tenant', modules: ['memory'],
+    slug: 'mercury', hosting_shape: 'byo-host', modules: ['memory'],
   });
   assert.equal(res.status, 400, res.raw);
   assert.equal(res.body.error.code, 'bad_modules');
@@ -286,11 +286,11 @@ await ta('POST /instances: naming an always-on module is refused with the reason
 
 await ta('POST /instances: modules must be an array of strings', async () => {
   existingRow = null;
-  const notArray = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'co-tenant', modules: 'discord' });
+  const notArray = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'byo-host', modules: 'discord' });
   assert.equal(notArray.status, 400, notArray.raw);
   assert.equal(notArray.body.error.code, 'validation_failed');
 
-  const notStrings = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'co-tenant', modules: [7] });
+  const notStrings = await post('/provisioning/instances', { slug: 'mercury', hosting_shape: 'byo-host', modules: [7] });
   assert.equal(notStrings.status, 400, notStrings.raw);
   assert.equal(notStrings.body.error.code, 'validation_failed');
 });
@@ -301,7 +301,7 @@ await ta('POST /instances: a re-request never changes an existing project\'s mod
   // to hunt for one.
   existingRow = { id: 41, owner_builder_id: 7, slug: 'mercury', status: 'active', type: 'game', modules: ['agents'], detail: {} };
   const res = await post('/provisioning/instances', {
-    slug: 'mercury', hosting_shape: 'co-tenant', modules: ['discord'],
+    slug: 'mercury', hosting_shape: 'byo-host', modules: ['discord'],
   });
   assert.equal(res.status, 200, res.raw);
   assert.ok(res.body.modules_ignored, 'the dropped answer is reported, not swallowed');
@@ -589,7 +589,7 @@ await ta('POST /instances: a null answer at CREATION is accepted and stores noth
   lastCreateArgs = null; existingRow = null;
 
   const res = await post('/provisioning/instances', {
-    slug: 'mercury', hosting_shape: 'co-tenant', type: 'game', detail: { team_shape: null },
+    slug: 'mercury', hosting_shape: 'byo-host', type: 'game', detail: { team_shape: null },
   });
 
   assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);

package/tests/provisioning_onboard_mode.mjs

@@ -150,7 +150,7 @@ function post(path, body) {
 await ta('POST /instances: onboard_mode=adopt is threaded through to createInstance', async () => {
   lastCreateArgs = null;
   const res = await post('/provisioning/instances', {
-    slug: 'demo', hosting_shape: 'co-tenant', target_ref: 'example-owner/demo', onboard_mode: 'adopt',
+    slug: 'demo', hosting_shape: 'byo-host', target_ref: 'example-owner/demo', onboard_mode: 'adopt',
   });
   assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
   assert.equal(lastCreateArgs && lastCreateArgs.onboardMode, 'adopt');
@@ -158,7 +158,7 @@ await ta('POST /instances: onboard_mode=adopt is threaded through to createInsta
 
 await ta('POST /instances: onboard_mode absent → greenfield (unchanged behavior for every existing caller)', async () => {
   lastCreateArgs = null;
-  const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: 'co-tenant' });
+  const res = await post('/provisioning/instances', { slug: 'demo', hosting_shape: 'byo-host' });
   assert.equal(res.status, 201, `expected 201, got ${res.status} ${res.raw}`);
   assert.equal(lastCreateArgs && lastCreateArgs.onboardMode, 'greenfield');
 });
@@ -167,7 +167,7 @@ await ta('POST /instances: an unknown onboard_mode is REFUSED (never silently co
   // Coercing here would be worse than refusing: the caller believes it asked for one thing
   // and the runner does another. The route names the valid set so the client can fix itself.
   const res = await post('/provisioning/instances', {
-    slug: 'demo', hosting_shape: 'co-tenant', target_ref: 'a/b', onboard_mode: 'brownfield',
+    slug: 'demo', hosting_shape: 'byo-host', target_ref: 'a/b', onboard_mode: 'brownfield',
   });
   assert.equal(res.status, 400);
   assert.equal(res.body.error.code, 'bad_onboard_mode');
@@ -204,8 +204,8 @@ await ta('POST /instances: adopt WITHOUT target_ref is refused — there is no r
   // Without target_ref the runner would fall back to greenfield behavior on a row labelled
   // adopt. Refuse at the door rather than store a lie.
   for (const body of [
-    { slug: 'demo', hosting_shape: 'co-tenant', onboard_mode: 'adopt' },
-    { slug: 'demo', hosting_shape: 'co-tenant', onboard_mode: 'adopt', target_ref: '   ' },
+    { slug: 'demo', hosting_shape: 'byo-host', onboard_mode: 'adopt' },
+    { slug: 'demo', hosting_shape: 'byo-host', onboard_mode: 'adopt', target_ref: '   ' },
   ]) {
     const res = await post('/provisioning/instances', body);
     assert.equal(res.status, 400, `expected 400 for ${JSON.stringify(body)}`);