@bongos/core 1.21.124 → 1.21.126

package/modules/provisioning/routes/provisioning.js

@@ -67,10 +67,12 @@ const { callbackPage } = require('./callback-page'); const githubSetup = require
 const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo'); const birth = require('../birth');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
 const { settingsPush, failPushConflict } = require('../settings-push');   // a settings save's push + receipt, shared with routes/look.js (task 1004421)
+const { requireProjectOwner, projectActor, isProjectOwner } = require('../route-helpers');   // the owner-or-archon gate (task 1004159, ADR 0328)
 // the kernel ports this module provides (moved out at the size ratchet, task 1003578)
 const { registerProvisioningSeams } = require('../seams');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('provisioning');
+const loadInstance = (id) => provisioning.getInstanceById(pool, id);
 
 // How long a GitHub-App-Manifest `state` token is valid — the owner must click the
 // pre-filled link + approve on GitHub within this window (task 2080). Comfortably
@@ -634,27 +636,18 @@ module.exports = function provisioningRoutes() {
     }
   });
 
-  // Own-scoped with an Archon override: an owner manages their own project; an
-  // Archon may act on any (fleet support). 404 for everyone else — no existence
-  // leak. Guards the per-id read (the manage page, task 1003041) and both
-  // settings routes (task 1003040).
-  function instanceAccessDenied(inst, builder) {
-    if (!inst) return true;
-    if (builder.rank === 'archon') return false;
-    return String(inst.owner_builder_id) !== String(builder.id);
-  }
+  // Every own-scoped /provisioning/instances/:id route below mounts requireProjectOwner
+  // (../route-helpers.js): the owner, or an Archon on any project (fleet support), and the
+  // same 404 for everyone else — no existence leak. The row rides on req.project.
 
   // GET /provisioning/instances/:id — read one instance (the manage page's read).
   // rank: any authenticated builder (own resource; archon may read any — task
   // 1003041). 404 otherwise — does not leak another owner's instance existence.
-  router.get('/provisioning/instances/:id', auth.requireBuilder, async (req, res) => {
+  router.get('/provisioning/instances/:id', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) {
-        return res.fail('instance_not_found', 404);
-      }
+      const inst = req.project;
       // SELF-HEAL THE CATALOG PROJECTION (task 1003581). ADR 0246's projection is
       // write-triggered, so an instance older than it has no catalog row and its owner's
       // invites 404 until they happen to save something. This own-scoped read — the manage
@@ -730,7 +723,7 @@ module.exports = function provisioningRoutes() {
   // the answer moved moves back. Only null does it — an empty string or any other
   // value is still refused as off-vocabulary, and `detail: {}` still changes nothing,
   // because a form that collected no answers is not asking for any to be erased.
-  router.patch('/provisioning/instances/:id/detail', auth.requireBuilder, async (req, res) => {
+  router.patch('/provisioning/instances/:id/detail', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     if (validateOrRespond(req, res, {
@@ -757,9 +750,8 @@ module.exports = function provisioningRoutes() {
         message: 'The body carries nothing to change — send description, detail, modules, type, or any mix.' });
     }
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
-      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      const inst = req.project;
+      const actor = projectActor(req);
       // An empty description is CLEARING it, not a no-op string: normalize here so
       // the column never holds '' — a blank string would read as answered to a
       // `description IS NOT NULL` publish check and put an empty husk on the map.
@@ -810,7 +802,7 @@ module.exports = function provisioningRoutes() {
   // purpose: ranking builders is a directory read the pure engine may not run.
   // This is the resolution, and ADR 0251 is why it looks like this.
   //
-  // rank: any authenticated builder, own resource — `instanceAccessDenied`, the
+  // rank: any authenticated builder, own resource — `requireProjectOwner`, the
   // same gate and the same 404 as the manage read above. That is deliberate and
   // not a new authorization idea: REACHING this route IS the ownership answer
   // (ADR 0249 §4), so the surface never re-derives "is this theirs" and can never
@@ -821,12 +813,9 @@ module.exports = function provisioningRoutes() {
   // nobody on purpose (ADR 0239 §6), which is a different statement from an empty
   // list nobody filled — so that answer returns its own reason and never touches
   // the directory at all.
-  router.get('/provisioning/instances/:id/invite-suggestions', auth.requireBuilder, async (req, res) => {
-    const id = parseId(req, res);
-    if (!id) return;
+  router.get('/provisioning/instances/:id/invite-suggestions', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const inst = req.project;
 
       const detail = provisioning.projectDetail(inst) || {};
       const { invites } = recommendationsForDetails({ type: inst.type, ...detail });
@@ -862,18 +851,15 @@ module.exports = function provisioningRoutes() {
   // ── Per-project settings (task 1003040, goal 1000058) ─────────────────────
   // The foundation the manage-page wave hangs off: effective settings are the
   // DEFAULTS (today's behavior — public surfaces, apply-to-join) overlaid with
-  // the instance's stored keys. Access: instanceAccessDenied above (own-scoped,
+  // the instance's stored keys. Access: requireProjectOwner (own-scoped,
   // Archon override, 404 otherwise — no existence leak).
 
   // GET /provisioning/instances/:id/settings — read a project's effective
   // settings + the allowed values (so a form can render its choices).
   // rank: any authenticated builder (own resource; archon may read any).
-  router.get('/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;
+  router.get('/provisioning/instances/:id/settings', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const inst = req.project;
       // `planet` rides beside `settings` (task 1003347): the same row, read by a
       // different rule — no defaults, null = the platform's own pick.
       res.json({ ok: true, settings: provisioning.effectiveSettings(inst), planet: provisioning.planetChoice(inst),
@@ -902,7 +888,7 @@ module.exports = function provisioningRoutes() {
   // 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) => {
+  router.patch('/provisioning/instances/:id/settings', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     // The schema IS the vocabularies, not a copy of them (task 1003352): strict
@@ -927,11 +913,10 @@ module.exports = function provisioningRoutes() {
         message: `The body carries no settings to change — send any of: ${settingKeys.join(', ')}.` });
     }
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const inst = req.project;
       // The archon override carries WHICH archon (the force-teardown convention) on
       // both the event and the intent it may enqueue below.
-      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      const actor = projectActor(req);
       // A save that changes nothing writes nothing and restarts nothing — a
       // whole-form save or a retried request must not bounce a live project. The
       // one exception is the owner re-kick (the domain route's F19 shape): the same
@@ -983,32 +968,32 @@ module.exports = function provisioningRoutes() {
   });
 
   // POST /provisioning/instances/:id/teardown — request teardown of the caller's
-  // OWN instance. rank: any authenticated builder (own resource). Enqueues a
-  // 'teardown' intent; the runner executes it (web tier holds no tokens). 404 when
-  // the id isn't the caller's; 409 when the instance isn't in a teardownable state.
-  router.post('/provisioning/instances/:id/teardown', auth.requireBuilder, async (req, res) => {
+  // OWN instance. rank: any authenticated builder (own resource; archon may tear down
+  // any — the override is audited via the actor). Enqueues a 'teardown' intent; the
+  // runner executes it (web tier holds no tokens). 404 when the id isn't the caller's;
+  // 409 when the instance isn't in a teardownable state.
+  router.post('/provisioning/instances/:id/teardown', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
-        return res.fail('instance_not_found', 404);
-      }
+      const inst = req.project;
+      const actor = projectActor(req);
       if (refusedAsTornDown(inst, res)) return;
       // enqueueTeardown supersedes a stale pending provision intent and reports each
       // outcome distinctly, so "already queued" is only ever said when it is TRUE
       // (task 1002691 — the old blind enqueue lied here and the instance leaked).
-      const r = await provisioning.enqueueTeardown(pool, id, 'api:self');
+      const r = await provisioning.enqueueTeardown(pool, id, actor);
       if (r.conflict) {
         return res.fail('intent_conflict', { status: 409,
           message: `A '${r.intent.action}' run is currently ${r.intent.state} for this instance — the teardown could not be queued; retry in a moment.`,
           details: { action: r.intent.action, state: r.intent.state } });
       }
       if (r.created) {
+        const who = isProjectOwner(inst, req.builder) ? 'owner' : `archon ${req.builder.github_login || req.builder.id}`;
         await provisioning.recordEvent(pool, {
-          instanceId: id, ownerBuilderId: req.builder.id, event: 'teardown',
-          detail: r.superseded ? 'teardown requested by owner (superseded a stale provision intent)' : 'teardown requested by owner',
-          actor: 'api:self',
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'teardown',
+          detail: `teardown requested by ${who}${r.superseded ? ' (superseded a stale provision intent)' : ''}`,
+          actor,
         }).catch(() => {});
       }
       res.json({ ok: true, queued: r.created, action: 'teardown', status: inst.status, superseded: r.superseded,
@@ -1034,14 +1019,13 @@ module.exports = function provisioningRoutes() {
   // Every refusal names the action that IS available in that state rather than
   // hiding behind a code, and no branch promises a duration — a restart's downtime
   // is exactly what this route cannot know (the F16 rule, ADR 0190 §7).
-  router.post('/provisioning/instances/:id/restart', auth.requireBuilder, async (req, res) => {
+  router.post('/provisioning/instances/:id/restart', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (instanceAccessDenied(inst, req.builder)) return res.fail('instance_not_found', 404);
+      const inst = req.project;
       // The archon override carries WHICH archon (the force-teardown convention).
-      const actor = String(inst.owner_builder_id) === String(req.builder.id) ? 'api:self' : `api:archon:${req.builder.id}`;
+      const actor = projectActor(req);
       if (!provisioning.RESTART_FROM.has(inst.status)) {
         const offline = inst.status === 'torn_down' || inst.status === 'tearing_down';
         return res.fail('not_restartable', { status: 409, details: { status: inst.status }, message: offline
@@ -1086,8 +1070,9 @@ module.exports = function provisioningRoutes() {
   // (re)provision run wires the domain itself. A bring-your-own address may be
   // RE-POINTED (task 1003237, ADR 0200): the same guards the first attach applies
   // decide it, and the address it moved off is queued for release.
-  // Body: { domain (required) }.
-  router.post('/provisioning/instances/:id/domain', auth.requireBuilder, domainWriteRateLimit, async (req, res) => {
+  // Body: { domain (required) }. An archon may set any project's address; the
+  // override is audited via the actor.
+  router.post('/provisioning/instances/:id/domain', auth.requireBuilder, domainWriteRateLimit, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     if (validateOrRespond(req, res, { domain: { required: true, type: 'string', maxLength: 253 } })) return;
@@ -1104,10 +1089,8 @@ module.exports = function provisioningRoutes() {
           message: `${domain} is a platform-reserved address — bring a domain of your own instead.`,
         });
       }
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
-        return res.fail('instance_not_found', 404);
-      }
+      const inst = req.project;
+      const actor = projectActor(req);
       // Same rule as create: inside the platform apex the only address an instance
       // can hold is its own <slug>.<apex> — anything else is a squat (task 1002704).
       const apexZone = provisioning.normalizeHostname(instanceApex());
@@ -1129,11 +1112,11 @@ module.exports = function provisioningRoutes() {
         // idempotent no-op below.
         const needsRewire = provisioning.ownsErrorNote(inst, 'domain-attach') || inst.last_verified_up === false;
         if (inst.status === 'active' && needsRewire && !(await provisioning.getOpenIntent(pool, id))) {
-          const { created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', 'api:self');
+          const { created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', actor);
           if (created) {
             await provisioning.recordEvent(pool, {
-              instanceId: id, ownerBuilderId: req.builder.id, event: 'domain',
-              detail: `domain ${domain} re-attach queued (owner re-kick)`, actor: 'api:self',
+              instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'domain',
+              detail: `domain ${domain} re-attach queued (${isProjectOwner(inst, req.builder) ? 'owner' : 'archon'} re-kick)`, actor,
             }).catch(() => {});
           }
           // created:false = a racing enqueue got there first — still truthful.
@@ -1176,7 +1159,7 @@ module.exports = function provisioningRoutes() {
       await catalogBridge.publishInstanceToCatalog(pool, rewired, { retireOrigin: current }).catch(() => {});
       let queued = false;
       if (inst.status === 'active') {
-        const { intent, created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', 'api:self');
+        const { intent, created } = await provisioning.enqueueIntent(pool, id, 'domain-attach', actor);
         if (!created && intent.action !== 'domain-attach') {
           // The open slot is held by other work (e.g. a teardown). The address IS
           // recorded — say exactly what happened and what to do.
@@ -1188,8 +1171,8 @@ module.exports = function provisioningRoutes() {
         if (!created) {
           // an identical attach is already open — idempotent
           await provisioning.recordEvent(pool, {
-            instanceId: id, ownerBuilderId: req.builder.id, event: 'domain',
-            detail: `domain ${domain} recorded (attach already queued)`, actor: 'api:self',
+            instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'domain',
+            detail: `domain ${domain} recorded (attach already queued)`, actor,
           }).catch(() => {});
           return res.json({ ok: true, changed: true, queued: false, domain, replaced: releasing,
             message: 'That address is already being wired for this instance.' });
@@ -1197,9 +1180,9 @@ module.exports = function provisioningRoutes() {
       }
       const moved = releasing ? ` (moved off ${releasing}, queued for release)` : '';
       await provisioning.recordEvent(pool, {
-        instanceId: id, ownerBuilderId: req.builder.id, event: 'domain',
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'domain',
         detail: (queued ? `domain ${domain} recorded + attach queued` : `domain ${domain} recorded (wired at provision)`) + moved,
-        actor: 'api:self',
+        actor,
       }).catch(() => {});
       // State-only sentences (task 1002720 / F16): the web tier holds no cloud
       // tokens and cannot know whether a DNS hook exists on the runner, so "it
@@ -1225,7 +1208,7 @@ module.exports = function provisioningRoutes() {
 
   // POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding
   // link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated
-  // builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target
+  // builder (own resource; archon may mint for any — audited via the actor). Returns the pre-filled manifest + the GitHub form-POST target
   // (personal + org variants) + a one-time `state`; the browser POSTs the manifest to
   // GitHub, the owner approves, and GitHub redirects back to the public callback below.
   // The web tier only RECORDS the attempt (state token) — the control-plane runner does
@@ -1237,7 +1220,7 @@ module.exports = function provisioningRoutes() {
   // whether the founder may make an app there is GitHub's to enforce on its own page
   // (this module holds no GitHub token to ask with, ADR 0111 §2). Anything other than
   // account 'org' is the founder's personal account, exactly as before.
-  router.post('/provisioning/instances/:id/github-app', auth.requireBuilder, async (req, res) => {
+  router.post('/provisioning/instances/:id/github-app', auth.requireBuilder, requireProjectOwner(loadInstance), async (req, res) => {
     const id = parseId(req, res); // (req, res) — parseId sends 400 bad_id + returns null on failure
     if (!id) return;
     if (validateOrRespond(req, res, { account: { type: 'string', maxLength: 12 }, org: { type: 'string', maxLength: 39 } })) return;
@@ -1247,10 +1230,8 @@ module.exports = function provisioningRoutes() {
       return res.fail('bad_org', { status: 400, message: 'That isn’t a GitHub organisation name: letters, numbers and single dashes, up to 39.' });
     }
     try {
-      const inst = await provisioning.getInstanceById(pool, id);
-      if (!inst || String(inst.owner_builder_id) !== String(req.builder.id)) {
-        return res.fail('instance_not_found', 404);
-      }
+      const inst = req.project;
+      const actor = projectActor(req);
       // A domain is required: it is the App's homepage + the sign-in callback host. No
       // domain ⇒ there is nothing to point "Login with GitHub" at yet.
       if (!inst.domain) {
@@ -1274,17 +1255,19 @@ module.exports = function provisioningRoutes() {
       if (guard && guard.refuse) return res.fail(guard.refuse, { status: 409, message: guard.message });
       const state = guard ? guard.reuse : crypto.randomBytes(32).toString('hex');
       const expiresAt = guard ? guard.expiresAt : new Date(Date.now() + MANIFEST_STATE_TTL_MS).toISOString();
-      if (!guard) await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: req.builder.id, expiresAt });
+      // requested_by is read downstream as the project's owner (every later manifest event's
+      // ownerBuilderId); an archon's mint is named by the actor on the event below instead
+      if (!guard) await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: inst.owner_builder_id, expiresAt });
       await provisioning.recordEvent(pool, {
-        instanceId: id, ownerBuilderId: req.builder.id, event: 'oauth-manifest-start',
-        detail: guard ? 'GitHub App Manifest link reopened (same attempt)' : 'GitHub App Manifest link minted', actor: 'api:self',
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'oauth-manifest-start',
+        detail: guard ? 'GitHub App Manifest link reopened (same attempt)' : 'GitHub App Manifest link minted', actor,
       }).catch(() => {});
       // which account owns this attempt's app, so the page can link its settings there
       // from any tab or device (github-setup.js reads it back as app_org)
       if (account === 'org') {
         await provisioning.recordEvent(pool, {
-          instanceId: id, ownerBuilderId: req.builder.id, event: githubSetup.SETUP_EVENTS.appOrg,
-          detail: orgLogin, actor: 'api:self',
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: githubSetup.SETUP_EVENTS.appOrg,
+          detail: orgLogin, actor,
         }).catch(() => {});
       }
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.124",
+  "version": "1.21.126",
   "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/release-notes.json

@@ -9726,5 +9726,29 @@
       "id": "1004633",
       "text": "Found why a merged task on your own project stayed at 'confirmed': with no GitHub key set up on the project's server, Bongos could not prove the merge happened, and its background checker switched itself off. It now confirms t"
     }
+  ],
+  "1.21.125": [
+    {
+      "id": "1004460",
+      "text": "Store modules' own tests can now run on GitHub's free test machines, away from the server holding our secrets. It switches on once the owner does three short GitHub setup steps."
+    },
+    {
+      "id": "1004159",
+      "text": "Project owners' controls now share one access check, and Archons can help with teardown, address and GitHub setup on any project — every such action is logged under the Archon's name."
+    },
+    {
+      "id": "1004632",
+      "text": "When a project updates its Bongos core, the next task's ship now uses the new core automatically instead of the old one, so it no longer fails for no visible reason."
+    },
+    {
+      "id": "1004627",
+      "text": "Bongos now has a 27-step plain-language how-to guide that an AI can walk a new person through inside their session, from where to start to their first ship."
+    }
+  ],
+  "1.21.126": [
+    {
+      "id": "1004738",
+      "text": "A goal's page is much shorter now: task dependencies sit in a small card at the top where Conflicts used to be, and the full dependency picture and conflict list are one click away."
+    }
   ]
 }

package/scripts/gds/core-pin-sync.js

@@ -0,0 +1,233 @@
+// scripts/gds/core-pin-sync.js — make `bongos ship` run the core the checkout PINS (task 1004632)
+//
+// WHY. An instance's task worktrees (`.claude/worktrees/task-N`) have no `node_modules`
+// of their own: Node and `npx` walk up to the MAIN checkout's, and so does every
+// `bongos ship`. After a core-update task lands, the next task's branch pins the new
+// core in package.json — but its worktree still resolves the main checkout's install,
+// which is whatever version was there before. On the owner's project that meant a
+// ship ran 1.21.20 against a branch pinned to 1.21.71 and failed on a bug 1.21.71 had
+// already fixed; the AI had to `npm ci` by hand in both places.
+//
+// THE FIX. Before `bongos ship` runs, the dispatcher asks `planCoreSync()` whether the
+// core it is running is the one the checkout it stands in pins. When it is not, it
+// installs the pinned core INTO that checkout (`npm ci`, or `npm install` with no
+// lockfile) and re-runs the same command under it. A worktree that gets its own
+// install keeps resolving it from then on. If the install fails, the builder gets one
+// line that names the command to run — never a silent run on the wrong core. Only
+// `ship` checks: it is the verb that runs the core's land/smoke code against the
+// branch, and it is slow anyway — the many quick verbs (status, recall, exec) pay no
+// git spawn for it.
+//
+// Safety. The pin comes from the branch, and installing it then RUNS it — so a branch
+// must never be able to choose what gets installed. Two gates, both required:
+//   1. the spec is a shape the core itself writes — a vendored
+//      `file:vendor/bongos-core-<v>.tgz` or an exact registry semver;
+//   2. the pin has already LANDED: package.json, package-lock.json and the vendored
+//      tarball in this checkout are byte-identical (same git blob, no local edits) to
+//      the ones on `main` / `origin/main`. That is exactly the case this fixes — a
+//      core update merged, the next task's branch carries it — and a branch that pins
+//      something main does not get the remedy line, never an automatic install.
+// The install also runs with `--ignore-scripts` (the core's dependencies need no
+// install hook), through npm's own JS entry under this node where it can be found, so
+// no shell is involved; only a Windows box without it falls back to `npm.cmd` + shell,
+// with fixed arguments. A `node_modules` that
+// is a LINK (the junction worktree.js gives an outside-repo worktree) is unlinked
+// first — installing through it would rewrite the MAIN checkout's install. It is never
+// followed and a real directory is never removed. The re-run sets BONGOS_CORE_SYNCED
+// so a pin the install still cannot satisfy cannot loop.
+//
+// It does nothing in the core repo itself (the running package is not `@bongos/core`),
+// outside git, or when the checkout pins no core. Pure planner + injectable runner, so
+// tests/core_pin_sync.mjs drives every branch without npm or a network.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const CORE_PKG = '@bongos/core';
+const SYNCED_ENV = 'BONGOS_CORE_SYNCED';
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(String(fsImpl.readFileSync(file, 'utf8')).replace(/^/, '')); } catch { return null; }
+}
+
+// { version, safe } for a dependency spec. `version` reads the same shapes upgrade.js
+// does (kept local so the dispatcher never loads upgrade.js's tree); `safe` is true
+// only for the two shapes the core writes itself — a tarball under vendor/ named for
+// its version, or an EXACT registry semver.
+function parseSpec(spec) {
+  const s = String(spec || '').trim();
+  const tgz = s.match(/bongos-core-(\d+\.\d+\.\d+[^/\\]*)\.tgz$/);
+  if (tgz) return { version: tgz[1], safe: /^file:(\.\/)?vendor\/bongos-core-[^/\\]+\.tgz$/.test(s) };
+  if (/^file:/.test(s)) return { version: null, safe: false };
+  const sem = s.match(/^[\^~>=<\s]*v?(\d+\.\d+\.\d+[A-Za-z0-9.+-]*)$/);
+  if (!sem) return { version: null, safe: false };
+  return { version: sem[1], safe: /^\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$/.test(s) };
+}
+
+function versionFromSpec(spec) { return parseSpec(spec).version; }
+
+function coreSpec(root, fsImpl = fs) {
+  const pkg = readJson(path.join(root, 'package.json'), fsImpl);
+  return pkg ? ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG] || null) : null;
+}
+
+// What the checkout at `root` pins: the lockfile's resolved version first (exact), then
+// the package.json spec.
+function pinnedCoreVersion(root, fsImpl = fs) {
+  const lock = readJson(path.join(root, 'package-lock.json'), fsImpl);
+  const locked = lock && lock.packages && lock.packages[`node_modules/${CORE_PKG}`];
+  if (locked && locked.version) return locked.version;
+  return versionFromSpec(coreSpec(root, fsImpl));
+}
+
+// The refs that count as LANDED for gate 2: a pin is trusted only once it is on one of them.
+const LANDED_REFS = ['main', 'origin/main'];
+
+function gitOut(args, cwd, run) {
+  try {
+    const r = run('git', args, { cwd, encoding: 'utf8' });
+    return r && r.status === 0 ? String(r.stdout || '').trim() : null;
+  } catch { return null; }
+}
+
+// Gate 2: every file that decides what `npm ci` installs — package.json, the lockfile,
+// the project .npmrc (it can redirect the registry), and the vendored tarball the spec
+// names — is in the SAME state as on a landed ref: the same blob as it sits on disk (so
+// an uncommitted edit counts), or absent on both. Deleting a file the landed ref has
+// is a difference too. True when one landed ref matches all of them. The lockfile is
+// also required outright: the install is `npm ci`, whose integrity check is the point.
+const PIN_FILES = ['package.json', 'package-lock.json', '.npmrc'];
+
+function pinLanded(root, { run = spawnSync, fsImpl = fs } = {}) {
+  if (!fsImpl.existsSync(path.join(root, 'package-lock.json'))) return false;
+  const spec = coreSpec(root, fsImpl);
+  const files = [...PIN_FILES];
+  const vendored = String(spec || '').match(/^file:(?:\.\/)?(vendor\/bongos-core-[^/\\]+\.tgz)$/);
+  if (vendored) files.push(vendored[1]);
+  const local = files.map((f) => (fsImpl.existsSync(path.join(root, f)) ? (gitOut(['hash-object', '--', f], root, run) || 'unreadable') : null));
+  return LANDED_REFS.some((ref) => files.every((f, i) => gitOut(['rev-parse', '--verify', '--quiet', `${ref}:${f}`], root, run) === local[i]));
+}
+
+function gitTopLevel(cwd, run = spawnSync) {
+  try {
+    const r = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const top = String(r.stdout || '').trim();
+    return top ? path.resolve(top) : null;
+  } catch { return null; }
+}
+
+// Pure decision. Inputs are facts; output says whether to sync and why.
+//   runningPkg   the running core's package.json ({ name, version })
+//   root         the git top-level of the cwd (null outside git)
+//   pinned       what that checkout pins (null when it pins no core)
+//   specSafe     gate 1: the spec is a shape the core writes itself (parseSpec)
+//   landed       gate 2: the pin is byte-identical to a landed ref's (pinLanded)
+//   env          process env (the re-run guard)
+function planCoreSync({ runningPkg, root, pinned, specSafe = false, landed = false, env = process.env }) {
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return { action: 'none', reason: 'not-installed-core' };
+  if (!root) return { action: 'none', reason: 'no-git' };
+  if (!pinned) return { action: 'none', reason: 'no-pin' };
+  const running = runningPkg.version || null;
+  if (running === pinned) return { action: 'none', reason: 'in-sync', running, pinned };
+  if (env && env[SYNCED_ENV]) return { action: 'refuse', reason: 'still-mismatched', running, pinned, root };
+  if (!specSafe) return { action: 'refuse', reason: 'unrecognised-spec', running, pinned, root };
+  if (!landed) return { action: 'refuse', reason: 'pin-not-landed', running, pinned, root };
+  return { action: 'sync', reason: 'mismatch', running, pinned, root };
+}
+
+function installArgs(hasLock) {
+  return [hasLock ? 'ci' : 'install', '--ignore-scripts', '--no-audit', '--no-fund'];
+}
+
+// npm's own JS entry beside this node (Windows: <dir>/node_modules/npm; POSIX:
+// <prefix>/lib/node_modules/npm), so the install needs no shell. null when absent.
+function npmCliPath(execPath = process.execPath, fsImpl = fs) {
+  const dir = path.dirname(execPath);
+  const candidates = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  return candidates.find((c) => fsImpl.existsSync(c)) || null;
+}
+
+function remedyLine({ root, pinned, running, hasLock = true }) {
+  return `bongos: this checkout pins core ${pinned} but ${running || 'another version'} is running. ` +
+    `Run \`npm ${hasLock ? 'ci' : 'install'}\` in ${root}, then run the command again.`;
+}
+
+// Remove a node_modules LINK without following it — the same move as worktree.js's
+// unlinkNodeModulesLink, kept here rather than required: bin/bongos.js is in the
+// executed closure (tests/executed_closure.mjs), and worktree.js would pull its
+// computed require in with it. unlink takes a symlink and (via libuv) a junction; a
+// Windows reparse point unlink refuses falls back to rmdir, which removes the link only.
+function unlinkLink(linkPath, { platform = process.platform, fsImpl = fs } = {}) {
+  if (!fsImpl.lstatSync(linkPath).isSymbolicLink()) throw new Error(`${linkPath} is not a link`);
+  try { fsImpl.unlinkSync(linkPath); } catch (e) {
+    if (platform !== 'win32' || (e.code !== 'EPERM' && e.code !== 'EISDIR')) throw e;
+    fsImpl.rmdirSync(linkPath);
+  }
+}
+
+// Install the pinned core into `root` and re-run the same bongos command under it.
+// Returns the exit code to use.
+function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), env = process.env, platform = process.platform, npmCli = npmCliPath(process.execPath, fsImpl) } = {}) {
+  const { root, pinned, running } = plan;
+  const hasLock = fsImpl.existsSync(path.join(root, 'package-lock.json'));
+  const remedy = () => log(remedyLine({ root, pinned, running, hasLock }));
+  log(`bongos: this checkout pins core ${pinned}, but ${running} is running — installing ${pinned} here first.`);
+  const nm = path.join(root, 'node_modules');
+  let st = null;
+  try { st = fsImpl.lstatSync(nm); } catch { /* absent */ }
+  if (st && st.isSymbolicLink()) {
+    try { unlinkLink(nm, { platform, fsImpl }); } catch (e) {
+      log(`bongos: could not detach the shared node_modules link (${e.message}).`);
+      remedy();
+      return 1;
+    }
+  }
+  // npm's JS entry under this node — no shell. Fallback: `npm`, which on win32 is
+  // npm.cmd and needs a shell (Node refuses a .cmd without one); the args are fixed
+  // strings, never branch data.
+  const cli = npmCli;
+  const inst = cli
+    ? run(process.execPath, [cli, ...installArgs(hasLock)], { cwd: root, stdio: 'inherit', env })
+    : run('npm', installArgs(hasLock), { cwd: root, stdio: 'inherit', env, ...(platform === 'win32' ? { shell: true } : {}) });
+  if (!inst || inst.error || inst.status !== 0) {
+    log(`bongos: installing core ${pinned} failed.`);
+    remedy();
+    return 1;
+  }
+  const bin = path.join(nm, '@bongos', 'core', 'bin', 'bongos.js');
+  if (!fsImpl.existsSync(bin)) { remedy(); return 1; }
+  const res = run(process.execPath, [bin, ...argv.slice(2)], { stdio: 'inherit', env: { ...env, [SYNCED_ENV]: '1' } });
+  if (!res || res.error) return 1;
+  return res.status == null ? 1 : res.status;
+}
+
+// The dispatcher's one call. Returns an exit code when it handled the command (synced
+// and re-ran, or refused), or null to run the verb on the current core.
+function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log } = {}) {
+  if (env && env.BONGOS_SKIP_CORE_SYNC) return null;
+  const runningPkg = readJson(path.join(coreRoot, 'package.json'), fsImpl);
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return null; // fast path: the core repo itself
+  const root = gitTopLevel(cwd, run);
+  const pinned = root ? pinnedCoreVersion(root, fsImpl) : null;
+  const specSafe = root ? parseSpec(coreSpec(root, fsImpl)).safe : false;
+  const out = { runningPkg, root, pinned, specSafe, env };
+  // gate 2 costs git spawns — only pay it when there is a mismatch to act on
+  const pre = planCoreSync({ ...out, landed: true });
+  const plan = pre.action === 'sync' ? planCoreSync({ ...out, landed: pinLanded(root, { run, fsImpl }) }) : pre;
+  if (plan.action === 'none') return null;
+  const say = log || ((s) => process.stderr.write(s + '\n'));
+  if (plan.action === 'refuse') {
+    say(remedyLine({ ...plan, hasLock: fsImpl.existsSync(path.join(root, 'package-lock.json')) }));
+    return 1;
+  }
+  return syncAndRerun(plan, { argv, run, fsImpl, log: say, env });
+}
+
+module.exports = { CORE_PKG, SYNCED_ENV, LANDED_REFS, pinLanded, npmCliPath, parseSpec, versionFromSpec, installArgs, pinnedCoreVersion, planCoreSync, remedyLine, syncAndRerun, ensurePinnedCore };