@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/prove-strict-versioning.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+// scripts/bongos/prove-strict-versioning.js — does strict versioning actually hold
+// on THIS instance? (BV1.R30a, task 1003716, goal 1000086; the harness BV1.R30
+// runs. ADR 0250, ADR 0263, ADR 0265.)
+//
+// ADR 0250 built five rules and ADR 0265 added a sixth, all enforced server-side.
+// Nothing could tell you whether they HOLD on a given instance — R30's brief said
+// "run each query against live and capture its output verbatim", which in practice
+// meant hand-assembling a dozen API calls and reading the results by eye. That is
+// how a proof ends up asserting what someone hoped rather than what the instance
+// returned.
+//
+// THE CORE SHIPS TO ANY INSTANCE, so this is not a one-off for the BONGOS-V1
+// cutover. "Is my scope actually closed?" is a question every instance will ask,
+// and its answer should not depend on someone reproducing a call sequence.
+//
+// Two halves, and the split is deliberate:
+//
+//   CHECKS are read-only and always run. They count the live rows and say what
+//   they found, whether or not it is what the rules promise.
+//
+//   PROBES (--probe) attempt writes that MUST be refused. Each one is chosen so a
+//   refusal is the only legal outcome, and it is SKIPPED WITH A STATED REASON when
+//   the preconditions for a guaranteed refusal are absent — a probe that could
+//   succeed is a mutation, not a proof. Each also RE-READS afterwards: a 409 that
+//   nevertheless mutated is the failure mode worth catching, and no amount of
+//   reading the status code finds it.
+//
+// Exit code is non-zero if any check fails, so this can become a gate.
+//
+// Usage:
+//   node scripts/bongos/prove-strict-versioning.js [--probe] [--json]
+//   CLOUDBONGOS_API_BASE=https://cloudbongos.com node scripts/bongos/prove-strict-versioning.js --probe
+
+// apiCall is the ONE HTTP client for this directory: it resolves the instance
+// base and bearer, returns { status, ok, data } WITHOUT throwing on an HTTP
+// status (exactly what a refusal probe needs), and routes through the
+// no-keep-alive dispatcher — a bare fetch() leaves sockets armed and turns a
+// natural exit into a hang.
+const { apiCall, hasFlag, cliExit, API_BASE } = require('./cli-lib');
+
+// The statuses that mean a task is FINISHED — one vocabulary, declared once
+// (BV1.R01, task 1003588). Everything else holds its goal, and therefore its
+// version, open. Read from the module rather than re-listed here so this file
+// cannot drift from the rule it is checking.
+const { TERMINAL_STATUSES } = require('../../modules/lifecycle/task-status');
+const NON_TERMINAL = ['backlog', 'ready', 'active', 'blocked', 'completed', 'confirmed']
+  .filter((s) => !TERMINAL_STATUSES.includes(s));
+
+// A goal that is no longer open must hold no unfinished work (ADR 0250 D2/D3).
+const CLOSED_GOAL_STATUSES = ['achieved', 'archived'];
+
+// A version's catch-all goal, by the two shapes the codebase has used. The
+// em-dash form is what `generalGoalTitle` matches; "Work with no goal yet" is
+// BONGOS-V1's, and the mismatch between them is exactly why 47 tasks went
+// homeless unnoticed (R31, task 1003711). Match BOTH, or this proof inherits the
+// blind spot it exists to close.
+const CATCH_ALL = (title, versionId) =>
+  title === `${versionId} — general` || /^work with no goal yet$/i.test(String(title || '').trim());
+
+// The API returns a refusal code in two shapes depending on which `res.fail`
+// overload the route used — a bare string, or an object carrying `.code`/`.error`.
+// Rendering the object straight gives `[object Object]`, which tells a reader
+// nothing about WHICH rule fired. Normalise both to the code.
+function errorCode(body) {
+  const e = body && body.error;
+  if (!e) return null;
+  if (typeof e === 'string') return e;
+  return e.code || e.error || e.message || null;
+}
+
+/** GET a Bongos API path, returning the parsed body. Throws on a non-2xx. */
+async function get(path) {
+  const r = await apiCall('GET', `/api/bongos${path}`);
+  if (!r.ok) throw new Error(`GET ${path} → ${r.status}`);
+  return r.data;
+}
+
+/** POST a probe. Returns the status WITHOUT throwing — the status IS the proof. */
+async function probePost(path, body) {
+  const r = await apiCall('POST', `/api/bongos${path}`, body || {});
+  return { status: r.status, body: r.data, why: errorCode(r.data) };
+}
+
+/** Every non-terminal task on the instance, one status at a time (the list route filters by one). */
+async function allNonTerminalTasks() {
+  const out = [];
+  for (const status of NON_TERMINAL) {
+    const j = await get(`/tasks?status=${encodeURIComponent(status)}&limit=1000`);
+    out.push(...(j.tasks || []));
+  }
+  return out;
+}
+
+const results = [];
+/** Record one check. `ok` false makes the whole run exit non-zero. */
+function record(id, ok, headline, detail) {
+  results.push({ id, ok, headline, detail: detail || null });
+}
+
+async function runChecks() {
+  const [versionsRes, goalsRes, tasks] = await Promise.all([
+    get('/versions'), get('/goals'), allNonTerminalTasks(),
+  ]);
+  const versions = versionsRes.versions || [];
+  const goals = goalsRes.goals || [];
+  const byGoal = new Map(goals.map((g) => [String(g.id), g]));
+  const byVersion = new Map(versions.map((v) => [String(v.id), v]));
+
+  // C1 — a closed goal holding unfinished work (ADR 0250 D2/D3).
+  const c1 = tasks.filter((t) => {
+    const g = t.goal_id == null ? null : byGoal.get(String(t.goal_id));
+    return g && CLOSED_GOAL_STATUSES.includes(g.status);
+  });
+  const c1Goals = [...new Set(c1.map((t) => String(t.goal_id)))];
+  record('C1', c1.length === 0,
+    `${c1Goals.length} closed goal(s) holding ${c1.length} unfinished task(s)`,
+    c1Goals.map((id) => `goal ${id} (${byGoal.get(id).status}) holds ${c1.filter((t) => String(t.goal_id) === id).length}`));
+
+  // C2 — every task has a real goal (ADR 0250 D4). The two populations are
+  // reported apart because they fail for different reasons: a catch-all is a
+  // goal nobody chose, a null is a goal nobody assigned, and only the first is
+  // visible to anything that reasons per goal.
+  const nullGoal = tasks.filter((t) => t.goal_id == null);
+  const inCatchAll = tasks.filter((t) => {
+    const g = t.goal_id == null ? null : byGoal.get(String(t.goal_id));
+    return g && CATCH_ALL(g.title, g.version_id);
+  });
+  record('C2', nullGoal.length === 0 && inCatchAll.length === 0,
+    `${nullGoal.length} task(s) with no goal, ${inCatchAll.length} in a catch-all goal`,
+    [`null goal_id: ${nullGoal.length}`, `catch-all: ${inCatchAll.length}`,
+     ...[...new Set(inCatchAll.map((t) => String(t.goal_id)))].map((id) => `  catch-all goal ${id} — ${byGoal.get(id).title}`)]);
+
+  // C3 — one version builds, at most one plans (ADR 0250 D5; R04 + R19).
+  const building = versions.filter((v) => v.status === 'building');
+  const planning = versions.filter((v) => v.status === 'planning');
+  record('C3', building.length === 1 && planning.length <= 1,
+    `${building.length} building, ${planning.length} planning`,
+    [`building: ${building.map((v) => v.id).join(', ') || '(none)'}`,
+     `planning: ${planning.map((v) => v.id).join(', ') || '(none)'}`]);
+
+  // C4 — the next version is scoped: every goal on the planning version carries
+  // at least one done-when criterion (R29b). A criterion-less goal can never
+  // achieve, so it entombs its version the way the catch-alls entombed V1.
+  if (planning.length === 0) {
+    record('C4', true, 'no planning version — nothing to scope yet (not a failure)', null);
+  } else {
+    const pv = planning[0];
+    const pvGoals = goals.filter((g) => String(g.version_id) === String(pv.id) && g.status === 'open');
+    const detail = [];
+    let missing = 0;
+    for (const g of pvGoals) {
+      const full = await get(`/goals/${g.id}`);
+      const n = (full.criteria || []).length;
+      if (n === 0) { missing++; detail.push(`goal ${g.id} — NO criteria — ${g.title}`); }
+    }
+    record('C4', missing === 0,
+      `${pv.id}: ${pvGoals.length - missing}/${pvGoals.length} goal(s) carry a done-when criterion`, detail);
+  }
+
+  // C5 — beyond R30's original four. R32 (task 1003713) made a close refuse to
+  // leave work behind; this is the same rule read from the other end, and it
+  // catches what closed BEFORE that rule existed.
+  const onShipped = tasks.filter((t) => {
+    const v = byVersion.get(String(t.version_id));
+    return v && v.status === 'shipped';
+  });
+  record('C5', onShipped.length === 0,
+    `${onShipped.length} unfinished task(s) stranded on a shipped version`,
+    onShipped.slice(0, 20).map((t) => `task ${t.id} (${t.status}) on ${t.version_id}`));
+
+  // C6 — a task and its goal must be on the SAME version. `PATCH /tasks/:id`
+  // refuses a cross-version link with 409 `goal_version_mismatch`, but nothing
+  // has ever checked the rows that predate that rule — and the hierarchy is
+  // version → goal → task, so a split row is counted by one version's rollup
+  // while appearing under the other version's goal. It is also how C5 and a
+  // by-goal count can honestly disagree about the same task, which is exactly
+  // how this check got written.
+  const split = tasks.filter((t) => {
+    const g = t.goal_id == null ? null : byGoal.get(String(t.goal_id));
+    return g && String(g.version_id) !== String(t.version_id);
+  });
+  record('C6', split.length === 0,
+    `${split.length} task(s) whose goal lives on a different version`,
+    split.slice(0, 20).map((t) => `task ${t.id} on ${t.version_id}, but goal ${t.goal_id} is on ${byGoal.get(String(t.goal_id)).version_id}`));
+
+  return { versions, goals, tasks, building, planning, byGoal };
+}
+
+async function runProbes(ctx) {
+  const { goals, tasks, building, byGoal } = ctx;
+  const out = [];
+  /** A probe is only a proof when refusal is the sole legal outcome. */
+  const skip = (id, why) => out.push({ id, skipped: true, why });
+
+  // P1 — R03: a goal cannot join a version that is already building.
+  if (building.length === 0) {
+    skip('P1', 'no building version, so a refusal is not guaranteed');
+  } else {
+    const before = (await get('/goals')).goals.length;
+    const r = await probePost('/goals', { version_id: building[0].id, title: '__probe__ R03 refusal — must never be created' });
+    const after = (await get('/goals')).goals.length;
+    out.push({ absent: r.status === 404, id: 'P1', rule: 'R03 — goal onto a building version', status: r.status,
+      refused: r.status === 409, error: r.why, mutated: after !== before });
+  }
+
+  // P2 — R10: archive refuses without a disposition. Aimed at a goal VERIFIED to
+  // hold open tasks, because a goal holding none archives legitimately — that is
+  // the one shape of this probe that would destroy something.
+  const held = new Map();
+  for (const t of tasks) if (t.goal_id != null) held.set(String(t.goal_id), (held.get(String(t.goal_id)) || 0) + 1);
+  const target = goals.find((g) => g.status === 'open' && (held.get(String(g.id)) || 0) > 0);
+  if (!target) {
+    skip('P2', 'no open goal holds unfinished tasks, so a bare archive could succeed');
+  } else {
+    const r = await probePost(`/goals/${target.id}/archive`, {});
+    const after = (await get(`/goals/${target.id}`)).goal;
+    out.push({ absent: r.status === 404, id: 'P2', rule: `R10 — bare archive of goal ${target.id} (holds ${held.get(String(target.id))})`,
+      status: r.status, refused: r.status === 409 || r.status === 403, error: r.why, mutated: after.status !== 'open' });
+  }
+
+  // P3 — R12: a version holding open goals refuses a close with no dispositions.
+  if (building.length === 0) {
+    skip('P3', 'no building version to close');
+  } else {
+    const v = building[0];
+    const openGoals = goals.filter((g) => String(g.version_id) === String(v.id) && g.status === 'open');
+    if (openGoals.length === 0) {
+      skip('P3', `${v.id} holds no open goals, so a bare close could succeed`);
+    } else {
+      const r = await probePost(`/versions/${v.id}/close`, {});
+      const after = (await get('/versions')).versions.find((x) => String(x.id) === String(v.id));
+      out.push({ absent: r.status === 404, id: 'P3', rule: `R12 — bare close of ${v.id} (holds ${openGoals.length} open goals)`,
+        status: r.status, refused: r.status === 409, error: r.why, mutated: after.status !== 'building' });
+    }
+  }
+  return out;
+}
+
+(async () => {
+  const base = API_BASE;
+  const wantProbe = hasFlag('--probe');
+  const asJson = hasFlag('--json');
+
+  const ctx = await runChecks();
+  const probes = wantProbe ? await runProbes(ctx) : [];
+
+  if (asJson) {
+    console.log(JSON.stringify({ instance: base, at: new Date().toISOString(), checks: results, probes }, null, 2));
+  } else {
+    console.log(`\nStrict-versioning proof — ${base}`);
+    console.log(`  ${new Date().toISOString()}\n`);
+    for (const r of results) {
+      console.log(`  ${r.ok ? 'HOLDS ' : 'FAILS '} ${r.id}  ${r.headline}`);
+      if (r.detail) for (const d of r.detail) console.log(`           ${d}`);
+    }
+    if (wantProbe) {
+      console.log('\n  Refusal probes (each write below MUST be refused):');
+      for (const p of probes) {
+        if (p.skipped) { console.log(`  SKIP   ${p.id}  ${p.why}`); continue; }
+        const verdict = p.absent ? 'ABSENT ' : (p.refused && !p.mutated ? 'REFUSED' : 'LEAKED ');
+        console.log(`  ${verdict} ${p.id}  ${p.rule} → ${p.status}${p.error ? ` ${p.error}` : ''}`);
+        if (p.absent) console.log('           the route does not exist on this instance — the rule is built but NOT DEPLOYED here.');
+        if (p.mutated) console.log('           ⚠ THE STATE CHANGED ANYWAY — the refusal is cosmetic.');
+      }
+    } else {
+      console.log('\n  (read-only; pass --probe to also attempt the three refusals)');
+    }
+    console.log('');
+  }
+
+  const failedChecks = results.filter((r) => !r.ok).length;
+  // A 404 is NOT a leak — the rule simply is not on this instance yet. Counting it
+  // as a failure would make the harness cry wolf on every instance running an
+  // older core, and the honest signal ("built, not deployed") is already printed.
+  const leakedProbes = probes.filter((p) => !p.skipped && !p.absent && (!p.refused || p.mutated)).length;
+  // cliExit, never process.exit — a hard exit while the request machinery is still
+  // tearing down aborts natively on Windows/Node 24 AFTER stdout has flushed, so
+  // the run looks fine and then exits 127 (this directory's CLAUDE.md; task 1002734).
+  cliExit(failedChecks + leakedProbes > 0 ? 1 : 0);
+})().catch((err) => {
+  console.error('prove-strict-versioning failed:', err.message);
+  cliExit(2);
+});

package/scripts/bongos/provision-auto-upgrade.js

@@ -0,0 +1,162 @@
+'use strict';
+
+// scripts/bongos/provision-auto-upgrade.js — the hub moves each hosted project's core on
+// its own, by that project's update rule (task 1004729, ADR 0381).
+//
+// WHY THIS EXISTS. Every runner tick, snapshotAllCoreVersions works out `recommended`
+// for every active cloud-host under its own rule (pinned / patch / minor, follow
+// released) — and then stopped. A move only happened when someone pressed the button on
+// /deploy, so a project on `patch` sat on 1.21.20 for 11 days while 1.21.69 was out
+// (toast, 2026-10). The rule already IS the owner's decision about taking updates; this
+// step acts on it, with the same two steps the button uses:
+//
+//   1. behind, not pinned, no open intent, target not held → queue a
+//      `core-upgrade-preflight` for `recommended` (the dry run; changes nothing);
+//   2. that preflight PASSED for that same target → queue the `core-upgrade` to it.
+//
+// Every intent goes through provisioning.enqueueIntent, exactly as the runner's own
+// reconcile does, so the control-plane guard and the single-open-intent slot apply, and
+// /deploy shows these moves like any other (requested_by 'runner:auto-upgrade').
+//
+// MINIMAL FAILURE HOLD. A passing preflight does not run migrations (toast's 1.21.115
+// passed its preflight and failed at migrate, intent 267), so without a hold this would
+// re-queue a target that already failed, every tick, forever. A target is held for an
+// instance when it already has, FOR THAT TARGET: a core-upgrade that ended (error, or
+// done but the box is still behind), a preflight intent that errored, or a stored
+// preflight verdict that refused. A newer release is a new target and is not held.
+//
+// BY FAILURE CLASS (task 1004730). A failed intent records WHAT KIND of failure it was
+// (upgrade-outcome.js classifyFailure, stored by the drain loop). A `transient` one (a
+// registry blip, an install that could not download) already waited out its own
+// 15m/1h/6h backoff inside the intent (intent-retry.js) before it was retired, so this
+// path may try that same target once more after TRANSIENT_HOLD_MS. Every other class (a
+// known wedge whose one fix did not hold, a rule refusing it, an unknown, a failed
+// rollback, which move-escalation.js already took to a person) stays held until a newer
+// release. The project's own hall tells its owner: src/bongos/upgrade-hold.js.
+//
+// Carved into its own file because provision.js and provision-core-upgrade.js sit at
+// the size ratchet. Best-effort: nothing here may fail the tick.
+
+const { resolveEnv } = require('../../src/instance-config');
+
+// At most this many automatic intents per tick, across ALL projects, so a release never
+// restarts every hosted project at once. The tick runs every few minutes; one is plenty.
+const AUTO_MOVES_PER_TICK = 1;
+
+// How long a target whose failure was classed transient waits before this path tries it
+// again (task 1004730): a day, the hold the self-host sweep gives a failed version
+// (update-sweep.js REFUSAL_HOLD_MS).
+const TRANSIENT_HOLD_MS = 24 * 60 * 60 * 1000;
+
+const REQUESTED_BY = 'runner:auto-upgrade';
+const OPEN_STATES = new Set(['pending', 'running']);
+const OFF_VALUES = new Set(['off', '0', 'false', 'no', 'disabled']);
+
+/**
+ * The platform-wide off switch: `<PREFIX>_AUTO_CORE_UPGRADE` (BONGOS_AUTO_CORE_UPGRADE on
+ * a vanilla hub) in the runner's environment. Unset means ON — the owner asked for this
+ * behaviour (2026-10-14). off / 0 / false / no / disabled stops every automatic move; the
+ * per-project `pinned` rule stays the project-level off switch. PURE over `env`.
+ */
+function autoUpgradeEnabled(env = process.env) {
+  const v = resolveEnv('AUTO_CORE_UPGRADE', { env, warn: () => {}, warnPack: () => {} });
+  if (v === undefined || v === null || String(v).trim() === '') return true;
+  return !OFF_VALUES.has(String(v).trim().toLowerCase());
+}
+
+function parseVerdict(p) {
+  if (!p) return null;
+  if (typeof p === 'string') { try { return JSON.parse(p); } catch { return null; } }
+  return p;
+}
+
+// Does this failed intent still hold its target at `now`? A transient error holds for
+// TRANSIENT_HOLD_MS from when it was retired; anything else holds until a newer release
+// (task 1004730). An unreadable time reads as "just now", the safe direction. PURE.
+function stillHolds(i, now) {
+  if (i.failure_class !== 'transient' || i.state !== 'error') return true;
+  const at = Date.parse(i.updated_at);
+  return !Number.isFinite(at) || now - at < TRANSIENT_HOLD_MS;
+}
+
+/**
+ * What, if anything, to queue for one project. PURE.
+ * @param {object} inst     provisioning_instances row joined with its core-version snapshot
+ * @param {object[]} intents that instance's intents (open ones + core-upgrade history)
+ * @param {object} channelMod update-channel.js
+ * @returns {{ action: string, to: string } | { skip: string }}
+ */
+function decideAutoMove(inst, intents, channelMod, now = Date.now()) {
+  if (inst.hosting_shape !== 'cloud-host') return { skip: 'not a hosted project' }; // never the control-plane row
+  if (inst.status !== 'active') return { skip: 'not active' };
+  if (channelMod.normalizeChannel(inst.update_channel) === 'pinned') return { skip: 'pinned' };
+  const served = inst.served_version;
+  const to = inst.recommended;
+  if (!served || !to || channelMod.compareSemver(to, served) <= 0) return { skip: 'current' };
+  if (intents.some((i) => OPEN_STATES.has(i.state))) return { skip: 'open intent' };
+  const same = (i) => String(i.target_version || '') === String(to);
+  const held = intents.some((i) => same(i) && (
+    (i.action === 'core-upgrade' && (i.state === 'error' || i.state === 'done'))
+    || (i.action === 'core-upgrade-preflight' && i.state === 'error')) && stillHolds(i, now));
+  const verdict = parseVerdict(inst.preflight);
+  const verdictForTarget = verdict && String(verdict.target || '') === String(to) ? verdict : null;
+  if (held || (verdictForTarget && verdictForTarget.ok !== true)) return { skip: `held: ${to} already failed here` };
+  if (verdictForTarget) return { action: 'core-upgrade', to };
+  return { action: 'core-upgrade-preflight', to };
+}
+
+/**
+ * Queue at most AUTO_MOVES_PER_TICK automatic core intents. Runs after the snapshot on an
+ * --apply tick. Never throws.
+ */
+async function autoUpgradeTick(deps) {
+  const { db, provisioning, log = () => {} } = deps;
+  if (!autoUpgradeEnabled(deps.env || process.env)) {
+    log('auto core-upgrade: off (AUTO_CORE_UPGRADE) — no automatic moves');
+    return { queued: 0, off: true };
+  }
+  const channelMod = deps.updateChannel || require('./update-channel.js');
+  let queued = 0;
+  const now = (deps.now || Date.now)();
+  try {
+    const { rows } = await db.query(
+      `SELECT i.id, i.slug, i.owner_builder_id, i.hosting_shape, i.status, i.update_channel,
+              s.served_version, s.recommended, s.preflight
+         FROM provisioning_instances i
+         JOIN provisioning_core_version_snapshot s ON s.instance_id = i.id
+        WHERE i.status = 'active' AND i.hosting_shape = 'cloud-host' AND s.recommended IS NOT NULL
+        ORDER BY i.id`);
+    if (!rows.length) return { queued };
+    const { rows: intents } = await db.query(
+      `SELECT instance_id, action, state, target_version, failure_class, updated_at FROM provisioning_intents
+        WHERE instance_id = ANY($1)
+          AND (state IN ('pending', 'running')
+               OR (action IN ('core-upgrade', 'core-upgrade-preflight') AND target_version IS NOT NULL))`,
+      [rows.map((r) => r.id)]);
+    for (const inst of rows) {
+      if (queued >= AUTO_MOVES_PER_TICK) break;
+      const mine = intents.filter((i) => String(i.instance_id) === String(inst.id));
+      const d = decideAutoMove(inst, mine, channelMod, now);
+      if (d.skip) { if (d.skip.startsWith('held')) log(`  auto core-upgrade: ${inst.slug} ${d.skip}`); continue; }
+      try {
+        const r = await provisioning.enqueueIntent(db, inst.id, d.action, REQUESTED_BY, d.to);
+        if (!r || !r.created) continue; // lost a race for the open slot — not spent
+        queued++;
+        log(`  auto core-upgrade: ${inst.slug} ${inst.served_version} → ${d.to} (${d.action} queued)`);
+        if (provisioning.recordEvent) {
+          await provisioning.recordEvent(db, {
+            instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: d.action, actor: REQUESTED_BY,
+            detail: d.action === 'core-upgrade' ? `automatic core move to ${d.to} (update rule)` : `automatic pre-flight check for ${d.to} (update rule)`,
+          }).catch(() => {});
+        }
+      } catch (e) {
+        log(`  auto core-upgrade: ${inst.slug} not queued (${(e && e.message) || e})`);
+      }
+    }
+  } catch (e) {
+    log(`  auto core-upgrade skipped (${(e && e.message) || e})`);
+  }
+  return { queued };
+}
+
+module.exports = { AUTO_MOVES_PER_TICK, TRANSIENT_HOLD_MS, autoUpgradeEnabled, autoUpgradeTick };

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

@@ -0,0 +1,68 @@
+'use strict';
+
+// scripts/bongos/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/bongos/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/bongos/provision-capacity.js

@@ -0,0 +1,79 @@
+// scripts/bongos/provision-capacity.js — the runner's BOX-CAPACITY preflight
+// (ADR 0285, task 1003927): before a standalone / co-tenant project is placed on a
+// shared box, ask whether it fits, and refuse with an owner-readable reason when it
+// does not. Nothing enforced the ceiling before this — the runner stood up project
+// N+1 on a full box and swap hid the overcommit until a reboot or a fleet upgrade
+// woke every project at once.
+//
+// The arithmetic and the two walls (row ceiling, live MemAvailable floor) live in
+// modules/provisioning/capacity.js, shared with the fleet API so both surfaces show
+// one number. This file is the runner-side composition: it reads /proc/meminfo
+// through the BOX executor — the control plane for a standalone (task 2074), the
+// remote co-hosting box for a co-tenant under remote-exec (ADR 0130) — so an
+// overflow box is measured where the project will actually run. A sibling of
+// provision-config / -repo / -units / -net; provision.js requires it back.
+'use strict';
+
+const { CONFIG } = require('./provision-config.js');
+const capacity = require('../../modules/provisioning/capacity.js');
+
+// The kernel's own two lines, kept small so the journal stays readable. allowFail:
+// a box without procfs (never, on Linux) reads as "unmeasured", and the ceiling
+// then falls to ADR 0285's conservative default rather than aborting the standup.
+const MEMINFO_CMD = "grep -E '^Mem(Total|Available):' /proc/meminfo";
+
+// capacityPreflight — { ok:true, …summary } when the project fits (or the shape has
+// no shared box), { ok:false, error, …summary } when it does not. The refusal is a
+// RETURN, never a throw: the drain loop retries it (a teardown may free a slot), and
+// on retirement writes `error` onto the instance's card without flipping its status
+// — so a project that was never placed is never labelled broken. Dry-run measures
+// and reports but refuses nothing, since it places nothing either way.
+async function capacityPreflight(inst, deps) {
+  const { db, provisioning, exec, log, apply } = deps;
+  const target = capacity.placementBox(inst.hosting_shape, { remoteHost: CONFIG.remoteHost });
+  // No target box = no box of OURS to place this on, so there is no ceiling to ask about.
+  // Today that is 'byo-host' alone: the owner supplies the machine. It also covered
+  // 'dedicated' until ADR 0327 decision 4 removed that shape, which is why the skip reason
+  // is named for the QUESTION rather than for whichever shape happens to answer it — a
+  // reason label that names a shape goes stale the moment the shape does.
+  if (!target) return { ok: true, skipped: 'no-shared-box' };
+  const boxExec = target.box === 'control-plane' ? (deps.controlExec || exec) : exec;
+  let res = null;
+  try { res = boxExec(MEMINFO_CMD, { allowFail: true }); } catch { res = null; }
+  const mem = capacity.parseMeminfo(res && res.stdout);
+  const { ceiling, source } = capacity.ceilingFor({ override: CONFIG.boxCeiling, memTotalMb: mem.memTotalMb, fixedMb: target.fixedMb });
+  const placed = await capacity.countPlaced(db, target.shapes, { excludeId: inst.id });
+  const floorMb = CONFIG.memFloorMb || capacity.DEFAULT_MEM_FLOOR_MB;
+  const summary = capacity.capacitySummary({ box: target.box, placed, ceiling, source, memAvailableMb: mem.memAvailableMb, floorMb });
+  const free = mem.memAvailableMb != null ? `${mem.memAvailableMb} MB free` : 'memory unmeasured';
+  const where = `${target.box} box at ${placed} of ${ceiling} slots (${source}, ${free})`;
+  if (!apply) {
+    log(`  [preflight] ${where} — would refuse if full (dry-run measures nothing and places nothing)`);
+    return { ok: true, dryRun: true, ...summary };
+  }
+  if (source === 'default') log(`  [preflight] ⚠ could not measure the box — using ADR 0285's smallest-tier ceiling (${ceiling}); set PROVISION_BOX_CEILING to override`);
+  if (!summary.verdict.ok) {
+    log(`  ✖ [preflight] ${where} — refusing to place ${inst.slug} (${summary.verdict.wall} wall)`);
+    if (provisioning && provisioning.recordEvent) {
+      await provisioning.recordEvent(db, {
+        instanceId: inst.id, ownerBuilderId: inst.owner_builder_id, event: 'placement-refused',
+        detail: summary.verdict.reason, actor: 'runner',
+      }).catch(() => {});
+    }
+    return { ok: false, error: summary.verdict.reason, ...summary };
+  }
+  log(`  [preflight] ${where} ✓${summary.resize_due ? ' — at or past 80%: schedule the resize (task 1003923) or open the next box' : ''}`);
+  return { ok: true, ...summary };
+}
+
+// statusCapacityLine — the "box at N of M" line `provision.js status` prints, read
+// from this host (the CLI runs on the control plane), so the resize is scheduled
+// at 80% rather than discovered at the ceiling.
+async function statusCapacityLine(db) {
+  const c = await capacity.fleetCapacity(db);
+  const free = c.mem_available_mb != null ? `, ${c.mem_available_mb} MB free` : '';
+  const due = c.resize_due ? ' — at or past 80%: resize or open the next box (ADR 0285, task 1003923)' : '';
+  return `  ${c.box} box: ${c.placed} of ${c.ceiling} project slots taken (${c.source}${free})${due}`;
+}
+
+module.exports = { MEMINFO_CMD, capacityPreflight, statusCapacityLine };

package/scripts/bongos/provision-caps.js

@@ -0,0 +1,63 @@
+// scripts/bongos/provision-caps.js — the resource caps every hosted project's service carries
+// (task 1004414). A cloud-host project runs its owner's code on the box that also serves the
+// hub, and ADR 0354 lets any signed-in builder host one, so a runaway project must not be
+// able to starve the others or the hub.
+//
+// The numbers are the owner's (2026-10-15), sized from ADR 0285's measurement: a project
+// idles at ~45-70 MB and peaks at 118-134 MB at boot (page cache included), and uses a
+// fraction of a percent of one core. MemoryHigh throttles and reclaims before MemoryMax
+// kills; a killed project comes back through the unit's Restart=always. Too tight a cap
+// takes a healthy project down, so change these only as a decision.
+//
+// A NEW unit renders them (serviceUnit). An EXISTING unit takes them with `systemctl
+// set-property`, which applies live and persists a drop-in under /etc/systemd/system.control/,
+// so nothing restarts and no unit file is rewritten — rewriting would move a project made
+// before the per-instance accounts (task 1003369) onto an account that does not exist.
+// systemd only: the supervisord image has no cgroups to cap.
+
+'use strict';
+
+const RESOURCE_CAPS = Object.freeze({
+  MemoryHigh: '160M',
+  MemoryMax: '256M',
+  CPUQuota: '50%',
+  TasksMax: '256',
+});
+
+function capDirectives() {
+  return Object.entries(RESOURCE_CAPS).map(([key, value]) => `${key}=${value}`);
+}
+
+// The slug is interpolated into a root shell command, so it is held to the create route's
+// charset here too rather than trusted from the row.
+const SAFE_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+function setCapsCmd(inst, { sudoP = '' } = {}) {
+  if (!SAFE_SLUG.test(String(inst.slug))) throw new Error(`refusing to cap an unsafe slug: ${JSON.stringify(inst.slug)}`);
+  return `${sudoP}systemctl set-property ${inst.slug}.service ${capDirectives().join(' ')}`;
+}
+
+// `provision.js apply-caps [--apply]` — cap every running hosted project now. A cloud-host
+// always runs on the control plane (capacity.placementBox), so this uses controlExec. One
+// project that refuses never stops the rest; the result names it.
+async function cmdApplyCaps(deps) {
+  const { db, log, privileged } = deps;
+  const exec = deps.controlExec || deps.exec;
+  const sudoP = privileged ? 'sudo ' : '';
+  const { rows } = await db.query(
+    `SELECT slug FROM provisioning_instances
+      WHERE hosting_shape = 'cloud-host' AND status = 'active'
+      ORDER BY slug`);
+  const capped = [], failed = [];
+  for (const { slug } of rows) {
+    // makeExec answers an allowFail'd failure ok:true + softFailed:true (softFailResult)
+    let r;
+    try { r = exec(setCapsCmd({ slug }, { sudoP }), { allowFail: true }); } catch { r = null; }
+    (!r || r.ok === false || r.softFailed ? failed : capped).push(slug);
+  }
+  log(`${deps.apply ? 'capped' : 'would cap (dry-run — add --apply)'} ${capped.length} of ${rows.length} active hosted project(s) at ${capDirectives().join(' ')}`);
+  if (failed.length) log(`  ✖ could not cap: ${failed.join(', ')} — re-run once each unit is loaded`);
+  return { ok: failed.length === 0, capped, failed };
+}
+
+module.exports = { RESOURCE_CAPS, capDirectives, setCapsCmd, cmdApplyCaps };