@bongos/core 1.19.851 → 1.19.852

package/modules/lifecycle/db-analytics.js

@@ -278,8 +278,35 @@ async function gradeTrendByDay(days = 30) {
 // -------------------------------------------------------------------------
 
 
-async function builderAnalytics(builderId, days = 90) {
+// THE KIND DIMENSION (task 1004005). `kind` narrows every series that CAN be
+// narrowed to one kind of work, so the page can answer "how am I doing at THIS
+// kind of work". Three rules it follows, each of them a correctness rule rather
+// than a style one:
+//
+//  1. COST IS NOT ANSWERABLE PER KIND, and is therefore not answered. cost_log
+//     has no kind and reaches tasks only through a NULLABLE task_id that is
+//     "NULL for non-task spend (infra, domain, etc.)" — most rows, as the
+//     cost-per-work comment below records. A kind-filtered cost line would
+//     silently drop nearly every cost row and plot a near-zero trend that looks
+//     like a real, cheap one. So a filtered call returns cost_trend: [] and
+//     cost_per_task: null, and the payload says why in `unavailable` — the page
+//     hides the chart and states the reason instead of drawing a lie.
+//  2. top_kinds is NEVER filtered. It is the fingerprint the kind picker is
+//     BUILT from; narrowing it to the selected kind would leave the reader with
+//     one bar and no way back.
+//  3. The same `kind` is honoured by ecosystemAnalytics, so the overlay compares
+//     like with like. A filtered line against an unfiltered benchmark is the
+//     failure mode this task's own text names as worse than no benchmark.
+//
+// An unknown kind is not rejected here — it simply matches nothing, which reads
+// as an empty window. COALESCE mirrors top_kinds, so the literal 'unspecified'
+// bucket the fingerprint shows is selectable.
+async function builderAnalytics(builderId, days = 90, kind = null) {
   const d = String(days);
+  const k = kind === undefined || kind === null || kind === '' ? null : String(kind);
+  // Every kind-aware series takes this as its LAST parameter: null → no filter,
+  // so an unfiltered call runs the same plan it always did.
+  const KIND_TASKS = `($3::text IS NULL OR COALESCE(kind, 'unspecified') = $3)`;
   const [shipRate, costTrend, durationTrend, gradeTrend, topKinds, headline, claimRollup] =
     await Promise.all([
       // Ships per day — the core "dev curve".
@@ -290,11 +317,14 @@ async function builderAnalytics(builderId, days = 90) {
           WHERE shipped_by = $1 AND status = 'shipped'
             AND shipped_at >= now() - ($2 || ' days')::interval
             AND ${SMOKE_NOT_LIKE}
+            AND ${KIND_TASKS}
           GROUP BY 1 ORDER BY 1 ASC`,
-        [builderId, d]
+        [builderId, d, k]
       ),
       // Cost per day + tasks touched that day → cost-per-task in JS.
-      pool.query(
+      // Skipped entirely under a kind filter — see rule 1 above. Not queried and
+      // then discarded: an un-askable question should not cost a round trip.
+      k !== null ? { rows: [] } : pool.query(
         `SELECT to_char(date_trunc('day', recorded_at), 'YYYY-MM-DD') AS day,
                 SUM(amount_usd)::numeric(12,2) AS total_usd,
                 COUNT(DISTINCT task_id)::int AS n_tasks
@@ -314,8 +344,9 @@ async function builderAnalytics(builderId, days = 90) {
             AND actual_minutes IS NOT NULL AND est_minutes IS NOT NULL
             AND shipped_at >= now() - ($2 || ' days')::interval
             AND ${SMOKE_NOT_LIKE}
+            AND ${KIND_TASKS}
           GROUP BY 1 ORDER BY 1 ASC`,
-        [builderId, d]
+        [builderId, d, k]
       ),
       // Grade pass-rate per day (quality holding up as throughput rises?).
       // Quality-graded rows only — outage / null-axis rows would read as
@@ -330,10 +361,14 @@ async function builderAnalytics(builderId, days = 90) {
            JOIN tasks t ON t.id = g.task_id
           WHERE t.shipped_by = $1
             AND g.graded_at >= now() - ($2 || ' days')::interval
+            AND ($3::text IS NULL OR COALESCE(t.kind, 'unspecified') = $3)
           GROUP BY 1 ORDER BY 1 ASC`,
-        [builderId, d]
+        [builderId, d, k]
       ),
       // Top kinds shipped (all-time — a "what do I build" fingerprint).
+      // DELIBERATELY UNFILTERED — see rule 2 above: this list is what the kind
+      // picker is built from, so narrowing it to the current selection would
+      // leave the reader one bar and no way back to the others.
       pool.query(
         `SELECT COALESCE(kind, 'unspecified') AS kind, COUNT(*)::int AS n
            FROM tasks
@@ -352,18 +387,23 @@ async function builderAnalytics(builderId, days = 90) {
            FROM tasks
           WHERE shipped_by = $1
             AND ${SMOKE_NOT_LIKE}
+            AND ${KIND_TASKS}
             AND (shipped_at IS NULL OR shipped_at >= now() - ($2 || ' days')::interval)`,
-        [builderId, d]
+        [builderId, d, k]
       ),
       // Confirmation rate — share of resolved claims that ended in a ship
       // (vs. abandoned / expired / partial). Distinct from the grade pass-rate.
       pool.query(
         `SELECT COUNT(*)::int AS resolved_claims,
                 SUM(CASE WHEN outcome = 'shipped' THEN 1 ELSE 0 END)::int AS shipped_claims
-           FROM claims
-          WHERE builder_id = $1 AND outcome IS NOT NULL
-            AND claimed_at >= now() - ($2 || ' days')::interval`,
-        [builderId, d]
+           FROM claims c
+          WHERE c.builder_id = $1 AND c.outcome IS NOT NULL
+            AND c.claimed_at >= now() - ($2 || ' days')::interval
+            AND ($3::text IS NULL OR EXISTS (
+                  SELECT 1 FROM tasks t
+                   WHERE t.id = c.task_id
+                     AND COALESCE(t.kind, 'unspecified') = $3))`,
+        [builderId, d, k]
       ),
     ]);
 
@@ -408,15 +448,24 @@ async function builderAnalytics(builderId, days = 90) {
 
   return {
     window_days: days,
+    kind: k, // the filter in force, echoed so a client can never mislabel a chart
+    // WHAT THIS WINDOW CANNOT ANSWER, named rather than left to look like a
+    // zero. Under a kind filter cost is un-attributable (see rule 1), so the
+    // page hides those two readouts and says why. An unfiltered call omits
+    // nothing and this is [].
+    unavailable: k === null ? [] : ['cost_trend', 'cost_per_task', 'total_cost_usd'],
     ship_rate: shipRate.rows, // [{ day, n }]
-    cost_trend, // [{ day, total_usd, n_tasks, per_work }] — per_work is cumulative (task 1503)
+    cost_trend, // [{ day, total_usd, n_tasks, per_work }] — per_work is cumulative (task 1503); [] under a kind filter
     duration_trend: durationTrend.rows, // [{ day, avg_actual, avg_est }]
     grade_trend: grades, // [{ day, n, n_passed, avg_score }]
-    top_kinds: topKinds.rows, // [{ kind, n }]
+    top_kinds: topKinds.rows, // [{ kind, n }] — always ALL kinds; this is the picker's source
     headline: {
       total_shipped: h.total_shipped,
-      total_cost_usd: Math.round(totalCost * 100) / 100,
-      cost_per_task: h.total_shipped > 0 ? Math.round((totalCost / h.total_shipped) * 100) / 100 : 0,
+      // null, not 0, under a kind filter: 0 is a measurement and this is the
+      // absence of one. A client that prints $0.00 here has said something false.
+      total_cost_usd: k === null ? Math.round(totalCost * 100) / 100 : null,
+      cost_per_task: k !== null ? null
+        : h.total_shipped > 0 ? Math.round((totalCost / h.total_shipped) * 100) / 100 : 0,
       avg_duration_min: h.avg_duration_min,
       confirmation_rate: c.resolved_claims > 0 ? Math.round((c.shipped_claims / c.resolved_claims) * 100) / 100 : null,
       resolved_claims: c.resolved_claims,
@@ -433,8 +482,14 @@ async function builderAnalytics(builderId, days = 90) {
 // daily series already have public feeds (/public/grades, /public/cost-summary),
 // so this adds just the ship-rate, duration, top-kinds, and headline aggregates.
 
-async function ecosystemAnalytics(days = 90) {
+async function ecosystemAnalytics(days = 90, kind = null) {
   const d = String(days);
+  // Same contract as builderAnalytics' kind, and for one reason: the hall overlays
+  // this series on a builder's own. If only one side could be narrowed, the overlay
+  // would compare a kind against the whole ecosystem and still look like a
+  // like-for-like benchmark (task 1004005).
+  const k = kind === undefined || kind === null || kind === '' ? null : String(kind);
+  const KIND_TASKS = `($2::text IS NULL OR COALESCE(kind, 'unspecified') = $2)`;
   const [shipRate, durationTrend, topKinds, headline] = await Promise.all([
     pool.query(
       `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
@@ -443,8 +498,9 @@ async function ecosystemAnalytics(days = 90) {
         WHERE status = 'shipped' AND shipped_by IS NOT NULL
           AND shipped_at >= now() - ($1 || ' days')::interval
           AND ${SMOKE_NOT_LIKE}
+          AND ${KIND_TASKS}
         GROUP BY 1 ORDER BY 1 ASC`,
-      [d]
+      [d, k]
     ),
     pool.query(
       `SELECT to_char(date_trunc('day', shipped_at), 'YYYY-MM-DD') AS day,
@@ -455,8 +511,9 @@ async function ecosystemAnalytics(days = 90) {
           AND actual_minutes IS NOT NULL AND est_minutes IS NOT NULL
           AND shipped_at >= now() - ($1 || ' days')::interval
           AND ${SMOKE_NOT_LIKE}
+          AND ${KIND_TASKS}
         GROUP BY 1 ORDER BY 1 ASC`,
-      [d]
+      [d, k]
     ),
     pool.query(
       `SELECT COALESCE(kind, 'unspecified') AS kind, COUNT(*)::int AS n
@@ -475,17 +532,19 @@ async function ecosystemAnalytics(days = 90) {
          FROM tasks
         WHERE status = 'shipped' AND shipped_by IS NOT NULL
           AND shipped_at >= now() - ($1 || ' days')::interval
-          AND ${SMOKE_NOT_LIKE}`,
-      [d]
+          AND ${SMOKE_NOT_LIKE}
+          AND ${KIND_TASKS}`,
+      [d, k]
     ),
   ]);
 
   const h = headline.rows[0] || { total_shipped: 0, active_builders: 0, avg_duration_min: 0 };
   return {
     window_days: days,
+    kind: k, // echoed so an overlay can prove both sides were narrowed the same way
     ship_rate: shipRate.rows,
     duration_trend: durationTrend.rows,
-    top_kinds: topKinds.rows,
+    top_kinds: topKinds.rows, // always ALL kinds — the picker's source, never narrowed
     headline: {
       total_shipped: h.total_shipped,
       active_builders: h.active_builders,

package/modules/lifecycle/routes/analytics.js

@@ -28,6 +28,26 @@ function parseDays(raw) {
   return 90;
 }
 
+// The `kind` filter (task 1004005) — "how am I doing at THIS kind of work".
+//
+// Bounded HERE rather than trusted to the query layer, even though both callers
+// pass it as a bound $n parameter and neither interpolates it. A kind is one
+// short token from a known vocabulary, so anything longer or stranger is a
+// mistake or a probe, and a 200-char string has no business reaching a GROUP BY
+// on either of these tables. An absent, blank or over-long value resolves to
+// null, which every query below reads as "no filter" — the unfiltered plan.
+//
+// An UNRECOGNISED kind is deliberately NOT rejected: `kind` is a free text
+// column with a COALESCE('unspecified') bucket, the vocabulary grows, and a 400
+// on a kind that simply has no rows yet would be a worse answer than the honest
+// empty window the filter already returns.
+const KIND_MAX = 40;
+function parseKind(raw) {
+  const s = (raw === undefined || raw === null ? '' : String(raw)).trim();
+  if (!s || s.length > KIND_MAX) return null;
+  return s;
+}
+
 module.exports = function buildAnalyticsRouter() {
   const router = express.Router();
 
@@ -40,7 +60,7 @@ module.exports = function buildAnalyticsRouter() {
   // rank: public — ecosystem-wide dev-curve aggregate; individuals stripped.
   router.get('/public/analytics/ecosystem', asyncHandler('GET /public/analytics/ecosystem', async (req, res) => {
     const days = parseDays(req.query.days);
-    const data = await db.ecosystemAnalytics(days);
+    const data = await db.ecosystemAnalytics(days, parseKind(req.query.kind));
     res.set('Cache-Control', 'public, max-age=60');
     res.json(data);
   }, { message: false, errorCode: 'ecosystem_analytics_failed' }));
@@ -55,7 +75,7 @@ module.exports = function buildAnalyticsRouter() {
       return res.fail('forbidden', { status: 403, message: 'You can only view your own analytics.' });
     }
     const days = parseDays(req.query.days);
-    const data = await db.builderAnalytics(targetId, days);
+    const data = await db.builderAnalytics(targetId, days, parseKind(req.query.kind));
     res.json({ builder_id: targetId, ...data });
   }, { message: false, errorCode: 'builder_analytics_failed' }));
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.851",
+  "version": "1.19.852",
   "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/provision-repo-auth.js

@@ -27,6 +27,7 @@
 
 'use strict';
 
+const { execFileSync } = require('node:child_process');
 const path = require('node:path');
 
 // The same value provision-config.js exports as REPO_ROOT, recomputed here rather than
@@ -44,14 +45,55 @@ function parseTargetRef(ref) {
   return m ? { owner: m[1], name: m[2] } : null;
 }
 
-// The git remote for an instance's OWN repo. Reuses the SAME SSH deploy alias the
-// control-plane checkout uses (git@<alias>:<owner>/<repo>.git) — NO secret in the
-// command (SSH-key auth, nothing to leak into journald), consistent with how the
-// platform repo is wired. Standing up a new instance repo therefore needs only that
-// the control plane's deploy key has WRITE access to that repo (ADR 0125). Alias is
-// overridable via PROVISION_GIT_SSH_ALIAS.
-function instanceRepoRemote(repo, { sshAlias = process.env.PROVISION_GIT_SSH_ALIAS || 'github-deploy' } = {}) {
-  return `git@${sshAlias}:${repo.owner}/${repo.name}.git`;
+// The SSH alias the founder control plane wires for the platform repo (ADR 0125/0129).
+const DEPLOY_ALIAS = 'github-deploy';
+
+// One probe per alias per process — `ssh -G` re-reads the same static config every call.
+const aliasProbeCache = new Map();
+
+// Does an SSH host alias actually resolve HERE? `ssh -G <name>` prints the effective
+// config for that name: a real `Host <name>` block rewrites `hostname`, an absent one
+// echoes the name straight back — which is then exactly what git hands to DNS, and
+// fails on. A box with no ssh client at all answers the same way. This has to be probed
+// rather than assumed because the alias is a property of ONE box's ~/.ssh/config, not of
+// this code (task 1003996). `runSsh` is injectable for tests; nothing spawns at require
+// time, so this file stays inert on the merge-resolver path (see the header).
+function sshAliasResolves(alias, runSsh) {
+  if (!runSsh && aliasProbeCache.has(alias)) return aliasProbeCache.get(alias);
+  let resolves = false;
+  try {
+    const probe = runSsh || ((a) => execFileSync('ssh', ['-G', a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }));
+    const hostname = (String(probe(alias)).match(/^hostname[ \t]+(\S+)/mi) || [])[1];
+    resolves = !!hostname && hostname.toLowerCase() !== alias.toLowerCase();
+  } catch { resolves = false; }
+  if (!runSsh) aliasProbeCache.set(alias, resolves);
+  return resolves;
+}
+
+// The git remote for an instance's OWN repo — git@<alias>:<owner>/<repo>.git, NO secret
+// in the command (SSH-key auth, nothing to leak into journald).
+//
+// Which <alias>: an explicit one, else PROVISION_GIT_SSH_ALIAS, else the control plane's
+// own deploy alias WHEN IT RESOLVES here, else github.com. The last two rungs are the
+// point: reusing the founder box's alias is what makes the instance repo reachable by the
+// same key that already pushes the platform repo (ADR 0125), and on that box the probe
+// keeps choosing it. Anywhere else the alias is a dangling name, and `git@github.com:` is
+// both the correct address and the one a plane's own deploy key is issued against.
+function instanceRepoRemote(repo, { sshAlias, runSsh } = {}) {
+  const alias = sshAlias
+    || process.env.PROVISION_GIT_SSH_ALIAS
+    || (sshAliasResolves(DEPLOY_ALIAS, runSsh) ? DEPLOY_ALIAS : 'github.com');
+  return `git@${alias}:${repo.owner}/${repo.name}.git`;
+}
+
+// Every remote URL shape this code writes for `repo`: the github.com form plus the deploy
+// alias in play. What a stored remote is VALIDATED against (upgrade.js), which must not
+// re-run the probe — a remote we wrote stays ours even from a box where the alias no
+// longer resolves.
+function instanceRepoRemotes(repo) {
+  const aliases = new Set(['github.com', DEPLOY_ALIAS]);
+  if (process.env.PROVISION_GIT_SSH_ALIAS) aliases.add(process.env.PROVISION_GIT_SSH_ALIAS);
+  return [...aliases].map((a) => `git@${a}:${repo.owner}/${repo.name}.git`);
 }
 
 // The instance owner's stored `repo`-scoped OAuth token (ADR 0155), or null (none
@@ -100,6 +142,7 @@ async function lookupInstanceRow(instanceDir, deps = {}) {
 
 module.exports = {
   instanceRepoRemote,
+  instanceRepoRemotes,
   lookupInstanceRow,
   parseTargetRef,
   resolveOwnerGithubToken,

package/scripts/gds/update-channel.js

@@ -28,6 +28,7 @@ const { spawnSync } = require('node:child_process');
 const CORE_PKG = '@bongos/core';
 const VALID_CHANNELS = ['pinned', 'patch', 'minor'];
 const DEFAULT_CHANNEL = 'patch';
+const NPM_VIEW_TIMEOUT_MS = 30000;
 // The subscription manifest an operator edits to opt instances in. Ships EMPTY (instances: []) in the
 // core template — a fresh instance subscribes nothing until the operator lists a target here.
 const SUBSCRIPTIONS_REL = path.join('config', 'update-subscriptions.json');
@@ -55,8 +56,10 @@ const DEFAULT_STALENESS_THRESHOLD = 5;
 
 // Parse "1.17.2" / "v1.17.2" / "1.17.2-rc.1" → { major, minor, patch, pre } or null. `pre` is the
 // prerelease tag ('' for a plain stable release), used only to EXCLUDE prereleases from auto-targets.
+// `+build` metadata parses and is dropped: semver gives it no precedence, and npm installs the
+// version underneath it, so a caller asking "is this older?" must see through it (task 1004009).
 function parseSemver(v) {
-  const m = String(v == null ? '' : v).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  const m = String(v == null ? '' : v).trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/);
   if (!m) return null;
   return { major: +m[1], minor: +m[2], patch: +m[3], pre: m[4] || '' };
 }
@@ -78,11 +81,27 @@ function compareSemver(a, b) {
   for (const k of ['major', 'minor', 'patch']) {
     if (pa[k] !== pb[k]) return pa[k] < pb[k] ? -1 : 1;
   }
-  // Same x.y.z: a prerelease is LOWER than the stable release. (Two prereleases: not ordered
-  // precisely here — we never auto-target a prerelease, so their relative order is immaterial.)
+  // Same x.y.z: a prerelease is LOWER than the stable release.
   if (pa.pre && !pb.pre) return -1;
   if (!pa.pre && pb.pre) return 1;
-  return 0;
+  return comparePrerelease(pa.pre, pb.pre);
+}
+
+// Semver §11.4 for two prerelease tags: dot-separated identifiers left to right, numeric ones as
+// numbers and below text ones, and the longer list wins a tie. Auto-targeting never needed this
+// (a prerelease is never a target); `bongos upgrade`'s downgrade guard does — rc.2 → rc.1 is one.
+function comparePrerelease(a, b) {
+  const ia = a ? a.split('.') : [];
+  const ib = b ? b.split('.') : [];
+  for (let i = 0; i < Math.min(ia.length, ib.length); i++) {
+    if (ia[i] === ib[i]) continue;
+    const na = /^\d+$/.test(ia[i]);
+    const nb = /^\d+$/.test(ib[i]);
+    if (na && nb) return +ia[i] < +ib[i] ? -1 : 1;
+    if (na !== nb) return na ? -1 : 1;
+    return ia[i] < ib[i] ? -1 : 1;
+  }
+  return Math.sign(ia.length - ib.length);
 }
 
 function normalizeChannel(channel) {
@@ -126,11 +145,12 @@ function resolveChannelTarget({ installed, channel, available } = {}) {
 // The package is public (task 1003872), so this needs no credential and no instance-local
 // `.npmrc` — any cwd resolves it. Fail-SOFT: any error returns
 // { ok:false } so the routine skips that instance rather than crashing the whole sweep. `run` +
-// `pkg` are injectable for tests.
-function listAvailableVersions({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env } = {}) {
+// `pkg` are injectable for tests. The timeout is a DEFAULT, not an opt-in: a hung registry read
+// would otherwise stall a whole sweep, or an upgrade refusal that only wanted to name a version.
+function listAvailableVersions({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
   let res;
   try {
-    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8' });
+    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs });
   } catch (e) {
     return { ok: false, error: e && e.message ? e.message : String(e), versions: [] };
   }

package/scripts/gds/upgrade.js

@@ -32,6 +32,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
+const { parseSemver, compareSemver, isStable, listAvailableVersions } = require('./update-channel');
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -202,7 +203,7 @@ function dirtyPinFiles(instanceDir, run = spawnSync) { return dirtyPaths(instanc
 
 // The GitHub owner/name behind `remote`, or null when the remote is not a GitHub
 // repository (there is nothing to push a GitHub token at) or cannot be read. Accepts
-// the plain github.com forms and the shared SSH alias instanceRepoRemote wires
+// the plain github.com forms and every SSH alias instanceRepoRemotes wires
 // (`git@github-deploy:owner/repo.git`) — never another host, so a stored token is
 // never pointed at github.com/<owner>/<repo> for a repo that lives elsewhere.
 function remoteGithubRepo(instanceDir, remote = 'origin', run = spawnSync) {
@@ -214,7 +215,7 @@ function remoteGithubRepo(instanceDir, remote = 'origin', run = spawnSync) {
   const repo = auth.parseTargetRef(url);
   if (!repo) return null;
   const host = (url.match(/^(?:[a-z+]+:\/\/)?(?:[^@/]+@)?([^/:]+)[/:]/i) || [])[1] || '';
-  if (host.toLowerCase() !== 'github.com' && url !== auth.instanceRepoRemote(repo)) return null;
+  if (host.toLowerCase() !== 'github.com' && !auth.instanceRepoRemotes(repo).includes(url)) return null;
   return repo;
 }
 
@@ -1093,9 +1094,19 @@ async function runUpgrade(opts, deps = {}) {
   let snapshot = null;
   if (!targetVersion) return { ok: false, error: 'missing --to <version> (the target core version)' };
 
-  const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || readPinnedCoreVersion(instanceDir, fsImpl);
+  const pinnedVersion = readPinnedCoreVersion(instanceDir, fsImpl);
+  const fromVersion = readInstalledCoreVersion(instanceDir, fsImpl) || pinnedVersion;
   const doRollback = (reason) => rollback({ instanceDir, snapshot, fromVersion, toVersion: targetVersion, opts }, reason, deps);
-  log(`bongos upgrade — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
+  // A --to OLDER than this instance's core is refused before anything moves, --force included
+  // (task 1004009). Measured against the NEWER of installed and pinned — a half-applied bump
+  // leaves them apart. rollback() restores its own pin and never comes through here.
+  const baseline = compareSemver(pinnedVersion, fromVersion) > 0 ? pinnedVersion : fromVersion;
+  const isDowngrade = !!(parseSemver(baseline) && parseSemver(targetVersion) && compareSemver(targetVersion, baseline) < 0);
+  if (isDowngrade && !opts.allowDowngrade) {
+    const newest = listAvailableVersions({ cwd: instanceDir, run }).versions.filter(isStable).sort(compareSemver).pop();
+    return { ok: false, downgrade: true, fromVersion, toVersion: targetVersion, error: `refusing to DOWNGRADE: --to ${targetVersion} is older than this instance's core ${baseline}${pinnedVersion && pinnedVersion !== fromVersion ? ` (installed ${fromVersion}, pinned ${pinnedVersion})` : ''}; newest published: ${newest || 'unknown — the registry could not be read'}. Re-read the live version and target that; pass --allow-downgrade only if going backwards is the point (migrations are not reverted).` };
+  }
+  log(`bongos ${isDowngrade ? 'DOWNGRADE (--allow-downgrade; migrations are NOT reverted)' : 'upgrade'} — ${CORE_PKG}: ${fromVersion || '(none)'} → ${targetVersion}`);
   log(`  instance: ${instanceDir}${dryRun ? '   [DRY RUN — no changes]' : ''}`);
   if (fromVersion === targetVersion && !opts.force) {
     return { ok: false, error: `already on ${targetVersion} (pass --force to re-run the steps anyway)`, fromVersion };
@@ -1350,7 +1361,7 @@ async function runUpgrade(opts, deps = {}) {
     return { ok: false, error: `${why} — rolled back to ${snapshot.prevVersion || 'the previous core'}`, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, rolledBack: true, rollback: rb };
   }
 
-  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
+  const ledger = await recordLedger({ fromVersion, toVersion: targetVersion, sourceCommit: opts.sourceCommit, note: isDowngrade ? `downgrade (--allow-downgrade)${opts.note ? `: ${opts.note}` : ''}` : opts.note, requestedByBuilderId: opts.requestedBy, source: opts.upgradeSource }, deps);
   if (ledger.ok) log('  ✓ recorded in core_upgrades ledger');
   else if (ledger.skipped) log(`  • ledger skipped (${ledger.reason})`);
   else err(`  ! ledger insert failed (${ledger.reason}) — record it manually`);
@@ -1383,7 +1394,7 @@ async function runUpgrade(opts, deps = {}) {
   }, run, log, err);
 
   const ok = versionOk && healthOk !== false && servedOk !== false;
-  log(ok ? `\n✓ upgrade complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! upgrade finished with warnings — review above.`);
+  log(ok ? `\n✓ ${isDowngrade ? 'downgrade' : 'upgrade'} complete — core ${fromVersion || '(none)'} → ${targetVersion}` : `\n! ${isDowngrade ? 'downgrade' : 'upgrade'} finished with warnings — review above.`);
   return { ok, fromVersion, toVersion: targetVersion, versionOk, healthOk, servedOk, servedVersion, ledger: ledger.ok, pin };
 }
 
@@ -1412,6 +1423,7 @@ function parseArgs(argv) {
     gitRemote: arg('--git-remote', argv),
     dryRun: hasFlag('--dry-run', argv),
     force: hasFlag('--force', argv),
+    allowDowngrade: hasFlag('--allow-downgrade', argv), // task 1004009: a --to older than the installed core is refused without it
     skipMigrate: hasFlag('--skip-migrate', argv),
     skipMaterialize: hasFlag('--skip-materialize', argv),
     skipRegenDocs: hasFlag('--skip-regen-docs', argv),
@@ -1449,7 +1461,8 @@ async function main(argv = process.argv.slice(2)) {
       '  --commit-pin         commit + push package.json/-lock so a pull-deploy reset cannot revert the bump. The push rides the instance owner\'s stored GitHub token when one is stored (a PRIVATE instance\'s origin is a read-only deploy key — ADR 0176), else the git remote (--git-remote <name>, default origin); a refused push is reported loudly with the fix',
       '  --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',
+      '  --force              skip the clean-tree + same-version guards (NOT the downgrade guard)',
+      '  --allow-downgrade    let --to be OLDER than the installed core. Refused otherwise: a stale --to silently takes merged work off a live instance, and migrations are never reverted, so the DB stays ahead of the code',
       '',
       'Full bump: pre-flight → bump pin → npm install → verify integrity pin → migrate → materialize .claude → regen API docs+client → restart → verify (health + served coreVersion).',
       'On a failure after the pin moves (install/pin-verify/migrate/restart/health/served-version), auto-rollback reverts the pin, reinstalls the previous core, restarts, and records a rolled_back ledger row (the DB is not rolled back — core migrations are additive).',

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