@bongos/core 1.19.675 → 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.675",
-  "core_contract": "1.19.675",
-  "source_commit": "1341cb9d37a0965db7f80483f7f1cb8f3622b2c5",
+  "core_version": "1.19.677",
+  "core_contract": "1.19.677",
+  "source_commit": "edcffc22cdab15c1f61e5cd2cb2b9d6a13872150",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T19:32:52.079Z",
+  "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": "554ecf20aaad28b8461021791d1e5c4d2c890a860a458885227f20429b946339",
+  "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": "af50f99c27d85db0067d45e5e6eba133edcae8b3dd7388041b6824f4cb192e22"
+      "sha256": "2fbf6cfad023d90c93ffcc7cadce65e73e578cead78069011d2b47b23a0de8e5"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2912,7 +2912,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "06b938c2ad38915d3ed92b20a94c57621ae835f617b01ab02fc01129cd154e2c"
+      "sha256": "86d266be2c1833484225886c1ed961b8f19d511e84226032dc65c9ccf18f5550"
     },
     {
       "path": "docs/recipes/devbox-app-release.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": "795b9955321b5ecffd9d78f515649442016285cb21f728c4001ee97ebcc32ac5"
+      "sha256": "f9c8562e66253cdfd8487dfb052d7a3443c477d4bb1abfef8b53946cd5104691"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "33bcb1180ab5e54281e7c50d39a712d142b259f77f37b685f2bb4512b1c010fa"
+      "sha256": "7be7c3c8b5ca557dbbf7f5a38453fedb85bd004e53b170e1746a03a02ab75ae9"
     },
     {
       "path": "public-docs/index.html",
@@ -8327,7 +8327,7 @@
     {
       "path": "scripts/gds/go-live.js",
       "mode": "0000644",
-      "sha256": "1e14a452c0ae53384facd6a20526a90106cb479c414937ebb7fe180f11c5fa31"
+      "sha256": "d1383b714ba0d8e4d0f5ceb097e45c1ed1af09caf648f7a43a6c6431c38fb422"
     },
     {
       "path": "scripts/gds/goal-names.js",
@@ -9102,7 +9102,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "430d1f55212254d75144fb15a438ffc61aad1ea7d5176b36f39e87c30efeb2df"
+      "sha256": "7a173ecf47b25007bba28f68787893352f429a52b34b7f7b4eae0d3791a5cdcf"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9532,7 +9532,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "35f42575db36eb956e2479c681562e18a93d2d4973c8df0d79ac5a54048d4542"
+      "sha256": "025ba17e4ac4f614e81bde6009db0ed9ba04ccfb3d226abcc92e9e51d24b97b9"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10667,7 +10667,7 @@
     {
       "path": "tests/go_live.mjs",
       "mode": "0000644",
-      "sha256": "ce97c74d749ec3574c0683160b3ce5dad8a7af2dcf1ce53fd23e95f5e0ad480d"
+      "sha256": "7528da9c6cd81d9876f0ffae0bf836844cb726a9bbb24cda44f0675d6f6ac0ea"
     },
     {
       "path": "tests/goal_abuse_matrix.mjs",
@@ -12132,7 +12132,7 @@
     {
       "path": "tests/provisioning_settings_apply.mjs",
       "mode": "0000644",
-      "sha256": "7fc80fc5576aba1dd10c0416899ade5fa2c9380ea8c1a995aaa99745aa56c29c"
+      "sha256": "a55a1c88958710a8b84048b88ba5d68b05e4489242a777852af8a2c9991462fb"
     },
     {
       "path": "tests/provisioning_settings_env.mjs",
@@ -12982,7 +12982,7 @@
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "07fd48b255bbd2370580b62a8f77d7fc981b0dfdefcc5be6973a9c4d6cb49add"
+      "sha256": "c0a96fbdc6a9f851925babfb0857c9a168374c4165c84884f5c4c56c7177dd58"
     },
     {
       "path": "tests/verify_task_guard.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

@@ -1809,5 +1809,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.673 with no explicit bump. run 34634515595. (task 1002620)
   1.19.675 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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/docs/recipes/core-release-pipeline.md

@@ -168,6 +168,18 @@ Host topology (ssh alias, box paths, service names, health URL) lives in a host-
 `config/go-live.json`, never in the core — run `node scripts/gds/go-live.js --help` for the
 schema. A core that named one instance's box would not be a core.
 
+**Upgrading a provisioned co-tenant** (task 1003521). A co-tenant under `/srv/<host>/<slug>` is
+the same engine with two fields different, because two of this instance's assumptions do not hold
+there: it has no pull-deploy timer to stop (only its `<slug>-db-backup.timer`), and its repo of
+record is the **customer's** own GitHub repo, so pushing the pin there is both wrong and
+uncredentialed. So omit `deployTimer` — the stop and the restart are skipped, and there is no
+`reset --hard` to race — and set `"pinMode": "local-commit"`, which commits the pin without
+pushing it. (`"leave-dirty"` leaves the bump in the working tree; `"push"` is the default and is
+what the platform instance needs.) Everything else — the registry proof, `--verify-marker`, the
+`pg_dump`, the health-gated upgrade with auto-rollback, the box-side version read-back — is
+unchanged. The co-tenant's own scaffold gap is separate and still open:
+[#1003520](https://cloudbongos.com/builders#/task/1003520).
+
 ### Step 1 — pick the version (your machine, main checkout)
 
 ```bash

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.675",
+  "version": "1.19.677",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.675",
+      "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.675",
+  "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/scripts/gds/go-live.js

@@ -77,8 +77,32 @@ function isSafeToken(v) {
 // rather than ignored: a typo'd `healthURL` that silently disables the health gate
 // is precisely the class of quiet failure this pipeline keeps being bitten by.
 // `ssh` is NOT required: a target with no ssh host is LOCAL (the box driving itself).
-const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer'];
-const OPTIONAL_FIELDS = ['ssh', 'local', 'deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage'];
+//
+// `deployTimer` is NOT required either — that is CO-TENANT MODE (task 1003521). A
+// provisioned instance under /srv/<host>/<slug> has no pull-deploy timer at all (only
+// its <slug>-db-backup.timer), so requiring the field forced an operator to invent a
+// unit name that the script would then try to `systemctl stop`. Absent, the stop and
+// the restart are simply skipped: there is no `reset --hard` to race.
+const REQUIRED_FIELDS = ['instanceDir', 'service', 'healthUrl', 'versionUrl'];
+const OPTIONAL_FIELDS = ['ssh', 'local', 'deployTimer', 'deployService', 'npmEnvFile', 'runAs', 'backupDb', 'backupDir', 'env', 'registryPackage', 'pinMode'];
+
+// How the bump is made durable — the other half of co-tenant mode (task 1003521).
+//
+// On the PLATFORM instance the repo of record is ours, and a pull-deploy
+// `git reset --hard origin/main` reverts any pin that was not PUSHED (task 1002712 —
+// thirteen releases were lost exactly that way). So the default is `push`.
+//
+// On a provisioned co-tenant the repo of record is the CUSTOMER's own GitHub repo, so
+// that push is both wrong and, in practice, uncredentialed. With no pull-deploy timer
+// nothing will revert the pin, so a local commit is enough to leave the tree clean:
+//   local-commit — commit the pin, do not push it
+//   leave-dirty  — do not commit at all; the bump lives in the working tree by design
+const PIN_MODES = ['push', 'local-commit', 'leave-dirty'];
+const DEFAULT_PIN_MODE = 'push';
+
+function pinModeOf(target) {
+  return (target && target.pinMode) || DEFAULT_PIN_MODE;
+}
 
 function validateTarget(name, t) {
   const errors = [];
@@ -105,6 +129,10 @@ function validateTarget(name, t) {
       if (typeof v !== 'boolean') errors.push(`target "${name}".local must be true or false`);
       continue;
     }
+    if (k === 'pinMode') { // an enum, never interpolated into a command
+      if (!PIN_MODES.includes(v)) errors.push(`target "${name}".pinMode must be one of ${PIN_MODES.join(', ')} (got ${JSON.stringify(v)})`);
+      continue;
+    }
     if (!isSafeToken(v)) errors.push(`target "${name}".${k} contains characters that are unsafe in a shell (got ${JSON.stringify(v)})`);
   }
   return errors;
@@ -123,14 +151,27 @@ const CONFIG_TEMPLATE = `{
       "service": "my-instance.service",                 // systemd unit to restart
       "healthUrl": "http://127.0.0.1:3002/healthz",     // box-side, NOT the apex
       "versionUrl": "http://127.0.0.1:3002/version",    // box-side truth read back after
-      "deployTimer": "my-deploy.timer",                 // pull-deploy timer (its reset --hard is the hazard)
+      "deployTimer": "my-deploy.timer",                 // optional: pull-deploy timer (its reset --hard is the hazard)
       "deployService": "my-deploy.service",             // optional: forced tick proves the pin stuck
       "npmEnvFile": "/etc/my/npm.env",                  // optional: root-only NPM_TOKEN for a PRIVATE package
       "runAs": "me",                                    // optional: unprivileged owner of the instance
       "backupDb": "mydb",                               // optional: pg_dump before the bump
       "backupDir": "~/backups",
       "env": { "PGDATABASE": "mydb" },                  // optional: load-bearing for migrate
-      "registryPackage": "@bongos/core"
+      "registryPackage": "@bongos/core",
+      "pinMode": "push"                                 // optional: push (default) | local-commit | leave-dirty
+    },
+    "a-co-tenant": {
+      // A PROVISIONED instance: no pull-deploy timer to stop, and the repo of record
+      // is the customer's own GitHub repo — so the pin is committed, never pushed.
+      "ssh": "my-box",
+      "instanceDir": "/srv/my-host/their-slug",
+      "service": "their-slug.service",
+      "healthUrl": "http://127.0.0.1:3101/healthz",
+      "versionUrl": "http://127.0.0.1:3101/version",
+      "runAs": "their-slug",
+      "env": { "PGDATABASE": "their_slug" },
+      "pinMode": "local-commit"
     }
   }
 }`;
@@ -455,7 +496,10 @@ function renderReport(r) {
 
   L.push('');
   L.push(`  live reads back   ${r.liveVersion || '(unread)'}`);
-  L.push(`  pin committed     ${r.pinCommitted ? 'yes' : 'NO — the next pull-deploy reset will revert this bump'}`);
+  const mode = r.pinMode || DEFAULT_PIN_MODE;
+  if (mode === 'leave-dirty') L.push('  pin               left in the working tree (pinMode leave-dirty)');
+  else if (r.pinCommitted) L.push(`  pin committed     yes${mode === 'local-commit' ? ' (local commit — this target\'s remote is not ours to push)' : ''}`);
+  else L.push('  pin committed     NO — the next pull-deploy reset will revert this bump');
   L.push('');
   return L.join('\n');
 }
@@ -506,36 +550,78 @@ echo "##END##"
   };
 }
 
+// The `bongos upgrade` invocation, as its own function so the pin-mode wiring is
+// assertable without a box.
+//
+// Both non-default modes pass --pin-no-push, which is what tells upgrade.js the repo of
+// record is not ours: `local-commit` pairs it with --commit-pin (commit, no push), and
+// `leave-dirty` sends it alone, which downgrades upgrade.js's "PIN NOT COMMITTED" alarm
+// to a note. That alarm is correct on a pull-deploy instance and misleading here, and an
+// alarm an operator learns to ignore is worse than no alarm.
+function upgradeCommand(target, targetVersion) {
+  const mode = pinModeOf(target);
+  return [
+    `./node_modules/.bin/bongos upgrade`,
+    `--to ${targetVersion}`, '--registry',
+    `--instance ${target.instanceDir}`,
+    `--service ${target.service}`,
+    `--health-url ${target.healthUrl}`,
+    ...(mode === 'leave-dirty' ? [] : ['--commit-pin']),
+    ...(mode === 'push' ? [] : ['--pin-no-push']),
+    '--force',
+  ].join(' ');
+}
+
+// Whether the post-bump pin state is what this target ASKED for. Under `leave-dirty` a
+// modified working tree is the configured outcome, so reporting it as the durability
+// failure it is on a pull-deploy instance would make a correct co-tenant run read as
+// broken — the one place the three modes must not share a verdict.
+function pinStep(mode, pinDirty, head) {
+  if (mode === 'leave-dirty') {
+    return {
+      name: 'pin left in the working tree (pinMode leave-dirty)',
+      ok: true,
+      detail: pinDirty ? 'package.json/-lock MODIFIED by design — this target has no pull-deploy to revert it' : (head || null),
+    };
+  }
+  return {
+    name: mode === 'local-commit' ? 'pin committed locally (not pushed)' : 'pin committed + pushed',
+    ok: !pinDirty,
+    detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (head || null),
+  };
+}
+
 function applyGoLive(target, targetName, targetVersion, from, opts = {}) {
   const pkg = target.registryPackage || '@bongos/core';
+  const pinMode = pinModeOf(target);
   const steps = [];
   const src = target.npmEnvFile ? `set -a; . ${target.npmEnvFile}; set +a` : 'true';
 
   // Phase A — stop the pull-deploy timer, then back up. The timer's `reset --hard`
-  // is the hazard: it would revert an uncommitted pin mid-flight.
+  // is the hazard: it would revert an uncommitted pin mid-flight. A co-tenant has no
+  // such timer (see REQUIRED_FIELDS), so there is nothing to stop and no hazard.
   const backup = target.backupDb
     ? asOwner(target, `bash -c "mkdir -p ${target.backupDir || '~/backups'} && pg_dump ${target.backupDb} | gzip > ${target.backupDir || '~/backups'}/pre-${targetVersion}-$(date -u +%Y%m%dT%H%M%SZ).sql.gz"`)
     : 'echo "(no backupDb configured — skipping)"';
   const phaseA = remote(target, `
 set -euo pipefail
 ${SUDO_PREAMBLE}
-echo "##TIMER##"; $SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true
+echo "##TIMER##"; ${target.deployTimer
+    ? `$SUDO systemctl stop ${target.deployTimer} && $SUDO systemctl is-active ${target.deployTimer} || true`
+    : 'echo "(no deployTimer configured — no pull-deploy to stop)"'}
 echo "##BACKUP##"; ${backup}
 echo "##END##"
 `, opts);
-  steps.push({ name: `stop ${target.deployTimer} + backup`, ok: phaseA.ok, detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop() });
-  if (!phaseA.ok) return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'PREPARE', raw: phaseA };
+  steps.push({
+    name: target.deployTimer ? `stop ${target.deployTimer} + backup` : 'backup (no pull-deploy timer)',
+    ok: phaseA.ok,
+    detail: phaseA.ok ? null : (phaseA.stderr || '').trim().split('\n').pop(),
+  });
+  if (!phaseA.ok) return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'PREPARE', raw: phaseA };
 
   // Phase B — the upgrade itself. --commit-pin makes the bump durable against the
   // pull-deploy reset; auto-rollback stays ON (do NOT pass --no-rollback-on-failure).
-  const upgrade = [
-    `./node_modules/.bin/bongos upgrade`,
-    `--to ${targetVersion}`, '--registry',
-    `--instance ${target.instanceDir}`,
-    `--service ${target.service}`,
-    `--health-url ${target.healthUrl}`,
-    '--commit-pin', '--force',
-  ].join(' ');
+  const upgrade = upgradeCommand(target, targetVersion);
   const phaseB = remote(target, `
 set -uo pipefail
 ${src}
@@ -549,9 +635,10 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { needsNpm
   });
   if (!phaseB.ok || rolledBack) {
     // Restart the timer even on failure — leaving it stopped silently disables
-    // the instance's pull-deploy until someone notices.
-    remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
-    return { ok: false, steps, from, to: targetVersion, targetName, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
+    // the instance's pull-deploy until someone notices. Nothing was stopped on a
+    // co-tenant, so there is nothing to put back.
+    if (target.deployTimer) remote(target, `${SUDO_PREAMBLE}\n$SUDO systemctl start ${target.deployTimer} || true`, opts);
+    return { ok: false, steps, from, to: targetVersion, targetName, pinMode, failedAt: 'UPGRADE', rolledBack, raw: phaseB };
   }
 
   // Phase C — restart the timer, force one tick, and read back the BOX-SIDE truth.
@@ -560,7 +647,7 @@ ${asOwner(target, `bash -c "cd ${target.instanceDir} && ${upgrade}"`, { needsNpm
   const phaseC = remote(target, `
 set -uo pipefail
 ${SUDO_PREAMBLE}
-echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}
+${target.deployTimer ? `echo "##TIMERSTART##"; $SUDO systemctl start ${target.deployTimer}; $SUDO systemctl is-active ${target.deployTimer}` : ''}
 echo "##PIN##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git status --porcelain -- package.json package-lock.json )
 echo "##HEAD##"; ( cd ${target.instanceDir} && ${target.runAs ? `sudo -u ${target.runAs} -H ` : ''}git log -1 --format='%h %s' )
 ${target.deployService ? `echo "##TICK##"; $SUDO systemctl start ${target.deployService} || true; $SUDO journalctl -u ${target.deployService} -n 20 --no-pager | tail -8` : ''}
@@ -578,13 +665,13 @@ echo "##END##"
   let liveVersion = null;
   try { liveVersion = JSON.parse(section('VERSION') || '{}').coreVersion || null; } catch { liveVersion = null; }
 
-  steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
-  steps.push({ name: 'pin committed + pushed', ok: !pinDirty, detail: pinDirty ? 'package.json/-lock still MODIFIED — the next reset --hard reverts this bump' : (section('HEAD') || null) });
+  if (target.deployTimer) steps.push({ name: `restart ${target.deployTimer}`, ok: (section('TIMERSTART') || '').includes('active') });
+  steps.push(pinStep(pinMode, pinDirty, section('HEAD')));
   steps.push({ name: 'installed package version', ok: installed === targetVersion, detail: installed === targetVersion ? installed : `reports ${installed}, expected ${targetVersion}` });
   steps.push({ name: 'live reads back (box-side)', ok: liveVersion === targetVersion, detail: liveVersion === targetVersion ? liveVersion : `reports ${liveVersion}, expected ${targetVersion}` });
 
   const ok = steps.every((s) => s.ok);
-  return { ok, steps, from, to: targetVersion, targetName, liveVersion, installed, pinCommitted: !pinDirty, raw: phaseC };
+  return { ok, steps, from, to: targetVersion, targetName, pinMode, liveVersion, installed, pinCommitted: !pinDirty, raw: phaseC };
 }
 
 // ---------------------------------------------------------------------------
@@ -608,6 +695,11 @@ go-live — move an enrolled instance's core pin, as one command.
   node scripts/gds/go-live.js --no-divergence     skip the git-derived checks (needs --to)
   node scripts/gds/go-live.js --json              machine-readable
 
+CO-TENANT TARGETS. A provisioned instance has no pull-deploy timer and its repo of
+record is the customer's own, so omit "deployTimer" (the stop/restart is skipped) and
+set "pinMode": "local-commit" (the pin is committed, never pushed). "leave-dirty"
+leaves the bump in the working tree; "push" (the default) is the platform instance.
+
 Host topology is NOT baked into the core. ${DEFAULT_CONFIG} (host-owned, not published):
 
 ${CONFIG_TEMPLATE}
@@ -770,5 +862,6 @@ if (require.main === module) {
 module.exports = {
   loadConfig, selectTarget, validateTarget, planGoLive, parseMarker, parseMarkerHits,
   renderPlan, renderReport, failureExcerpt, asOwner, isSafeToken, NPM_AUTH_PREAMBLE, refreshMain, isLocalTarget, gitRefExists, SUDO_PREAMBLE,
-  CONFIG_TEMPLATE, HALTS, SEMVER_RE,
+  applyGoLive, upgradeCommand, pinStep, pinModeOf,
+  CONFIG_TEMPLATE, HALTS, SEMVER_RE, PIN_MODES, DEFAULT_PIN_MODE,
 };

package/scripts/gds/upgrade.js

@@ -160,7 +160,12 @@ function dirtyPinFiles(instanceDir, run = spawnSync) {
   return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
 }
 
-function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = 'origin', dryRun = false },
+// `push: false` is CO-TENANT MODE (task 1003521). The reasoning above assumes the repo
+// of record is OURS; on a provisioned instance it is the customer's own GitHub repo, so
+// pushing there is both wrong and uncredentialed. Such an instance also has no
+// pull-deploy timer, so nothing will `reset --hard` the pin away — the commit alone
+// makes it durable, and leaves the tree clean for the customer's own pulls.
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false },
   run = spawnSync, log = console.log, err = console.error) {
   const dirty = dirtyPinFiles(instanceDir, run);
   if (dirty === null) return { applicable: false, reason: 'not a git repo' };
@@ -169,6 +174,15 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   const branch = gitCurrentBranch(instanceDir, run);
 
   if (!commitPin) {
+    if (!push) {
+      // No pull-deploy of ours reaches this instance, so an uncommitted pin is untidy
+      // rather than doomed. Crying wolf here would teach an operator to ignore the
+      // warning that DOES matter on the platform instance.
+      err(`  ! pin not committed — ${dirty.join(', ')} changed in the working tree only.`);
+      err('    This target pulls from a repo that is not ours, so nothing here will revert it —');
+      err('    but the tree stays dirty until it is committed. Re-run with --commit-pin to commit it.');
+      return { applicable: true, committed: false, pushed: false, dirty, warned: true };
+    }
     // LOUD — this is the whole point. A silent uncommitted pin is the bug.
     err(`  ! PIN NOT COMMITTED — ${dirty.join(', ')} changed in the working tree only.`);
     err('    On a pull-deploy instance the next push to the repo of record makes deploy.sh');
@@ -184,7 +198,9 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   }
 
   if (dryRun) {
-    log(`  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`);
+    log(push
+      ? `  [dry-run] would commit + push ${dirty.join(', ')} to ${remote}/${branch || 'main'}`
+      : `  [dry-run] would commit ${dirty.join(', ')} locally (no push — this remote is not ours)`);
     return { applicable: true, committed: false, pushed: false, dirty, dryRun: true };
   }
 
@@ -201,8 +217,13 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, remote = '
   }
   log(`  ✓ committed the pin (${dirty.join(', ')})`);
 
-  const push = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
-  if (!push || push.error || push.status !== 0) {
+  if (!push) {
+    log('  ✓ not pushed, by request — this instance\'s repo of record is not ours, and no pull-deploy of ours can revert the commit');
+    return { applicable: true, committed: true, pushed: false, dirty, pushSkipped: true };
+  }
+
+  const pushed = run('git', ['push', remote, `HEAD:${branch || 'main'}`], { cwd: instanceDir, encoding: 'utf8' });
+  if (!pushed || pushed.error || pushed.status !== 0) {
     // Committed but not pushed is still doomed: deploy.sh resets to the REMOTE.
     err(`  ! commit landed locally but the push to ${remote} FAILED — this bump is still not durable.`);
     err(`    Push it: git -C ${instanceDir} push ${remote} HEAD:${branch || 'main'}`);
@@ -984,6 +1005,7 @@ async function runUpgrade(opts, deps = {}) {
     fromVersion,
     toVersion: targetVersion,
     commitPin: opts.commitPin,
+    push: !opts.pinNoPush,
     remote: opts.gitRemote || 'origin',
     dryRun: opts.dryRun,
   }, run, log, err);
@@ -1006,6 +1028,7 @@ function parseArgs(argv) {
     pinPath: arg('--pin-path', argv),
     registry: hasFlag('--registry', argv), // ADR 0134: pull @bongos/core@<--to> from the npm registry instead of vendoring
     commitPin: hasFlag('--commit-pin', argv), // task 1002712: commit + push package.json/-lock so a pull-deploy reset cannot revert the bump
+    pinNoPush: hasFlag('--pin-no-push', argv), // task 1003521 co-tenant mode: commit the pin but leave the customer's own remote alone
     gitRemote: arg('--git-remote', argv),
     dryRun: hasFlag('--dry-run', argv),
     force: hasFlag('--force', argv),
@@ -1042,6 +1065,7 @@ async function main(argv = process.argv.slice(2)) {
       '  --skip-pin-verify    do not verify the integrity pin (tree_sha256 + tarball.sha256) after install',
       '  --require-pin        treat a MISSING reference manifest as fatal (default: warn — a MISMATCH is always fatal)',
       '  --no-rollback-on-failure  do NOT auto-revert on a failed install/pin-verify/migrate/health check (default: auto-rollback ON)',
+      '  --pin-no-push        with --commit-pin: commit the pin but do NOT push it — for an instance whose repo of record is not ours (a provisioned co-tenant), where the push is wrong and no pull-deploy can revert the commit',
       '  --dry-run            show the plan; change nothing',
       '  --force              skip the clean-tree + same-version guards',
       '',

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.675'; // 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/go_live.mjs

@@ -144,9 +144,11 @@ test('a typo’d field is reported, never silently ignored', () => {
 
 test('missing required fields are named individually', () => {
   const errs = G.validateTarget('t', { ssh: 'box' });
-  for (const f of ['instanceDir', 'service', 'healthUrl', 'versionUrl', 'deployTimer']) {
+  for (const f of ['instanceDir', 'service', 'healthUrl', 'versionUrl']) {
     assert.match(errs.join(' '), new RegExp(`missing required field "${f}"`));
   }
+  // deployTimer is co-tenant-optional (task 1003521) and must NOT be demanded.
+  assert.ok(!/missing required field "deployTimer"/.test(errs.join(' ')));
 });
 
 test('a valid target passes clean', () => {
@@ -393,7 +395,7 @@ test('ssh is OPTIONAL — a local target validates clean', () => {
 
 test('the remaining required fields are still enforced for a local target', () => {
   const errs = G.validateTarget('local', { instanceDir: '/i' });
-  for (const f of ['service', 'healthUrl', 'versionUrl', 'deployTimer']) {
+  for (const f of ['service', 'healthUrl', 'versionUrl']) {
     assert.match(errs.join(' '), new RegExp(`missing required field "${f}"`));
   }
   // ssh must NOT be demanded any more.
@@ -411,3 +413,173 @@ test('gitRefExists reports rather than throwing', () => {
   assert.equal(G.gitRefExists('x', { run: () => ({ status: 1 }) }), false);
   assert.equal(G.gitRefExists('x', { run: () => ({ error: new Error('ENOENT') }) }), false);
 });
+
+// ---------------------------------------------------------------------------
+// Co-tenant mode (task 1003521)
+//
+// go-live drove the PLATFORM instance and could not drive a provisioned co-tenant,
+// for two structural reasons, so mercury had to be upgraded by hand from a box-side
+// script — the exact one-command path this file exists to provide:
+//
+//   1. deployTimer was REQUIRED. A co-tenant has no pull-deploy timer at all (only
+//      its <slug>-db-backup.timer), so the config could not even be AUTHORED without
+//      inventing a unit name that the script would then try to `systemctl stop`.
+//   2. The pin was always PUSHED. On a co-tenant the repo of record is the customer's
+//      own GitHub repo, so that push is both wrong and, in practice, uncredentialed.
+//
+// The assertions below are on the scripts applyGoLive COMPOSES and the verdicts it
+// reaches — `run` is injected, so nothing here touches a box.
+// ---------------------------------------------------------------------------
+
+const coTenant = {
+  ssh: 'my-box',
+  instanceDir: '/srv/my-host/their-slug',
+  service: 'their-slug.service',
+  healthUrl: 'http://127.0.0.1:3101/healthz',
+  versionUrl: 'http://127.0.0.1:3101/version',
+  pinMode: 'local-commit',
+};
+
+// Canned phase-C output. The sections are what applyGoLive parses its verdicts from.
+const phaseC = ({ timer = true, pin = '', version = '1.19.306', installed = '1.19.306' } = {}) => [
+  timer ? '##TIMERSTART##\nactive' : '',
+  `##PIN##\n${pin}`,
+  '##HEAD##\ndeadbee pin @bongos/core 1.19.306',
+  `##VERSION##\n{"coreVersion":"${version}"}`,
+  `##INSTALLED##\n${installed}`,
+  '##END##',
+].filter(Boolean).join('\n');
+
+// Records every script fed to a shell. `upgradeFails` drives the rollback path.
+function fakeShell({ upgradeFails = false, phaseCOut = phaseC() } = {}) {
+  const scripts = [];
+  const fn = (cmd, args, opts = {}) => {
+    const input = opts.input || '';
+    scripts.push(input);
+    if (input.includes('bongos upgrade')) return { status: upgradeFails ? 1 : 0, stdout: '', stderr: upgradeFails ? 'boom' : '' };
+    if (input.includes('##PIN##')) return { status: 0, stdout: phaseCOut, stderr: '' };
+    return { status: 0, stdout: '##TIMER##\n##BACKUP##\n##END##', stderr: '' };
+  };
+  fn.scripts = scripts;
+  fn.all = () => scripts.join('\n');
+  return fn;
+}
+
+const stepNames = (r) => (r.steps || []).map((s) => s.name);
+
+test('pinMode defaults to push, so an existing config keeps its behaviour', () => {
+  assert.equal(G.pinModeOf(okTarget), 'push');
+  assert.equal(G.pinModeOf({}), 'push');
+  assert.equal(G.pinModeOf(undefined), 'push');
+  assert.equal(G.pinModeOf({ pinMode: 'leave-dirty' }), 'leave-dirty');
+});
+
+test('a bogus pinMode is REFUSED, and each documented one validates', () => {
+  assert.match(G.validateTarget('t', { ...okTarget, pinMode: 'shove-it' }).join(' '), /pinMode must be one of/);
+  for (const m of G.PIN_MODES) assert.deepEqual(G.validateTarget('t', { ...okTarget, pinMode: m }), []);
+});
+
+test('push mode pushes the pin; the two co-tenant modes never do', () => {
+  const cmd = (t) => G.upgradeCommand(t, '1.19.306');
+
+  // The platform instance: --commit-pin ALONE, which pushes (task 1002712 — thirteen
+  // releases were lost to an unpushed pin, so this is the regression that matters).
+  const push = cmd({ ...okTarget, pinMode: 'push' });
+  assert.ok(push.includes('--commit-pin'), 'push mode must still commit the pin');
+  assert.ok(!push.includes('--pin-no-push'), 'push mode must NOT suppress the push');
+
+  // local-commit: commit it, leave the customer's remote alone.
+  const local = cmd({ ...okTarget, pinMode: 'local-commit' });
+  assert.ok(local.includes('--commit-pin') && local.includes('--pin-no-push'));
+
+  // leave-dirty: no commit at all, and --pin-no-push so upgrade.js does not raise the
+  // pull-deploy alarm at an instance that has no pull-deploy.
+  const dirty = cmd({ ...okTarget, pinMode: 'leave-dirty' });
+  assert.ok(!dirty.includes('--commit-pin'), 'leave-dirty must not commit');
+  assert.ok(dirty.includes('--pin-no-push'));
+
+  // Unchanged for every mode: auto-rollback stays ON.
+  for (const c of [push, local, dirty]) assert.ok(!c.includes('--no-rollback-on-failure'));
+});
+
+test('a co-tenant target validates with NO deployTimer — the field that blocked the config', () => {
+  assert.deepEqual(G.validateTarget('a-co-tenant', coTenant), []);
+});
+
+test('with no deployTimer, nothing is stopped, started, or reported as restarted', () => {
+  const run = fakeShell({ phaseCOut: phaseC({ timer: false }) });
+  const r = G.applyGoLive(coTenant, 'a-co-tenant', '1.19.306', '1.19.300', { run });
+
+  assert.equal(r.ok, true, `expected a clean run, got ${JSON.stringify(stepNames(r))}`);
+  // The bug shape: an invented unit name reaching systemctl, or a literal `undefined`.
+  assert.ok(!/systemctl (stop|start)/.test(run.all()), 'must not touch a timer it has not got');
+  assert.ok(!run.all().includes('undefined'), 'no field may interpolate as undefined');
+  assert.ok(!stepNames(r).some((n) => /restart/.test(n)), 'no restart step for a timer that does not exist');
+  assert.match(stepNames(r)[0], /^backup \(no pull-deploy timer\)$/);
+});
+
+test('the platform instance still stops the timer and puts it back', () => {
+  const run = fakeShell();
+  const r = G.applyGoLive({ ...okTarget, deployTimer: 'inst-deploy.timer' }, 'web', '1.19.306', '1.19.300', { run });
+
+  assert.equal(r.ok, true);
+  assert.match(run.all(), /systemctl stop inst-deploy\.timer/);
+  assert.match(run.all(), /systemctl start inst-deploy\.timer/);
+  assert.ok(stepNames(r).includes('restart inst-deploy.timer'));
+});
+
+test('a failed upgrade restarts the timer it stopped — and asks for none when it stopped none', () => {
+  const withTimer = fakeShell({ upgradeFails: true });
+  const a = G.applyGoLive(okTarget, 'web', '1.19.306', '1.19.300', { run: withTimer });
+  assert.equal(a.ok, false);
+  assert.equal(a.failedAt, 'UPGRADE');
+  assert.match(withTimer.all(), /systemctl start inst-deploy\.timer/);
+
+  const coT = fakeShell({ upgradeFails: true });
+  const b = G.applyGoLive(coTenant, 'a-co-tenant', '1.19.306', '1.19.300', { run: coT });
+  assert.equal(b.ok, false);
+  assert.ok(!/systemctl start/.test(coT.all()), 'nothing was stopped, so nothing is restarted');
+});
+
+test('a dirty pin is the durability failure it is under push and local-commit', () => {
+  for (const pinMode of ['push', 'local-commit']) {
+    const run = fakeShell({ phaseCOut: phaseC({ pin: ' M package.json' }) });
+    const r = G.applyGoLive({ ...okTarget, pinMode }, 'web', '1.19.306', '1.19.300', { run });
+    assert.equal(r.ok, false, `${pinMode} must fail on an uncommitted pin`);
+    assert.equal(r.pinCommitted, false);
+  }
+});
+
+test('under leave-dirty the SAME dirty pin is the configured outcome, not a failure', () => {
+  const run = fakeShell({ phaseCOut: phaseC({ pin: ' M package.json' }) });
+  const r = G.applyGoLive({ ...okTarget, pinMode: 'leave-dirty' }, 'web', '1.19.306', '1.19.300', { run });
+  assert.equal(r.ok, true, `a correct leave-dirty run must not read as broken: ${JSON.stringify(stepNames(r))}`);
+  assert.match(stepNames(r).join(' '), /leave-dirty/);
+});
+
+test('the health and version gates are untouched by pin mode', () => {
+  // A co-tenant serving the WRONG version must still fail, or co-tenant mode would be
+  // a way to get a green report out of a bump that did not take.
+  const run = fakeShell({ phaseCOut: phaseC({ timer: false, version: '1.19.300' }) });
+  const r = G.applyGoLive(coTenant, 'a-co-tenant', '1.19.306', '1.19.300', { run });
+  assert.equal(r.ok, false);
+  assert.match(stepNames(r).join(' '), /live reads back/);
+});
+
+test('the report does not promise a push it did not make', () => {
+  const base = { targetName: 'x', from: '1.19.300', to: '1.19.306', steps: [], liveVersion: '1.19.306', ok: true };
+  assert.match(G.renderReport({ ...base, pinMode: 'push', pinCommitted: true }), /pin committed {5}yes$/m);
+  assert.match(G.renderReport({ ...base, pinMode: 'local-commit', pinCommitted: true }), /local commit/);
+  assert.match(G.renderReport({ ...base, pinMode: 'leave-dirty', pinCommitted: false }), /left in the working tree/);
+  // An absent pinMode (a failure return from an older path) still reads as push.
+  assert.match(G.renderReport({ ...base, pinCommitted: false }), /next pull-deploy reset will revert/);
+});
+
+test('the shipped co-tenant template is itself valid config', () => {
+  const r = G.loadConfig({ configPath: 'x.json', exists: () => true, readFile: () => G.CONFIG_TEMPLATE });
+  assert.ok(r.ok, `template did not parse: ${r.detail || ''}`);
+  const sel = G.selectTarget(r.config, 'a-co-tenant');
+  assert.ok(sel.ok, `co-tenant template target invalid: ${sel.detail || ''}`);
+  assert.equal(sel.target.pinMode, 'local-commit');
+  assert.equal(sel.target.deployTimer, undefined);
+});

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 () => {

package/tests/upgrade_persist_pin.mjs

@@ -146,6 +146,67 @@ test('the copy-pasteable fix line is shell-quoted', () => {
   assert.equal((cmd.match(/'/g) || []).length % 2, 0, 'every quote is closed');
 });
 
+// ── push: false — co-tenant mode (task 1003521) ─────────────────────────────
+//
+// The reasoning above assumes the repo of record is OURS. On a PROVISIONED instance it
+// is the customer's own GitHub repo, so the push is both wrong and, in practice,
+// uncredentialed — and with no pull-deploy timer nothing will reset the pin away, so
+// the commit alone is durable. go-live.js passes --pin-no-push for such a target.
+
+test('push: false commits the pin and stops there', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false }, run, quiet, quiet);
+
+  assert.equal(r.committed, true);
+  assert.equal(r.pushed, false);
+  assert.equal(r.pushSkipped, true);
+  assert.ok(!r.error, 'a skipped push is not a failure');
+  assert.ok(run.calls.some((c) => c === `git add ${PIN_FILES.join(' ')}`), 'still stages the pin files');
+  assert.ok(run.calls.some((c) => c.startsWith('git commit -m pin @bongos/core')), 'still commits');
+  assert.ok(!run.calls.some((c) => c.startsWith('git push')), 'must NOT touch a remote that is not ours');
+});
+
+test('push defaults to true, so every existing caller still pushes', () => {
+  // The absent field must not silently become co-tenant mode: that is how thirteen
+  // releases were lost the first time.
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true }, run, quiet, quiet);
+  assert.equal(r.pushed, true);
+  assert.ok(run.calls.some((c) => c === 'git push origin HEAD:main'));
+});
+
+test('a co-tenant with no --commit-pin gets a NOTE, not the pull-deploy alarm', () => {
+  // The loud warning is correct on a pull-deploy instance and false here. An alarm an
+  // operator learns to ignore is worse than no alarm.
+  const warnings = [];
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: false, push: false }, run, quiet, (m) => warnings.push(m));
+
+  assert.equal(r.warned, true);
+  assert.equal(r.committed, false);
+  const text = warnings.join('\n');
+  assert.ok(!/PIN NOT COMMITTED/.test(text), 'no shouting about a revert that cannot happen');
+  assert.ok(!/reset --hard/.test(text), 'and no claim that a pull-deploy will revert it');
+  assert.match(text, /not ours/, 'says why the push is off');
+  assert.match(text, /--commit-pin/, 'still names the fix for the dirty tree');
+});
+
+test('--dry-run under push: false does not promise a push', () => {
+  const logs = [];
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, dryRun: true }, run, (m) => logs.push(m), quiet);
+  assert.equal(r.dryRun, true);
+  assert.ok(!/push/.test(logs.join('\n').replace(/no push/g, '')), `dry-run must not claim a push: ${logs.join('\n')}`);
+  assert.ok(!run.calls.some((c) => c.includes('git commit') || c.includes('git push')));
+});
+
+test('a failed commit under push: false still reports the failure', () => {
+  const run = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN, commit: { status: 1, stdout: '' } });
+  const r = persistPin({ ...base, commitPin: true, push: false }, run, quiet, quiet);
+  assert.equal(r.committed, false);
+  assert.ok(!r.pushSkipped, 'nothing was skipped — the commit never happened');
+});
+
 // ── preflightDbIdentity (task 1002712) ──────────────────────────────────────
 // migrate.sh uses peer auth, so `sudo bongos upgrade` connects as root, which is
 // almost never a Postgres role. That surfaced as a raw FATAL mid-run, AFTER the