@bongos/core 1.19.676 → 1.19.677

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.676",
-  "core_contract": "1.19.676",
-  "source_commit": "9aad4d0005991e8ba38f4443b4e5611a13aa3af8",
+  "core_version": "1.19.677",
+  "core_contract": "1.19.677",
+  "source_commit": "edcffc22cdab15c1f61e5cd2cb2b9d6a13872150",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T20:44:28.469Z",
+  "built_at": "2026-09-11T21:42:20.049Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 474,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2621,
-  "tree_sha256": "b556a6e9644d99b65ffdf9ac64384eee16b20ecfb7e31ed60c875d76297310f3",
+  "tree_sha256": "2afeb3b9fd9e3cf3de8feb833f7710642830cc081102cfd1a58d9e7ea6057332",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -1917,7 +1917,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "301cf1db00b9f18b84cb765bbaa359329a665b1ef754dff4c21c1550ec60cae5"
+      "sha256": "45efd65847e2b9e5ade3d21eef0bc3ec3562184b109927f93425887ca99b02ba"
     },
     {
       "path": "docs/architecture.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b8786c58575f93eb93661ee1d7e0745f0993f5666e5237ca073177df2d3ee9f4"
+      "sha256": "2fbf6cfad023d90c93ffcc7cadce65e73e578cead78069011d2b47b23a0de8e5"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6482,7 +6482,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "32083b07e4c676f9a68e0b78df3e5f5a0cea45fe0cb168a32fe1180165c99fbe"
+      "sha256": "0f82fbdf4838a7e72d4128c76b4da7f05ed4578b8a20c167c7fb2e95cb1e9237"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -6507,7 +6507,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "202dcfb416317eda72696455ace487d36021377d87a6c122df9561bc087939a8"
+      "sha256": "c83cec200215e9cb04446592e1aed32daf8e083142416bdc1f25d261f460d1cf"
     },
     {
       "path": "modules/provisioning/starter-bundles.js",
@@ -7767,12 +7767,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3b0ebf2f1fb870085a40531295fb3c5989be5ab399e2493e43a1e3e844b0633c"
+      "sha256": "f9c8562e66253cdfd8487dfb052d7a3443c477d4bb1abfef8b53946cd5104691"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b4c1e3c5189ac7220af056624bdc0476a0d751c00aa76aba2e84416128280bc7"
+      "sha256": "7be7c3c8b5ca557dbbf7f5a38453fedb85bd004e53b170e1746a03a02ab75ae9"
     },
     {
       "path": "public-docs/index.html",
@@ -9532,7 +9532,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "406c218b56b011b4560887f2ae4e13f20e227fa4404e6763649e2eac2b0f5292"
+      "sha256": "025ba17e4ac4f614e81bde6009db0ed9ba04ccfb3d226abcc92e9e51d24b97b9"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12132,7 +12132,7 @@
     {
       "path": "tests/provisioning_settings_apply.mjs",
       "mode": "0000644",
-      "sha256": "7fc80fc5576aba1dd10c0416899ade5fa2c9380ea8c1a995aaa99745aa56c29c"
+      "sha256": "a55a1c88958710a8b84048b88ba5d68b05e4489242a777852af8a2c9991462fb"
     },
     {
       "path": "tests/provisioning_settings_env.mjs",

package/docs/api/openapi.json

@@ -12149,7 +12149,7 @@
           "provisioning"
         ],
         "summary": "PATCH /provisioning/instances/:id/settings",
-        "description": "PATCH /provisioning/instances/:id/settings — change a project's settings. Body: any subset of the known keys; strict validation refuses unknown keys and off-vocabulary values. rank: any authenticated builder (own resource; archon may change any — the override is audited via the event's actor). The platform's row is updated first; then, for an ACTIVE instance on a shape the runner can reach, a 'settings-apply' intent is enqueued (task 1003140): the control-plane runner patches the instance's web.env in place and RESTARTS it, because the branding pack is memoized for the process lifetime. A save that changes nothing neither writes nor restarts. The response is a request receipt — `saved` is what the platform now stores, and `push` { queued, restart, reachable, message } says whether a restart was queued and when the value takes effect — never a claim the instance already runs it; a client reads that back from the instance's own public GET /instance manifest (brand.project). 409 intent_conflict (details.recorded: true) when the open slot is held by other work — the change IS saved.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "PATCH /provisioning/instances/:id/settings — change a project's settings. Body: any subset of the known keys; strict validation refuses unknown keys and off-vocabulary values. rank: any authenticated builder (own resource; archon may change any — the override is audited via the event's actor). The platform's row is updated first; then, for an ACTIVE instance on a shape the runner can reach, a 'settings-apply' intent is enqueued (task 1003140): the control-plane runner patches the instance's web.env in place and RESTARTS it, because the branding pack is memoized for the process lifetime. A save that changes nothing neither writes nor restarts. The response is a request receipt — `saved` is what the platform now stores, and `push` { queued, restart, reachable, message } says whether a restart was queued and when the value takes effect — never a claim the instance already runs it; a client reads that back from the instance's own public GET /instance manifest (brand.project). 409 intent_conflict (details.recorded: true) when the open slot is held by other work — the change IS saved. A save whose push did not get carried (that 409, or an enqueue that threw) marks the push OWED, which is what makes the \"send it again\" both of those name actually re-queue instead of hitting the no-op \"No change\" branch (task 1003524).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "parameters": [

package/docs/module-api-changelog.md

@@ -1811,5 +1811,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.674 with no explicit bump. run 34639371461. (task 1002620)
   1.19.676 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.675 with no explicit bump. run 34645751352. (task 1002620)
+  1.19.677 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.676 with no explicit bump. run 34650610723. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/provisioning.js

@@ -441,6 +441,12 @@ ${lines}
 `;
 }
 
+// The reserved settings-jsonb key settingsPushOwed/recordSettingsPushOwed use
+// (task 1003524). Deliberately NOT in SETTINGS_VOCAB or PLANET_VOCAB — it is the
+// platform's own bookkeeping, not a setting an owner declares, and the test
+// asserts it stays out of both so it can never start projecting as one.
+const SETTINGS_PUSH_OWED_KEY = 'push_owed';
+
 // The instance's EFFECTIVE settings: the defaults overlaid with the stored,
 // on-vocabulary keys. An off-vocabulary or unknown stored value falls back to
 // its default rather than leaking into the read surface. PURE.
@@ -466,6 +472,30 @@ function planetChoice(row) {
   return out;
 }
 
+// Is a POLICY settings push OWED to this instance (task 1003524)? Set when the
+// row was written but its push demonstrably did not get carried: the open slot
+// was held by other work (409 intent_conflict), or the enqueue itself threw.
+// Both of those answer the owner "send it again" — and without this marker that
+// remedy is a NO-OP, because the re-send is by definition unchanged and takes
+// the "No change" branch, leaving the saved value stranded on the platform. (The
+// only way out was toggling to a third value and back.)
+//
+// It lives as a RESERVED key in the settings jsonb rather than a column so it
+// costs no migration — the provisioning_009 rationale, which is why that column
+// is jsonb in the first place. It can neither leak nor be client-written:
+// effectiveSettings / planetChoice / settingsEnvVars project ONLY vocabulary
+// keys, and the route builds its patch only from settingKeys.
+//
+// error_note is the sibling marker and the two do not overlap: that one latches
+// a push that WAS queued and then failed (F19), this one a push that was never
+// queued at all. Together they make "send it again" true on every branch that
+// says it. PURE.
+function settingsPushOwed(row) {
+  const stored = row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings)
+    ? row.settings : {};
+  return stored[SETTINGS_PUSH_OWED_KEY] === true;
+}
+
 // A description as it may be STORED: trimmed, collapsed of runaway whitespace,
 // capped, and empty-means-absent. Returns null for anything that isn't real prose,
 // because null is what leaves the project dark-matter — an empty string stored in a
@@ -669,6 +699,25 @@ async function updateInstanceSettings(db, id, patch) {
   return rows[0] || null;
 }
 
+// Mark (or clear) the owed-push marker settingsPushOwed reads (task 1003524).
+// Same narrowness rule as recordDnsNote / clearErrorNote: no `status`, and no
+// `updated_at` — this is the platform's own bookkeeping, and bumping updated_at
+// would reshuffle the owner's card ordering (listInstancesForOwner orders by it)
+// for a write the owner did not make. Clearing DELETES the key rather than
+// storing false, so a row that never owed a push is byte-identical to one whose
+// debt was settled.
+async function recordSettingsPushOwed(db, id, owed) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances
+        SET settings = CASE WHEN $2::boolean
+              THEN settings || $3::jsonb
+              ELSE settings - $4::text END
+      WHERE id = $1 RETURNING id, settings`,
+    [id, !!owed, JSON.stringify({ [SETTINGS_PUSH_OWED_KEY]: true }), SETTINGS_PUSH_OWED_KEY]
+  );
+  return rows[0] || null;
+}
+
 // Fill in (or change) the project-detail answers AFTER creation — the other half
 // of "skippable" (task 1002334). Skipping the step at creation is a supported
 // default, but it is only a default and not a dead end if there is a way back; this
@@ -1290,6 +1339,7 @@ module.exports = {
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
   defaultDomainForSlug, isReservedHostname, effectiveSettings, planetChoice,
+  settingsPushOwed,
   normalizeDescription, normalizeProjectDetail, projectDetailPatch, projectDetail,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl, publicGithubApp,
@@ -1298,6 +1348,8 @@ module.exports = {
   getInstanceById, getInstanceBySlug, getInstanceByDomain, listInstancesForOwner, listAllInstances,
   // data access — verification overlay (task 1002696)
   listActiveInstancesForLiveness, recordLivenessProbe, recordDnsNote, clearErrorNote,
+  // data access — the owed-push marker (task 1003524)
+  recordSettingsPushOwed,
   createInstance, setInstanceStatus, updateInstanceDomain, updateInstanceSettings, updateInstanceDetail,
   createInstance, setInstanceStatus, updateInstanceDomain, clearReleasedDomains, updateInstanceSettings,
   enqueueIntent, enqueueTeardown, enqueueSettingsApply, enqueueRestart, getOpenIntent, claimNextIntent, resolveIntent,

package/modules/provisioning/routes/provisioning.js

@@ -853,7 +853,10 @@ module.exports = function provisioningRoutes() {
   // and when the value takes effect — never a claim the instance already runs
   // it; a client reads that back from the instance's own public GET /instance
   // manifest (brand.project). 409 intent_conflict (details.recorded: true) when
-  // the open slot is held by other work — the change IS saved.
+  // the open slot is held by other work — the change IS saved. A save whose push
+  // did not get carried (that 409, or an enqueue that threw) marks the push OWED,
+  // which is what makes the "send it again" both of those name actually re-queue
+  // instead of hitting the no-op "No change" branch (task 1003524).
   router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
@@ -898,7 +901,13 @@ module.exports = function provisioningRoutes() {
       const policyKeys = Object.keys(provisioning.SETTINGS_VOCAB);
       const policyTouched = policyKeys.some((k) => patch[k] !== undefined);
       const policyChanged = policyKeys.some((k) => patch[k] !== undefined && before[k] !== patch[k]);
-      const policyResent = !!inst.error_note && policyTouched;
+      // A push is OWED when the last save's push did not get carried — a queued
+      // push that RAN and failed (error_note, the F19 re-kick), or one never queued
+      // at all (the 409 below, or an enqueue that threw; task 1003524). Both answer
+      // "send it again", and folding the second in is what makes that sentence
+      // true: the re-send is unchanged, so it would otherwise hit "No change".
+      const pushOwed = provisioning.settingsPushOwed(inst);
+      const policyResent = (!!inst.error_note || pushOwed) && policyTouched;
       const updated = changed ? await provisioning.updateInstanceSettings(pool, id, patch) : inst;
       if (changed) {
         await provisioning.recordEvent(pool, {
@@ -947,14 +956,25 @@ module.exports = function provisioningRoutes() {
         catch (err) {
           // The value IS saved — say so; a 500 here would deny a durable write.
           log.error('[provisioning] PATCH /provisioning/instances/:id/settings enqueue', err);
+          // The remedy this sentence names has to WORK (task 1003524): nothing is
+          // going to carry the saved value, so record the debt. Best-effort — a failed
+          // marker write must never turn a durable settings write into a 500.
+          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
           push = receipt({ queued: false, restart: true, message: 'Saved, but the restart could not be queued just now — send it again to apply it.' });
         }
         if (r && r.conflict) {
+          // Saved, but the slot is held by work that will not carry this change, so
+          // "send it again once that settles" has to re-queue when they do (task 1003524).
+          await provisioning.recordSettingsPushOwed(pool, id, true).catch(() => {});
           return res.fail('intent_conflict', { status: 409,
             message: `The change was saved, but a '${r.intent.action}' run is currently ${r.intent.state} for this project — send it again once that settles to apply it.`,
             details: { action: r.intent.action, state: r.intent.state, recorded: true } });
         }
         if (r) {
+          // A push is now in hand — fresh, or a PENDING one that has not read the row
+          // yet — so either way it carries the current settings. Only written when
+          // there IS a debt, so the hot path stays a single UPDATE.
+          if (pushOwed) await provisioning.recordSettingsPushOwed(pool, id, false).catch(() => {});
           push = receipt({ queued: r.created, restart: true, message: r.created
             ? 'Saved. Your project will restart to pick this up — until then it keeps its current setting.'
             : 'Saved. A restart is already queued for this project and will carry this change.' });

package/package-lock.json

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

package/package.json

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

package/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.676'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.677'; // 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/provisioning_settings_apply.mjs

@@ -132,7 +132,19 @@ let enqueueCalls = [];
 let enqueueResult = null;      // what enqueueSettingsApply reports (null → created:true)
 let enqueueThrows = null;      // an Error to throw from enqueueSettingsApply
 let events = [];
+let owedCalls = [];           // every recordSettingsPushOwed(id, owed) the route makes
 provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+// The marker is a reserved key in the SAME settings jsonb, so the stub mutates the
+// fixture the way the real UPDATE does — that is what lets a test re-send against
+// the row its own previous save left behind.
+const realRecordSettingsPushOwed = provisioning.recordSettingsPushOwed;
+provisioning.recordSettingsPushOwed = async (_db, id, owed) => {
+  owedCalls.push({ id, owed });
+  const next = { ...(instance.settings || {}) };
+  if (owed) next.push_owed = true; else delete next.push_owed;
+  instance = { ...instance, settings: next };
+  return { id, settings: next };
+};
 provisioning.updateInstanceSettings = async (_db, id, patch) => {
   updateCalls.push({ id, patch, enqueuedSoFar: enqueueCalls.length });
   instance = { ...instance, settings: { ...(instance.settings || {}), ...patch } };
@@ -196,6 +208,7 @@ function reset({ inst, as } = {}) {
   enqueueResult = null;
   enqueueThrows = null;
   events = [];
+  owedCalls = [];
 }
 // every receipt carries the same four keys, and never a duration promise
 function receiptShape(push, { queued, restart, reachable }) {
@@ -354,6 +367,122 @@ await ta('ACTIVE dedicated: stored, NO intent, reachable:false, restart:true (a
   assert.doesNotMatch(r.body.push.message, /web\.env/, 'no file the owner has never seen');
 });
 
+console.log("\nthe owed push — making \"send it again\" true (task 1003524):");
+
+// THE HEADLINE, end to end, exactly as the bug was reported: the owner saves
+// visibility (queued), saves joinability one card below while the first push is
+// RUNNING (409), that run settles, and they do what the 409 told them to — re-send
+// the SAME joinability. Before this fix the re-send was unchanged, so it took the
+// "No change" branch and queued nothing: the value sat on the platform forever and
+// the only way out was toggling to a third value and back.
+await ta('save A queues → save B 409s while A RUNS → A settles → the UNCHANGED re-send of B queues a NEW push', async () => {
+  reset();
+
+  // 1. visibility: a clean queue.
+  let r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.push.queued, true);
+  assert.equal(enqueueCalls.length, 1);
+
+  // 2. joinability, while that push is RUNNING — saved, but nothing carries it.
+  enqueueResult = { intent: { id: 5, action: 'settings-apply', state: 'running' }, created: false, conflict: 'open_intent' };
+  r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 409, r.raw);
+  assert.equal(r.body.error.details.recorded, true, 'the value IS stored');
+  assert.match(r.body.error.message, /send it again once that settles/i, 'the remedy this test exists to make true');
+  assert.deepEqual(owedCalls, [{ id: 18, owed: true }], 'the debt is recorded at the moment the push is refused');
+
+  // 3. that run settles; the owner re-sends the SAME joinability.
+  enqueueResult = null;               // the slot is free again
+  const enqueuedBefore = enqueueCalls.length;
+  const writesBefore = updateCalls.length;
+  r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+
+  assert.equal(r.status, 200, r.raw);
+  assert.doesNotMatch(r.body.push.message, /No change/, 'the whole bug: the remedy used to be a no-op');
+  assert.equal(r.body.push.queued, true, 'a NEW push is queued');
+  assert.equal(enqueueCalls.length, enqueuedBefore + 1, 'exactly one new intent');
+  assert.equal(updateCalls.length, writesBefore, 'nothing re-written — the value was already stored in step 2');
+  assert.deepEqual(owedCalls[owedCalls.length - 1], { id: 18, owed: false }, 'and the debt is settled');
+  assert.deepEqual(r.body.saved, { platform_visibility: 'gated', joinability: 'open', visibility: 'public', join_grant: 'full' },
+    'the value that finally ships is the one the owner saved');
+});
+
+await ta('an enqueue that THROWS records the debt too — its "send it again" is the same sentence', async () => {
+  reset();
+  enqueueThrows = new Error('db down');
+  const r = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r.status, 200, r.raw);
+  assert.match(r.body.push.message, /send it again/i);
+  assert.deepEqual(owedCalls, [{ id: 18, owed: true }]);
+
+  // and the re-send it names now works
+  enqueueThrows = null;
+  const r2 = await patch('/provisioning/instances/18/settings', { joinability: 'open' });
+  assert.equal(r2.body.push.queued, true, 'the unchanged re-send queues');
+  assert.equal(updateCalls.length, 1, 'still only the original write');
+});
+
+await ta('a push already in hand settles the debt; with no debt outstanding nothing is written (the hot path stays one UPDATE)', async () => {
+  // an identical PENDING push (created:false, no conflict) has not read the row yet,
+  // so it carries this change — the debt is settled just as for a fresh intent.
+  reset({ inst: { ...ACTIVE, settings: { platform_visibility: 'gated', push_owed: true } } });
+  enqueueResult = { intent: { id: 5, action: 'settings-apply', state: 'pending' }, created: false };
+  const r = await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(owedCalls, [{ id: 18, owed: false }], 'a pending push carries it — debt settled');
+
+  reset();
+  await patch('/provisioning/instances/18/settings', { platform_visibility: 'gated' });
+  assert.deepEqual(owedCalls, [], 'no debt, no bookkeeping write');
+});
+
+await ta('an owed push is a POLICY debt: a planet-only re-send neither re-kicks it nor clears it', async () => {
+  reset({ inst: { ...ACTIVE, settings: { planet_template: 'bead-obsidian-tint', push_owed: true } } });
+  const r = await patch('/provisioning/instances/18/settings', { planet_template: 'bead-obsidian-tint' });
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(enqueueCalls.length, 0, 'the planet reaches no instance, so it re-kicks nothing');
+  assert.deepEqual(owedCalls, [], 'and the policy debt survives, still owed');
+  assert.equal(provisioning.settingsPushOwed(instance), true);
+});
+
+await ta('the marker never leaks: not a vocabulary key, not in any projection, and a client cannot write it', async () => {
+  const row = { settings: { push_owed: true, joinability: 'open', planet_template: 'bead-obsidian-tint' } };
+  assert.equal(provisioning.settingsPushOwed(row), true);
+  assert.ok(!('push_owed' in provisioning.SETTINGS_VOCAB), 'not a policy setting');
+  assert.ok(!('push_owed' in provisioning.PLANET_VOCAB), 'not a planet setting');
+  assert.ok(!('push_owed' in provisioning.effectiveSettings(row)), 'never in the saved projection');
+  assert.ok(!('push_owed' in provisioning.planetChoice(row)), 'never in the planet projection');
+  const env = provisioning.settingsEnvVars(row, 'BONGOS');
+  for (const k of Object.keys(env)) assert.doesNotMatch(k, /PUSH_OWED/, 'never reaches the instance web.env');
+  assert.equal(provisioning.settingsPushOwed({ settings: {} }), false);
+  assert.equal(provisioning.settingsPushOwed({ settings: { push_owed: 'yes' } }), false, 'strictly true, never truthy');
+  assert.equal(provisioning.settingsPushOwed(null), false);
+
+  // strict validation refuses it on the way in, so it is server-only by construction
+  reset();
+  const r = await patch('/provisioning/instances/18/settings', { push_owed: true });
+  assert.equal(r.status, 400, r.raw);
+  assert.equal(updateCalls.length, 0);
+});
+
+await ta('recordSettingsPushOwed writes NOTHING but the marker — no status, no updated_at, and clearing deletes the key', async () => {
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ id: 18, settings: {} }] }; } };
+  await realRecordSettingsPushOwed(db, 18, true);
+  await realRecordSettingsPushOwed(db, 18, false);
+  for (const c of seen) {
+    assert.match(c.sql, /UPDATE provisioning_instances/);
+    assert.doesNotMatch(c.sql, /updated_at/, 'bookkeeping must not reshuffle the owner\'s card order');
+    assert.doesNotMatch(c.sql, /status/, 'and must not touch the lifecycle');
+    assert.match(c.sql, /settings - \$4::text/, 'clearing DELETES the key rather than storing false');
+    assert.equal(c.params[0], 18);
+  }
+  assert.equal(seen[0].params[1], true);
+  assert.equal(seen[1].params[1], false);
+  assert.equal(seen[0].params[3], 'push_owed', 'the reserved key, passed as a parameter not interpolated');
+});
+
 console.log('\nthe walls that did not move:');
 
 await ta("another builder's PATCH → 404; nothing stored, nothing queued", async () => {