@bongos/core 1.19.772 → 1.19.774

package/scripts/gds/cli-lib.js

@@ -1166,6 +1166,42 @@ function detectWorktreeName() {
   }
 }
 
+// ---- card richness (task 1002518) ------------------------------------------
+//
+// The one place a CLI turns a /me payload into "what should this card look
+// like": three booleans — print the card at all, write the widget, open its
+// summary — that emitCard consumes directly.
+//
+// WHY THIS READS THE PAYLOAD AND NEVER require()s render-prefs.js. The ladder
+// lives in modules/builder-settings/render-prefs.js, and requiring it from here
+// would work on a full checkout and BREAK on a task-scoped dev box, which
+// carries scripts/ and src/bongos/ but not every modules/ directory (task
+// 1003098 — tree-preflight exists precisely to fail an entry point that reaches
+// for module code, and start.js is one). So the server resolves the rung and
+// ships the answers on `render.flags`; this function only picks them up.
+//
+// TWO SERVER SHAPES, deliberately. `render.flags` is the ladder (task 1002518);
+// `render.widgets_enabled` is the boolean that predates it. A CLI newer than the
+// instance it is pointed at sees only the boolean — the /me payload is not
+// version-negotiated — so the fallback is not defensive padding, it is the
+// supported path against a pinned instance, and it reconstructs exactly what
+// that boolean has always meant: card always, widget iff true, never expanded.
+// An absent or failed /me lands on the same default.
+function cardFlagsFromMe(me) {
+  const render = me && me.data && me.data.render;
+  const f = render && render.flags;
+  if (f && typeof f === 'object') {
+    return {
+      level: typeof f.level === 'string' ? f.level : null,
+      showCard: f.showCard !== false,
+      showWidget: f.showWidget === true,
+      expanded: f.expanded === true,
+    };
+  }
+  const enabled = !render || render.widgets_enabled !== false;
+  return { level: null, showCard: true, showWidget: enabled, expanded: false };
+}
+
 module.exports = {
   API_BASE,
   detectWorktreeName,
@@ -1220,4 +1256,5 @@ module.exports = {
   printOnboardingNudge,
   printCostWarning,
   printNeedsNudge,
+  cardFlagsFromMe,
 };

package/scripts/gds/fitness-migration-contraction.js

@@ -0,0 +1,50 @@
+// scripts/gds/fitness-migration-contraction.js — the ONE shape of destructive DDL a
+// module migration may carry: an ACKNOWLEDGED contract-phase DROP COLUMN on its own
+// namespaced table (task 1003092; ADR 0083 §Module-owned migrations, amended; the
+// expand-then-contract pattern of ADR 0177).
+//
+// WHY. Check 11 in fitness.js keeps module migrations ADDITIVE: there is no down
+// path, "disable a module" means "stop applying", so a DROP can only be an accident.
+// That rule met its first legitimate exception the moment a module ran an
+// expand-then-contract rename (ADR 0177 §"the fifth use"): `platform_identity_010`
+// ADDed `membership_kind` beside the legacy `role` column and kept the pair in
+// lockstep; the CONTRACT phase has to DROP the legacy column, or the rename never
+// finishes and the shim outlives its release (ADR 0174's Lineage lesson). A drop
+// that a previous migration wrote down in advance is not an accident.
+//
+// THE SHAPE, AND WHY IT IS THIS NARROW. A statement is let through only when ALL of:
+//   1. the FILE carries the `-- forward-unsafe: <reason>` pragma — the same
+//      acknowledgement scripts/gds/lint-migrations.js requires of a core migration,
+//      so one vocabulary says "this destruction is deliberate" everywhere;
+//   2. the statement is EXACTLY `ALTER TABLE <t> DROP COLUMN [IF EXISTS] <c>` and
+//      nothing else — no second clause, no DROP TABLE, no TRUNCATE, no bare DROP
+//      CONSTRAINT (which stays a violation even with the pragma);
+//   3. <t> is inside the module's own namespace (or its grandfathered legacy set),
+//      the same test the namespace check applies to every ALTER.
+// The pragma does not turn the check off for the file: every OTHER destructive
+// statement in an acknowledged file is still flagged. PURE — no fs, no process.
+'use strict';
+
+// Same single-line acknowledgement lint-migrations.js captures (ACK_RE there).
+const ACK_RE = /^\s*--\s*forward-unsafe\s*:\s*(.+)$/im;
+
+// Exactly one column drop, on one table, and nothing else in the statement.
+const COLUMN_DROP_RE = /^\s*alter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?("?[\w.]+"?)\s+drop\s+column\s+(?:if\s+exists\s+)?"?\w+"?\s*$/i;
+
+// Is the migration FILE acknowledged as forward-unsafe? Read on the RAW sql — the
+// pragma is a comment, and the destructive-DDL scan strips comments first.
+function acknowledgedContraction(rawSql) {
+  const m = ACK_RE.exec(String(rawSql == null ? '' : rawSql));
+  return m ? m[1].trim() : null;
+}
+
+// Is THIS statement the one allowed shape? `inNamespace(table)` is the caller's
+// namespace predicate (fitness.js owns the <key>_ / legacy-set rule).
+function isAcknowledgedColumnContraction(stmt, { acknowledged, inNamespace }) {
+  if (!acknowledged) return false;
+  const m = COLUMN_DROP_RE.exec(stmt);
+  if (!m) return false;
+  return inNamespace(m[1]);
+}
+
+module.exports = { acknowledgedContraction, isAcknowledgedColumnContraction };

package/scripts/gds/fitness.js

@@ -827,6 +827,12 @@ function isConstraintWidening(stmt, reAdded) {
   return reAdded.has(m[1].replace(/"/g, ''));            // re-added same-named constraint → widening
 }
 
+// The ONE destructive shape a module may carry: an ACKNOWLEDGED contract-phase
+// `ALTER TABLE <own table> DROP COLUMN <c>` (task 1003092 — the expand-then-contract
+// rename of ADR 0177 has to finish; ADR 0083 §Module-owned migrations, amended). The
+// pragma is read off the RAW sql (it is a comment); everything else here still runs.
+const { acknowledgedContraction, isAcknowledgedColumnContraction } = require('./fitness-migration-contraction.js');
+
 // Pure: violations for ONE module's migration SQL. Exported for the negative test.
 function moduleMigrationViolations(key, sql) {
   const ns = moduleNamespace(key);
@@ -835,8 +841,11 @@ function moduleMigrationViolations(key, sql) {
   const violations = [];
   // additive — scan per statement so an ALTER…DROP never spans a `;`
   const reAdded = reAddedConstraintNames(clean);
+  const acknowledged = acknowledgedContraction(sql);
+  const ownTable = (t) => inNamespace(t, ns, legacy);
   for (const stmt of clean.split(';')) {
     if (isConstraintWidening(stmt, reAdded)) continue; // additive CHECK-enum widening (task 1978)
+    if (isAcknowledgedColumnContraction(stmt, { acknowledged, inNamespace: ownTable })) continue; // contract phase (task 1003092)
     for (const d of DESTRUCTIVE_DDL) {
       if (d.re.test(stmt)) {
         violations.push(`module "${key}" migration uses destructive DDL (${d.label}) — module migrations must be ADDITIVE; disabling a module stops applying, it never drops (ADR 0083 §Decision #5).`);
@@ -1205,6 +1214,15 @@ const CHECKS = [
   // migrations: same shared, monotonic, human-allocated number line, and until this
   // landed only one of the two was enforced. An ADR number is a citation target, so a
   // duplicate is wrong forever (ADR 0195).
+  // Check 33 — task 1003819: a module declares what it contributes, and nothing
+  // checked that a declared seam is actually WIRED. verifyPortsSatisfied asks the
+  // opposite question (every `consumes` has a provider) and validateManifest checks
+  // only the SHAPE, so a contributes entry whose artifact was never shipped — or was
+  // renamed out from under the manifest — boots silent: every consumer skips it the
+  // same way it correctly skips a real declarative-only entry. CI, not boot: nothing
+  // crashes later, so a start-up refusal would trade an outage risk for a cosmetic
+  // one (ADR 0289). Rationale + the seam→consumer table live in that file.
+  require('./seam-wiring-guard.js').checkSeamWiring,
   require('./adr-namespace.js').checkAdrNumbering, require('./exec-path-guard.js').checkExecPathsStatic, // Check 32 — task 1003371 / B50: what the server EXECUTES, out of whose tree — the blind spot all three 2026-08-29 CRITICALs shared. Rationale + reviewed exemptions live in that file. Sharing Check 31's line (the 19c/19d + 23/24 precedent above): fitness.js is AT the 1,500 ratchet and a new check cannot afford a line until task 1003825 buys it back.
 ];
 

package/scripts/gds/land-watch.js

@@ -122,9 +122,15 @@ function buildShippedEnvelope(crumb, task) {
     title: inputs.title || (task && task.title) || `Task #${crumb.taskId}`,
     valueSummary: inputs.valueSummary || (task && task.value_summary) || '',
   });
+  // task 1002518: prefer the rung the shipping session actually resolved, so the
+  // later-rendered shipped card matches the one it printed. A breadcrumb written
+  // by an older CLI carries only `widgetsEnabled`, which still reads correctly.
+  const flags = (crumb.cardFlags && typeof crumb.cardFlags === 'object')
+    ? crumb.cardFlags
+    : { showWidget: crumb.widgetsEnabled !== false, expanded: false };
   return {
-    widgets_enabled: crumb.widgetsEnabled !== false,
-    html: shipCard.renderCardHtml(model),
+    widgets_enabled: flags.showWidget === true,
+    html: shipCard.renderCardHtml(model, { expanded: flags.expanded === true }),
     markdown: shipCard.renderMonospaceCard(model),
     warnings: [],
     title: `task_${crumb.taskId}_card`,

package/scripts/gds/provision-config.js

@@ -177,16 +177,16 @@ function loadDeps() {
   // (fitness Check 16b / task 2135). A vanilla core that neither ships nor enables the
   // module never resolves it → no MODULE_NOT_FOUND on a fresh boot. Null here → federation
   // dormant (shouldFederate skips) → the instance owns its auth, byte-identical to today.
-  let platformIdentity = null, hubKeys = null;
+  let platformIdentity = null, hubKeys = null, projectCatalog = null;
   const PI_KEY = 'platform-identity';
   let piEnabled = false;
   try { piEnabled = require(path.join(REPO_ROOT, 'src/modules')).isModuleEnabled(PI_KEY); } catch { piEnabled = false; }
   if (piEnabled) {
     const piBase = path.join(REPO_ROOT, 'modules', PI_KEY);
-    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); }
-    catch { platformIdentity = null; hubKeys = null; }
+    try { platformIdentity = require(path.join(piBase, 'platform-identity')); hubKeys = require(path.join(piBase, 'hub-keys')); projectCatalog = require(path.join(piBase, 'project-catalog')); }
+    catch { platformIdentity = null; hubKeys = null; projectCatalog = null; }
   }
-  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys };
+  _deps = { pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog };
   return _deps;
 }
 

package/scripts/gds/provision-disconnect.js

@@ -0,0 +1,90 @@
+'use strict';
+// provision-disconnect.js — "Disconnect from Bongos entirely": the runner leg (task 1003249,
+// ADR 0290).
+//
+// WHY. A teardown deliberately KEEPS a project's database, dumps and address (ADR 0181), so
+// taking a project offline is always reversible. The owner asked for a separate, truer delete.
+// This is it, and it is the exception ADR 0181 names: owner-initiated only, behind a typed-name
+// confirm the route checks server-side (modules/provisioning/routes/disconnect.js).
+//
+// ORDER IS THE SAFETY PROPERTY. The teardown runs first (units stopped, Caddy block gone, DNS
+// parked, deploy key revoked). Then the erase. Then the catalog, membership and client rows
+// leave the map. The provisioning row is deleted LAST, and only when everything before it
+// succeeded: the row is what lets the runner retry, so a failure anywhere leaves the row intact
+// (an erase or forget failure returns a retryable { ok:false }; a teardown throw propagates).
+// Deleting the row is what releases the name (slug UNIQUE), the port (allocatePort reads every
+// row) and the address (the next standup UPSERTs it).
+//
+// The GitHub repository is never touched, and neither is the GitHub App the owner registered for
+// sign-in — GitHub offers no API to delete an App; the manage page tells the owner where it is.
+
+const path = require('node:path');
+const { CONFIG } = require('./provision-config.js');
+const { dbName, instanceDbRole, instanceStateDir, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const { webEnvPath } = require('./provision-units.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
+const { catalogOriginForInstance, ownerGithubIdForInstance } = require('../../modules/provisioning/catalog-bridge.js');
+const { deleteInstance } = require('../../modules/provisioning/disconnect.js');
+
+// The dump filename db-backup-nightly.sh writes — <db>-YYYY-MM-DDTHHMMSSZ.sql.gz — matched
+// EXACTLY. The nightly prune's own `<db>-*.sql.gz` would let a project named `test` erase
+// `test-nk`'s dumps, which is harmless for a 30-day prune and unacceptable for an erase. PURE.
+function dumpGlob(inst) {
+  const d = '[0-9]';
+  return `${dbName(inst)}-${d.repeat(4)}-${d.repeat(2)}-${d.repeat(2)}T${d.repeat(6)}Z.sql.gz`;
+}
+
+// The erase, in order: the database before the role that owns it; the dumps; the env dir and
+// state dir; the per-project checkout (standalone only — a co-tenant runs from the shared one);
+// the unix account last, idempotently. Every path derives from a slug the caller has already
+// validated. PURE.
+function eraseCommands(inst, { privileged = false } = {}) {
+  const sudo = privileged ? 'sudo ' : '';
+  const asPg = (cmd) => (privileged ? `sudo -u postgres ${cmd}` : cmd);
+  const user = instanceUser(inst);
+  const cmds = [
+    asPg(`dropdb --if-exists --force ${dbName(inst)}`),
+    asPg(`psql -v ON_ERROR_STOP=1 -d postgres -c 'DROP ROLE IF EXISTS "${instanceDbRole(inst)}"'`),
+    `${sudo}find ${CONFIG.backupDir} -maxdepth 1 -type f -name '${dumpGlob(inst)}' -delete`,
+    `${sudo}rm -rf ${path.posix.dirname(webEnvPath(inst))} ${instanceStateDir(inst)}`,
+  ];
+  if (inst.hosting_shape === 'standalone') cmds.push(`${sudo}rm -rf ${standaloneRoot(inst)}`);
+  cmds.push(`if id -u ${user} >/dev/null 2>&1; then ${sudo}userdel ${user}; fi`);
+  return cmds;
+}
+
+async function disconnectInstance(inst, deps) {
+  const { db, exec, log, apply, privileged } = deps;
+  // Every rm -rf below is built from the slug, so it is re-validated here rather than trusted.
+  if (!inst || !isValidSlug(inst.slug)) return { ok: false, error: `refusing to disconnect: invalid slug ${JSON.stringify(inst && inst.slug)}` };
+  log(`disconnect ${inst.slug} (status=${inst.status})`);
+  // A teardown returns ok or throws; a throw ends the run here, before anything is erased.
+  await teardownInstance(inst, deps);
+
+  if (inst.hosting_shape !== 'dedicated') {
+    const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
+    for (const cmd of eraseCommands(inst, { privileged })) {
+      try { boxExec(cmd); }
+      catch (e) { return { ok: false, error: `erase step failed (${cmd.split(' ').slice(0, 3).join(' ')}): ${(e && e.message) || e}` }; }
+    }
+  }
+
+  const origin = catalogOriginForInstance(inst);
+  if (origin && deps.projectCatalog) {
+    if (apply) {
+      try {
+        const ownerGithubId = await ownerGithubIdForInstance(db, inst);
+        const gone = await deps.projectCatalog.forgetOwnedProject({ clientId: inst.slug, origin, ownerGithubId }, { pool: db });
+        log(`  catalog: removed ${gone.project} project row, ${gone.client} client, ${gone.memberships} membership(s)`);
+      } catch (e) { return { ok: false, error: `catalog forget failed: ${(e && e.message) || e}` }; }
+    } else log(`  would remove ${origin} from the catalog`);
+  }
+
+  if (!apply) { log(`  would delete the provisioning row for ${inst.slug}`); return { ok: true }; }
+  await deleteInstance(db, inst.id);
+  log(`  ✓ ${inst.slug} disconnected — row deleted; name, port and address released`);
+  return { ok: true };
+}
+
+module.exports = { disconnectInstance, eraseCommands, dumpGlob };

package/scripts/gds/provision-teardown.js

@@ -0,0 +1,108 @@
+'use strict';
+// provision-teardown.js — reverse the provisioning runbook for one instance
+// (idempotent). Split out of provision.js (task 1002897), which sat at the size
+// ratchet; provision.js re-exports teardownInstance, so its callers are unchanged.
+//
+// What a teardown takes down: the service + backup units, the per-instance Caddy
+// snippet, the DNS record (parked at the blackhole), and the deploy key. What it
+// deliberately LEAVES (ADR 0181): the database, its dumps and the checkout (data is
+// precious), and the row's `domain` + `port` — a revive re-uses exactly that address,
+// and step 5 of the next standup UPSERTs it straight back.
+
+const path = require('node:path');
+const { CONFIG, REPO_ROOT } = require('./provision-config.js');
+const { dbName, deployKeyPath, deployKeyTitle, parseTargetRef, resolveOwnerGithubToken } = require('./provision-repo.js');
+const { backupServicePath, backupTimerPath, backupUnitName, serviceUnitPath } = require('./provision-units.js');
+const { caddySnippetPath, dnsReleaseEnv } = require('./provision-net.js');
+const apexMod = require('./instance-apex.js');
+const { isReservedHostname } = require('../../modules/provisioning/provisioning.js');
+
+async function teardownInstance(inst, deps) {
+  const { db, provisioning, exec, log, apply, privileged } = deps;
+  const controlExec = deps.controlExec || exec;
+  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
+  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
+  // box, where it was never installed (that would allowFail-noop and leave the real
+  // control-plane unit running). Co-tenant + dedicated are unchanged.
+  const boxExec = inst.hosting_shape === 'standalone' ? controlExec : exec;
+  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
+  log(`teardown ${inst.slug} (status=${inst.status})`);
+  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
+  if (inst.hosting_shape !== 'dedicated') {
+    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
+    // Stop + remove the nightly backup units too (task 2213; the dir + dumps stay — precious data, like the DB below), then reset-failed (task 1003940): a removed unit's FAILED state outlives its file, so `systemctl --failed` listed torn-down ghosts for weeks.
+    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
+    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
+    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
+    boxExec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
+    // The site snippet standup step 6 wrote: while it stays, Caddy proxies the hostname to
+    // a port nothing listens on and every visitor gets a 502 (task 1002897). Not precious.
+    boxExec(`${sudoP}rm -f ${caddySnippetPath(inst)}`, { allowFail: true });
+    boxExec(`${sudoP}systemctl reload caddy`, { allowFail: true });
+    // Left for an operator (data is precious), naming ONLY what this row created —
+    // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
+    if (inst.db_name) log(`  (left for the operator: dropdb ${dbName(inst)}, prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz)`);
+  } else if (apply && deps.doApi && inst.droplet_id) {
+    await deps.doApi.deleteDroplet(inst.droplet_id);
+  }
+  parkAddress(inst, { controlExec, log, apply });
+  // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
+  // checkout itself is deliberately left in place (data is precious), so the key
+  // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project
+  // silently keeping durable read access to the owner's private repo is the exact
+  // shape a teardown exists to end. A missing token / API hiccup never blocks it.
+  if (inst.hosting_shape === 'standalone' && inst.target_ref) {
+    const repo = parseTargetRef(inst.target_ref);
+    if (repo) {
+      try {
+        const token = await resolveOwnerGithubToken(inst, deps, { tag: '[teardown]' });
+        if (token) {
+          const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
+          if (apply) {
+            const keys = await ghRepos.listDeployKeys(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
+            const ours = keys.find((k) => k.title === deployKeyTitle(inst));
+            if (ours) {
+              await ghRepos.deleteDeployKey(token, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
+              log(`  revoked the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name}`);
+            }
+          } else log(`  would revoke the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name} if present`);
+        } else {
+          log(`  (deploy-key revoke skipped: no usable owner credential — if ${repo.owner}/${repo.name} carries a "${deployKeyTitle(inst)}" deploy key, remove it in the repo's settings)`);
+        }
+      } catch (e) { log(`  (deploy-key revoke skipped: ${e && e.message})`); }
+      boxExec(`rm -f ${deployKeyPath(inst)} ${deployKeyPath(inst)}.pub`, { allowFail: true });
+    }
+  }
+  if (apply) {
+    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
+    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
+  }
+  log(`  ✓ ${inst.slug} torn down`);
+  return { ok: true };
+}
+
+// Park the row's hostname at the RFC 5737 blackhole — the release a re-point already
+// uses (ADR 0200 §2: parked, not deleted, so no NXDOMAIN window gets negative-cached).
+// Runs on the CONTROL PLANE for every shape: the hook needs the Cloudflare token, which
+// never leaves it. BEST-EFFORT: a failure is logged and never strands the row. A
+// platform-reserved hostname is refused outright — standup would never have been given
+// one, and blackholing it would take the platform's own record down.
+function parkAddress(inst, { controlExec, log, apply }) {
+  if (!inst.domain) return;
+  if (isReservedHostname(inst.domain, apexMod.instanceApex())) {
+    log(`  [dns] NOT parking ${inst.domain}: a platform-reserved hostname is never blackholed by a teardown`);
+    return;
+  }
+  if (!CONFIG.dnsHook) {
+    log(`  [dns] cannot park ${inst.domain} (BOX_DNS_HOOK unset) — point its A record at 192.0.2.1 by hand`);
+    return;
+  }
+  const env = dnsReleaseEnv(inst.domain);
+  log(`  [dns] park ${inst.domain} -> ${env.BOX_IP} (blackhole, zone ${env.CLOUDFLARE_ZONE}) via ${CONFIG.dnsHook}`);
+  if (!apply) return;
+  try { controlExec(CONFIG.dnsHook, { env }); }
+  catch (e) { log(`  ⚠ could not park ${inst.domain}: ${(e && e.message) || e} — its A record still points at the platform`); }
+}
+
+module.exports = { teardownInstance };

package/scripts/gds/provision.js

@@ -54,6 +54,8 @@ const { APP_USER, alreadyScaffolded, buildCorePinRefreshCommit, dbCreateCmd, dbN
 const { backupScriptPath, backupService, backupServicePath, backupTimer, backupTimerPath, backupUnitName, instanceManifestCmd, originEnvVarsFor, serviceUnit, serviceUnitPath, settingsConsumed, settingsEnvVarsFor, upsertEnvVars, webEnvBody, webEnvPath } = require('./provision-units.js');
 const { caddyBlock, caddySnippetPath, checkDnsTokenScope, classifyZoneScope, dnsReleaseEnv, dnsUpsertEnv, federateInstance, federationHubOrigin, healthzCmd, identityCmd, identityVerdict, shouldFederate, zoneForDomain } = require('./provision-net.js');
 const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.js');
+const { teardownInstance } = require('./provision-teardown.js');
+const { disconnectInstance } = require('./provision-disconnect.js');
 
 function makeExec({ apply, log = console.log, remoteHost = null, remoteCwd = null, sshOpts = '' }) {
   // `shown` (task 1003140): what to LOG in place of the command text — for a command
@@ -1017,69 +1019,6 @@ async function restartInstance(inst, deps) {
   return { ok: true, healthy };
 }
 
-// ---------------------------------------------------------------------------
-// Teardown one instance (reverse the runbook; idempotent).
-// ---------------------------------------------------------------------------
-async function teardownInstance(inst, deps) {
-  const { db, provisioning, exec, log, apply, privileged } = deps;
-  // Tear down on the box the instance actually RAN on: a standalone ran control-plane-
-  // local (task 2074), so disable/remove its unit HERE — not on the remote co-hosting
-  // box, where it was never installed (that would allowFail-noop and leave the real
-  // control-plane unit running). Co-tenant + dedicated are unchanged.
-  const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
-  const sudoP = privileged ? 'sudo ' : '';   // systemctl / rm-under-/etc escalation (task 2066)
-  log(`teardown ${inst.slug} (status=${inst.status})`);
-  if (apply) await provisioning.setInstanceStatus(db, inst.id, 'tearing_down');
-  if (inst.hosting_shape !== 'dedicated') {
-    boxExec(`${sudoP}systemctl disable --now ${inst.slug}`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${serviceUnitPath(inst)}`, { allowFail: true });
-    // Stop + remove the nightly backup units too (task 2213; the dir + dumps stay — precious data, like the DB below), then reset-failed (task 1003940): a removed unit's FAILED state outlives its file, so `systemctl --failed` listed torn-down ghosts for weeks.
-    boxExec(`${sudoP}systemctl disable --now ${backupUnitName(inst)}.timer`, { allowFail: true });
-    boxExec(`${sudoP}rm -f ${backupServicePath(inst)} ${backupTimerPath(inst)}`, { allowFail: true });
-    boxExec(`${sudoP}systemctl daemon-reload`, { allowFail: true });
-    boxExec(`${sudoP}systemctl reset-failed ${inst.slug}.service ${backupUnitName(inst)}.service`, { allowFail: true });
-    // Left for an operator (data is precious), naming ONLY what this row created —
-    // teardown now takes 'requested'/'error'. `port` + `domain` stay held: ADR 0181.
-    const dumps = inst.db_name ? [`dropdb ${dbName(inst)}`, `prune ${CONFIG.backupDir}/${dbName(inst)}-*.sql.gz`] : [];
-    log(`  (left for the operator: ${dumps.concat([`remove the Caddy block for ${inst.slug} if one was written`]).join(', ')})`);
-  } else if (apply && deps.doApi && inst.droplet_id) {
-    await deps.doApi.deleteDroplet(inst.droplet_id);
-  }
-  // Revoke the instance's deploy key (ADR 0176) and remove its local halves. The
-  // checkout itself is deliberately left in place (data is precious), so the key
-  // files must NOT ride along — and a revoke skip must be LOUD: a torn-down project
-  // silently keeping durable read access to the owner's private repo is the exact
-  // shape a teardown exists to end. A missing token / API hiccup never blocks it.
-  if (inst.hosting_shape === 'standalone' && inst.target_ref) {
-    const repo = parseTargetRef(inst.target_ref);
-    if (repo) {
-      try {
-        const token = await resolveOwnerGithubToken(inst, deps, { tag: '[teardown]' });
-        if (token) {
-          const ghRepos = deps.githubRepos || require(path.join(REPO_ROOT, 'src/bongos/github-repos'));
-          if (apply) {
-            const keys = await ghRepos.listDeployKeys(token, { owner: repo.owner, name: repo.name, fetchImpl: deps.fetchImpl });
-            const ours = keys.find((k) => k.title === deployKeyTitle(inst));
-            if (ours) {
-              await ghRepos.deleteDeployKey(token, { owner: repo.owner, name: repo.name, keyId: ours.id, fetchImpl: deps.fetchImpl });
-              log(`  revoked the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name}`);
-            }
-          } else log(`  would revoke the "${deployKeyTitle(inst)}" deploy key on ${repo.owner}/${repo.name} if present`);
-        } else {
-          log(`  (deploy-key revoke skipped: no usable owner credential — if ${repo.owner}/${repo.name} carries a "${deployKeyTitle(inst)}" deploy key, remove it in the repo's settings)`);
-        }
-      } catch (e) { log(`  (deploy-key revoke skipped: ${e && e.message})`); }
-      boxExec(`rm -f ${deployKeyPath(inst)} ${deployKeyPath(inst)}.pub`, { allowFail: true });
-    }
-  }
-  if (apply) {
-    await provisioning.setInstanceStatus(db, inst.id, 'torn_down', { torn_down_at: new Date().toISOString() });
-    await provisioning.recordEvent(db, { instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'torn_down', detail: 'torn down by runner', actor: 'runner' });
-  }
-  log(`  ✓ ${inst.slug} torn down`);
-  return { ok: true };
-}
-
 // ---------------------------------------------------------------------------
 // GitHub App Manifest conversion + cred placement (task 2080, ADR 0133).
 // The web tier stored GitHub's temporary `code` on a provisioning_oauth_manifests
@@ -1298,6 +1237,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'domain-attach') result = await domainAttachInstance(inst, deps);
       else if (intent.action === 'settings-apply') result = await settingsApplyInstance(inst, deps);
       else if (intent.action === 'restart') result = await restartInstance(inst, deps);
+      else if (intent.action === 'disconnect') result = await disconnectInstance(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) {
@@ -1425,8 +1365,8 @@ async function main() {
   const slug = args[1] && !args[1].startsWith('--') ? args[1] : null;
   if ((cmd === 'provision' || cmd === 'teardown') && !slug) { console.error(`${cmd} needs a <slug>`); process.exit(2); }
 
-  let pool, provisioning, DoApi, platformIdentity, hubKeys;
-  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys } = loadDeps()); }
+  let pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog;
+  try { ({ pool, provisioning, DoApi, platformIdentity, hubKeys, projectCatalog } = loadDeps()); }
   catch (e) { console.error(`cannot load DB layer (run this on the control plane): ${e.message}`); process.exit(1); }
 
   // Box-target executor (remote over SSH when PROVISION_REMOTE_HOST is set, else
@@ -1446,6 +1386,7 @@ async function main() {
     // Cross-site identity (ADR 0141 §4). Null on a non-hub control plane → federation
     // dormant; shouldFederate() then skips and the instance owns its auth (as today).
     platformIdentity, hubKeys,
+    projectCatalog,   // the disconnect leg's catalog forget (task 1003249); null off the hub
   };
 
   let result;