@bongos/core 1.19.675 → 1.19.676

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.676",
+  "core_contract": "1.19.676",
+  "source_commit": "9aad4d0005991e8ba38f4443b4e5611a13aa3af8",
   "source_ref": "HEAD",
-  "built_at": "2026-09-11T19:32:52.079Z",
+  "built_at": "2026-09-11T20:44:28.469Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 474,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2621,
-  "tree_sha256": "554ecf20aaad28b8461021791d1e5c4d2c890a860a458885227f20429b946339",
+  "tree_sha256": "b556a6e9644d99b65ffdf9ac64384eee16b20ecfb7e31ed60c875d76297310f3",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2792,7 +2792,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "af50f99c27d85db0067d45e5e6eba133edcae8b3dd7388041b6824f4cb192e22"
+      "sha256": "b8786c58575f93eb93661ee1d7e0745f0993f5666e5237ca073177df2d3ee9f4"
     },
     {
       "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",
@@ -7767,12 +7767,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "795b9955321b5ecffd9d78f515649442016285cb21f728c4001ee97ebcc32ac5"
+      "sha256": "3b0ebf2f1fb870085a40531295fb3c5989be5ab399e2493e43a1e3e844b0633c"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "33bcb1180ab5e54281e7c50d39a712d142b259f77f37b685f2bb4512b1c010fa"
+      "sha256": "b4c1e3c5189ac7220af056624bdc0476a0d751c00aa76aba2e84416128280bc7"
     },
     {
       "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": "406c218b56b011b4560887f2ae4e13f20e227fa4404e6763649e2eac2b0f5292"
     },
     {
       "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",
@@ -12982,7 +12982,7 @@
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "07fd48b255bbd2370580b62a8f77d7fc981b0dfdefcc5be6973a9c4d6cb49add"
+      "sha256": "c0a96fbdc6a9f851925babfb0857c9a168374c4165c84884f5c4c56c7177dd58"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/module-api-changelog.md

@@ -1809,5 +1809,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.675",
+  "version": "1.19.676",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.675",
+      "version": "1.19.676",
       "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.676",
   "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.676'; // 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/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