@bongos/core 1.21.70 → 1.21.71

package/src/bongos/routes/core-update.js

@@ -33,6 +33,7 @@ const { readCoreUpdate, readCoreUpgrades } = require('../core-update');
 const { readSoftwareUpdate } = require('../software-update');
 const seams = require('../../module-seams');
 const { loadIdpConfig } = require('../auth-config');
+const upgradeRequest = require('../upgrade-request');
 
 // WHERE A HOSTED PROJECT'S OWNER TAKES THE UPGRADE (task 1004174, ADR 0339): the hub's
 // own deploy door, scoped to this project — `<hub>/deploy?project=<slug>`. The act stays
@@ -73,12 +74,22 @@ function hubManageLinks(config) {
 //   local — this hall runs the door: its own /deploy.
 //   hub   — a hosted project: the hub's door for this project (ADR 0339 D3).
 //   cli   — neither: a self-hosted instance, upgraded on its server with `bongos upgrade`.
-function updateDoor({ provisioning, idp }) {
+// A hosted project that does not federate its sign-in (a cloud-host, or one keeping its own
+// GitHub app) has no idp config to derive the hub from, so provisioning writes the door's
+// address as <PREFIX>_HUB_UPGRADE_URL (task 1004608). Without it, those owners were told to
+// run `bongos upgrade` on a server the platform runs. Only the hub's /deploy path is taken.
+const HUB_UPGRADE_URL_RE = /^https?:\/\/[^\s"'<>/]+\/deploy\?project=[A-Za-z0-9._%-]+$/;
+function updateDoor({ provisioning, idp, hubUpgradeUrl }) {
   if (provisioning) return { kind: 'local', url: '/deploy' };
-  const url = hubDeployUrl(idp);
+  const url = hubDeployUrl(idp)
+    || (typeof hubUpgradeUrl === 'string' && HUB_UPGRADE_URL_RE.test(hubUpgradeUrl.trim()) ? hubUpgradeUrl.trim() : null);
   return url ? { kind: 'hub', url } : { kind: 'cli', url: null };
 }
 
+function safeHubUpgradeUrl() {
+  try { return require('../../instance-config').resolveEnv('HUB_UPGRADE_URL') || null; } catch { return null; }
+}
+
 function provisioningEnabled() {
   try { return require('../../modules').isModuleEnabled('provisioning'); } catch { return false; }
 }
@@ -164,16 +175,57 @@ async function resolveChannel(selfChannel) {
   return { channel, source: channel ? 'deploy' : 'default' };
 }
 
+// "Ask for this upgrade" (task 1004595): what src/bongos/upgrade-request.js needs from
+// the outside world, resolved per request so a test can stand every piece in. The receipt
+// goes into the SAME store the public redeem route reads (routes/feedback.js).
+function defaultAskDeps() {
+  const ps = require('../project-settings');
+  const fb = require('./feedback');
+  return {
+    hub: fb.feedbackHub(),
+    host: configuredHost(),
+    getSetting: ps.getSetting,
+    setSetting: ps.setSetting,
+    issueReceipt: (r) => fb.defaultReceiptStore().issue(r),
+  };
+}
+
+// The host this project answers on, from its OWN branding pack (domains is server-only):
+// the origin the hub calls back to redeem the receipt. Never read from the request: a
+// Host or X-Forwarded-Host header is the caller's to write, and would let them point the
+// hub's call-back at any address they like. '' when the pack names none.
+function configuredHost() {
+  try {
+    const d = require('../../branding').branding().domains || {};
+    return new URL(d.publicOrigin || d.buildersOrigin).host;
+  } catch { return ''; }
+}
+
+// The page's ask state. Fail-soft: a stored row that cannot be read is "not asked yet",
+// never a 500 on the whole Software update panel.
+async function readAsk({ update, door, deps }) {
+  const offered = update && update.reading === 'ok' ? update.offered : null;
+  const base = { offered, host: upgradeRequest.projectHost(deps.host), doorKind: door.kind, hub: deps.hub };
+  let stored = null;
+  if (offered && upgradeRequest.isOperatorRun(base)) {
+    try { stored = upgradeRequest.parseStored(await deps.getSetting(upgradeRequest.SETTING_KEY)); } catch { stored = null; }
+  }
+  return upgradeRequest.askState({ ...base, stored });
+}
+
 function buildCoreUpdateRouter({
   coreUpdate = readCoreUpdate,
   selfChannel = storedSelfChannel,
   upgrades = readCoreUpgrades,
   softwareUpdate = readSoftwareUpdate,
   canUpdate = holdsCorePin,
-  doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig() }),
+  doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig(), hubUpgradeUrl: safeHubUpgradeUrl() }),
+  askDeps = defaultAskDeps,
 } = {}) {
   contributeCoreUpdateToDocket();
   const router = express.Router();
+  // One send at a time: a double press waits for the first and is answered from its row.
+  let asking = null;
 
   router.get(
     '/core-update',
@@ -229,10 +281,51 @@ function buildCoreUpdateRouter({
         resolveChannel(selfChannel).then(async ({ channel, source }) => ({ ...(await softwareUpdate({ running, channel })), channel_source: source })),
         canUpdate(req),
       ]);
-      res.json({ ok: true, update, door: updateDoor(doorInputs()), can_update: can === true });
+      const door = updateDoor(doorInputs());
+      const ask = await readAsk({ update, door, deps: askDeps() });
+      res.json({ ok: true, update, door, can_update: can === true, ask });
     }, { errorCode: 'software_update_failed', message: false }),
   );
 
+  // POST /software-update/request — "Ask for this upgrade" (task 1004595). On a project
+  // the hub's operator runs, sends one request for the version this project is offered
+  // to the operator, through the direct feedback door, and remembers it so the page can
+  // say it is pending. The version is the server's own reading, never the caller's.
+  // Idempotent per version; a different version waits out a 24h cooldown (429).
+  // rank: core.pin.move — the same atom as the Update button the panel draws.
+  router.post(
+    '/software-update/request',
+    auth.requireBuilder,
+    auth.requirePermission('core.pin.move'),
+    asyncHandler('POST /software-update/request', async (req, res) => {
+      while (asking) { try { await asking; } catch { /* the next one tries for itself */ } }
+      const run = (async () => {
+        let running = null;
+        try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
+        const { channel } = await resolveChannel(selfChannel);
+        const update = await softwareUpdate({ running, channel });
+        const door = updateDoor(doorInputs());
+        const deps = askDeps();
+        return upgradeRequest.requestUpgrade({
+          host: deps.host,
+          running,
+          wanted: update && update.reading === 'ok' ? update.offered : null,
+          builder: req.builder,
+          doorKind: door.kind,
+        }, deps);
+      })();
+      asking = run;
+      let out;
+      try { out = await run; } finally { if (asking === run) asking = null; }
+      if (out.status >= 400) {
+        const { error, message, ...details } = out.body;
+        if (details.retry_after_seconds) res.set('Retry-After', String(details.retry_after_seconds));
+        return res.fail(error, { status: out.status, message, details });
+      }
+      res.status(out.status).json(out.body);
+    }, { errorCode: 'upgrade_request_failed', message: false }),
+  );
+
   // GET /project/manage-link — the hub's page for THIS project, where its owner takes it
   // offline or disconnects it (task 1004570). On a hosted project the owner is its Archon,
   // so the read is Archon-only: a builder below that is refused and the hall draws no
@@ -254,4 +347,5 @@ function buildCoreUpdateRouter({
 module.exports = buildCoreUpdateRouter;
 module.exports.hubManageLinks = hubManageLinks;
 module.exports.hubDeployUrl = hubDeployUrl;
+module.exports.updateDoor = updateDoor;
 module.exports.coreUpdateDocketMatters = coreUpdateDocketMatters;

package/src/bongos/routes/feedback.js

@@ -77,7 +77,16 @@ function makeReceiptStore({ now = Date.now, ttlMs = RECEIPT_TTL_MS, max = RECEIP
   };
 }
 
-function buildFeedbackRouter({ store = makeReceiptStore(), hub = feedbackHub } = {}) {
+// The process's one receipt store. Shared, because a receipt is redeemed at the public
+// route below whoever issued it: the CLI's POST /feedback/receipt, or this project's own
+// "Ask for this upgrade" (src/bongos/upgrade-request.js, task 1004595).
+let sharedStore = null;
+function defaultReceiptStore() {
+  if (!sharedStore) sharedStore = makeReceiptStore();
+  return sharedStore;
+}
+
+function buildFeedbackRouter({ store = defaultReceiptStore(), hub = feedbackHub } = {}) {
   const router = express.Router();
 
   // rank: any signed-in builder — a receipt only says "this builder sent this
@@ -120,5 +129,6 @@ function buildFeedbackRouter({ store = makeReceiptStore(), hub = feedbackHub } =
 
 module.exports = buildFeedbackRouter;
 module.exports.makeReceiptStore = makeReceiptStore;
+module.exports.defaultReceiptStore = defaultReceiptStore;
 module.exports.feedbackHub = feedbackHub;
 module.exports.DEFAULT_FEEDBACK_HUB = DEFAULT_FEEDBACK_HUB;

package/src/bongos/upgrade-request.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// src/bongos/upgrade-request.js — "Ask for this upgrade" on Settings → Software update
+// (task 1004595).
+//
+// WHY. A project that Cloud Bongos hosts is upgraded by the people who run its server,
+// not by its owner. Its Settings page said "Update ready" and then nothing: no button,
+// no next step (Will, mercury, 2026-10-06, 46 versions behind with nobody told). This
+// file gives that owner one press that reaches the operator, and remembers that it was
+// pressed so the page can say the request is pending.
+//
+// THE CHANNEL IS ONE THAT ALREADY EXISTS: the direct feedback door (task 1004591). The
+// project issues a one-time receipt for the signed-in builder in its OWN receipt store
+// (src/bongos/routes/feedback.js), then posts the request straight to the hub's
+// POST /api/bongos/sso/feedback/direct. The hub redeems the receipt at this project's
+// public URL, so the request lands in the maintainers' backlog attributed to the person
+// who really pressed the button, with no new credential and no new hub route.
+//
+// ONE REQUEST PER TARGET VERSION. Asking again for a version already asked for is
+// answered from the stored row and sends nothing. A different version may be asked for
+// once the cooldown has passed, so a project that falls further behind can say so,
+// without a press per patch release flooding the backlog.
+
+const crypto = require('node:crypto');
+
+const SETTING_KEY = 'software_update.request';
+const COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const HUB_TIMEOUT_MS = 15000;
+
+const VERSION_RE = /^\d{1,4}\.\d{1,5}\.\d{1,6}$/;
+const LOGIN_RE = /^[A-Za-z0-9-]{1,39}$/;
+
+// The host this hall answers on, as the hub will need it to redeem the receipt: a bare
+// public DNS name. Anything else (an IP, a port, localhost, a dev name) cannot be
+// reached by the hub, so it is not askable. Mirrors the hub's own projectOrigin check.
+function projectHost(raw) {
+  const host = String(raw || '').trim().toLowerCase();
+  if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(host)) return null;
+  if (/^\d+(\.\d+)+$/.test(host)) return null;
+  if (/(^|\.)(localhost|local|internal|test|invalid)$/.test(host)) return null;
+  return host;
+}
+
+function hubHostOf(hub) {
+  try { return new URL(String(hub)).host.toLowerCase(); } catch { return null; }
+}
+
+// Is this a project the hub's operator runs? Its door is the hub's, or it answers on a
+// name under the hub's own domain (the same rule the hub uses to call a sender "verified").
+function isOperatorRun({ doorKind, host, hub }) {
+  if (doorKind === 'local' || !hub) return false;
+  if (doorKind === 'hub') return true;
+  const h = hubHostOf(hub);
+  return !!(h && host && (host === h || host.endsWith(`.${h}`)));
+}
+
+// The stored request, or null. A row this file did not write reads as no request.
+function parseStored(row) {
+  if (!row || typeof row.value !== 'string') return null;
+  let v;
+  try { v = JSON.parse(row.value); } catch { return null; }
+  if (!v || !VERSION_RE.test(String(v.version || ''))) return null;
+  const at = Date.parse(v.requested_at);
+  if (!Number.isFinite(at)) return null;
+  return {
+    version: String(v.version),
+    requested_at: new Date(at).toISOString(),
+    by: typeof v.by === 'string' && LOGIN_RE.test(v.by) ? v.by : null,
+  };
+}
+
+// What the page needs: may it offer the button, and what was asked before.
+// `ask_again_after` is when a request for a DIFFERENT version would be taken.
+function askState({ offered, host, doorKind, hub, stored }) {
+  const available = !!offered && isOperatorRun({ doorKind, host, hub }) && !!projectHost(host);
+  const ask = { available, hub_host: hub ? hubHostOf(hub) : null, requested: stored || null, ask_again_after: null };
+  if (stored) ask.ask_again_after = new Date(Date.parse(stored.requested_at) + COOLDOWN_MS).toISOString();
+  return ask;
+}
+
+// The text the operator reads. Its first line becomes the hub task's title.
+function requestMessage({ host, running, wanted, login }) {
+  const who = login && LOGIN_RE.test(login) ? `@${login}` : 'its owner';
+  return [
+    `Upgrade request: ${host} asks for core ${wanted} (it runs ${running || 'an unknown version'})`,
+    '',
+    `${who} pressed "Ask for this upgrade" in Settings, Software update on ${host}.`,
+    'This project cannot upgrade itself: the people who run its server do it.',
+    `Move its core to ${wanted} or newer, or tell them when it will be.`,
+  ].join('\n');
+}
+
+/**
+ * Send one upgrade request, or answer from the stored one. Never throws for an
+ * expected refusal; returns { status, body } for the route to send.
+ *
+ * deps: { hub, issueReceipt(receipt) → id|null, fetchImpl, getSetting, setSetting, now }
+ */
+async function requestUpgrade({ host, running, wanted, builder, doorKind }, deps) {
+  const now = deps.now || Date.now;
+  const hub = deps.hub;
+  const target = projectHost(host);
+  if (!wanted || !VERSION_RE.test(String(wanted))) return { status: 409, body: { error: 'nothing_to_ask', message: 'This project is up to date.' } };
+  if (!target || !isOperatorRun({ doorKind, host: target, hub })) {
+    return { status: 409, body: { error: 'not_operator_run', message: 'This project is not upgraded by an operator, so there is no one to ask.' } };
+  }
+
+  const stored = parseStored(await deps.getSetting(SETTING_KEY));
+  if (stored && stored.version === wanted) return { status: 200, body: { ok: true, already: true, request: stored } };
+  if (stored && now() < Date.parse(stored.requested_at) + COOLDOWN_MS) {
+    const retry = Math.ceil((Date.parse(stored.requested_at) + COOLDOWN_MS - now()) / 1000);
+    return { status: 429, body: { error: 'asked_recently', message: 'This project already asked for an upgrade today. Ask again tomorrow.', retry_after_seconds: retry, request: stored } };
+  }
+
+  const login = builder && typeof builder.github_login === 'string' && LOGIN_RE.test(builder.github_login) ? builder.github_login : null;
+  const message = requestMessage({ host: target, running, wanted, login });
+  const sha256 = crypto.createHash('sha256').update(message, 'utf8').digest('hex');
+  const receipt = deps.issueReceipt({
+    github_id: String(builder && builder.github_id),
+    github_login: login,
+    sha256,
+    kind: 'bug',
+    core_version: running || null,
+  });
+  if (!receipt) return { status: 429, body: { error: 'rate_limited', message: 'Too many requests just now. Try again in ten minutes.', retry_after_seconds: 600 } };
+
+  let res;
+  try {
+    res = await (deps.fetchImpl || fetch)(`${String(hub).replace(/\/+$/, '')}/api/bongos/sso/feedback/direct`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ origin: `https://${target}`, receipt, message, kind: 'bug', context: {} }),
+      redirect: 'error',
+      signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
+    });
+  } catch {
+    return { status: 502, body: { error: 'operator_unreachable', message: 'Could not reach the people who run this project. Try again in a few minutes.' } };
+  }
+  if (res.status === 429) return { status: 429, body: { error: 'rate_limited', message: 'Too many requests just now. Try again in an hour.', retry_after_seconds: 3600 } };
+  if (res.status !== 202) {
+    return { status: 502, body: { error: 'operator_unreachable', message: `The request was not taken (HTTP ${res.status}). Try again later.` } };
+  }
+
+  const request = { version: String(wanted), requested_at: new Date(now()).toISOString(), by: login };
+  await deps.setSetting(SETTING_KEY, JSON.stringify(request), builder && builder.id != null ? builder.id : null);
+  return { status: 201, body: { ok: true, already: false, request } };
+}
+
+module.exports = {
+  SETTING_KEY,
+  COOLDOWN_MS,
+  projectHost,
+  isOperatorRun,
+  parseStored,
+  askState,
+  requestMessage,
+  requestUpgrade,
+};

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.70'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.71'; // 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('discord'); log.info('mounted');

package/tests/claude_materialize.mjs

@@ -41,24 +41,24 @@ function t(name, fn) {
 
 // ---- bongosify -------------------------------------------------------------
 t('bongosify: a script WITH a dedicated verb → bongos <verb> (args preserved)', () => {
-  assert.equal(m.bongosify('run `node scripts/gds/ship.js 1885 --force`'), 'run `bongos ship 1885 --force`');
-  assert.equal(m.bongosify('node scripts/gds/start.js --json'), 'bongos start --json');
+  assert.equal(m.bongosify('run `node scripts/gds/ship.js 1885 --force`'), 'run `npx bongos ship 1885 --force`');
+  assert.equal(m.bongosify('node scripts/gds/start.js --json'), 'npx bongos start --json');
 });
 
 t('bongosify: a script WITHOUT a dedicated verb → bongos exec (args preserved)', () => {
-  assert.equal(m.bongosify('node scripts/gds/api.js GET /api/gds/me'), 'bongos exec scripts/gds/api.js GET /api/gds/me');
-  assert.equal(m.bongosify('node scripts/gds/capture.js "x"'), 'bongos exec scripts/gds/capture.js "x"');
+  assert.equal(m.bongosify('node scripts/gds/api.js GET /api/gds/me'), 'npx bongos exec scripts/gds/api.js GET /api/gds/me');
+  assert.equal(m.bongosify('node scripts/gds/capture.js "x"'), 'npx bongos exec scripts/gds/capture.js "x"');
 });
 
 t('bongosify: $CLAUDE_PROJECT_DIR + surrounding quotes are stripped', () => {
-  assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify('node "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"'), 'npx bongos exec scripts/gds/session-cost.js');
 });
 
 t('bongosify: the run-node.sh resolver form (task 1003548) collapses to the same bongos form', () => {
   const wrap = 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/run-node.sh"';
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'bongos exec scripts/gds/session-cost.js');
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
-  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'bongos ship 1885');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/session-cost.js"`), 'npx bongos exec scripts/gds/session-cost.js');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/deploy-divergence.js" --line --timeout-ms 2500`), 'npx bongos exec scripts/gds/deploy-divergence.js --line --timeout-ms 2500');
+  assert.equal(m.bongosify(`${wrap} "$CLAUDE_PROJECT_DIR/scripts/gds/ship.js" 1885`), 'npx bongos ship 1885');
   // …and a resolver call whose target is a .claude/hooks/*.js stays instance-local, like the bare-node form.
   const hook = `${wrap} "$CLAUDE_PROJECT_DIR/.claude/hooks/secret-gate.js"`;
   assert.equal(m.bongosify(hook), hook);
@@ -100,7 +100,7 @@ t('transformSettings: rewrites scripts/gds hook commands, keeps .claude/hooks/ o
   const out = JSON.parse(m.transformSettings(p));
   const cmds = out.hooks.Stop[0].hooks.map((h) => h.command);
   assert.deepEqual(cmds, [
-    'bongos exec scripts/gds/session-cost.js',
+    'npx bongos exec scripts/gds/session-cost.js',
     'node "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-sound.js"',
   ]);
   rmSync(dir, { recursive: true, force: true });
@@ -121,12 +121,12 @@ t('transformSettings: permission rules are rewritten to the form the instance\'s
     },
   }, null, 2));
   const out = JSON.parse(m.transformSettings(p)).permissions;
-  assert.deepEqual(out.allow, ['Bash(bongos ship:*)', 'Bash(bongos exec scripts/gds/me.js:*)', 'Bash(git status:*)'],
+  assert.deepEqual(out.allow, ['Bash(npx bongos ship:*)', 'Bash(npx bongos exec scripts/gds/me.js:*)', 'Bash(git status:*)'],
     'allow takes the ONE spelling the skills use, and two spellings of a command collapse to one rule');
   // An instance can reach a script two ways — `bongos release` and `bongos exec scripts/gds/release.js` —
   // so a restrictive rule that named only one would still LOOK like a guard while guarding half.
-  assert.deepEqual(out.deny, ['Bash(bongos release:*)', 'Bash(bongos exec scripts/gds/release.js:*)', 'Bash(bongos exec scripts/gds/me.js:*)', 'Read(./.env)']);
-  assert.deepEqual(out.ask, ['Bash(bongos claim:*)', 'Bash(bongos exec scripts/gds/claim.js:*)']);
+  assert.deepEqual(out.deny, ['Bash(npx bongos release:*)', 'Bash(npx bongos exec scripts/gds/release.js:*)', 'Bash(npx bongos exec scripts/gds/me.js:*)', 'Read(./.env)']);
+  assert.deepEqual(out.ask, ['Bash(npx bongos claim:*)', 'Bash(npx bongos exec scripts/gds/claim.js:*)']);
   assert.equal(out.defaultMode, 'acceptEdits', 'a non-list permission key passes through untouched');
   rmSync(dir, { recursive: true, force: true });
 });
@@ -222,7 +222,7 @@ t('copyTreeTransformed: overwrite:false LEAVES a pre-existing dest file (reports
   const res = m.copyTreeTransformed(src, dest, { overwrite: false });
   assert.equal(res.files, 1, 'only the absent file was written');
   assert.deepEqual(res.skipped, ['b.md']);
-  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'bongos ship 1', 'absent file materialized + rewritten');
+  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'npx bongos ship 1', 'absent file materialized + rewritten');
   assert.equal(readFileSync(join(dest, 'b.md'), 'utf8'), ownerB, 'pre-existing file left byte-untouched');
   rmSync(src, { recursive: true, force: true });
   rmSync(dest, { recursive: true, force: true });
@@ -236,7 +236,7 @@ t('copyTreeTransformed: overwrite defaults true → greenfield still clobbers (r
   const res = m.copyTreeTransformed(src, dest);       // default overwrite:true
   assert.equal(res.files, 1);
   assert.deepEqual(res.skipped, []);
-  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'bongos start', 'greenfield overwrites as before');
+  assert.equal(readFileSync(join(dest, 'a.md'), 'utf8'), 'npx bongos start', 'greenfield overwrites as before');
   rmSync(src, { recursive: true, force: true });
   rmSync(dest, { recursive: true, force: true });
 });
@@ -772,8 +772,8 @@ t('every allow-rule names a verb the CLI actually registers', () => {
   const checkedByTool = {};
   for (const rule of m.STARTER_ALLOW) {
     const [, tool, inner] = rule.match(/^(\w+)\((.*?)(?::\*)?\)$/); // any shell tool (task 1004014)
-    if (!inner.startsWith('bongos ')) continue; // the git/gh reads (task 1003992) name no verb
-    const verb = inner.split(' ')[1];
+    if (!inner.startsWith('npx bongos ')) continue; // the git/gh reads (task 1003992) name no verb
+    const verb = inner.split(' ')[2];
     assert.ok(cliVerbs[verb], `allow-rule "${rule}" names "${verb}", which is not a registered bongos verb`);
     checkedByTool[tool] = (checkedByTool[tool] || 0) + 1;
   }
@@ -784,7 +784,7 @@ t('every allow-rule names a verb the CLI actually registers', () => {
 t('the escape hatch is NOT blanket-allowed', () => {
   // `bongos exec` runs any script inside the core by path. Allow-listing it bare
   // would be a blanket grant wearing a narrow rule's clothes.
-  assert.deepEqual(m.STARTER_ALLOW.filter((r) => /^\w+\(bongos exec(:\*| \*)?\)$/.test(r)), [],
+  assert.deepEqual(m.STARTER_ALLOW.filter((r) => /^\w+\((?:npx )?bongos exec(:\*| \*)?\)$/.test(r)), [],
     'bongos exec must never be allowed bare — under any shell tool');
   const execRules = m.STARTER_ALLOW.filter((r) => r.includes('bongos exec'));
   for (const r of execRules) {
@@ -1065,7 +1065,7 @@ t('a checkout-materialized instance gets allow-rules in the bongos form, end to
   const res = m.materializeClaude({ coreRoot: core, instanceDir: inst, dryRun: false });
   assert.equal(res.settings, true);
   const allow = JSON.parse(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8')).permissions.allow;
-  assert.deepEqual(allow, ['Bash(bongos claim:*)', 'Bash(bongos exec scripts/gds/api.js:*)', 'Bash(gh pr list:*)']);
+  assert.deepEqual(allow, ['Bash(npx bongos claim:*)', 'Bash(npx bongos exec scripts/gds/api.js:*)', 'Bash(gh pr list:*)']);
   for (const rule of allow) assert.ok(m.STARTER_ALLOW.includes(rule), `${rule} is the starter's spelling too — one form, two sources`);
   rmSync(core, { recursive: true, force: true });
   rmSync(inst, { recursive: true, force: true });
@@ -1154,5 +1154,182 @@ t('materializeClaude: a broken core settings.json reaches the instance unchanged
   rmSync(inst, { recursive: true, force: true });
 });
 
+// ---- task 1004621: a project runs the CLI as `npx bongos`, never a bare `bongos` ---------------
+// The bin ships at node_modules/.bin/bongos, which is not on PATH, so every bare `bongos …` a
+// project's assistant read was a guaranteed `command not found` on the session's first call.
+
+// A bare `bongos <verb>` (not preceded by `npx `) anywhere in text an assistant reads.
+const BARE_VERB = new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${Object.keys(cliVerbs).join('|')})(?![\w-])`);
+
+t('bongosify: a hand-written bare `bongos <verb>` takes the npx spelling too', () => {
+  assert.equal(m.bongosify('paste `bongos paste-token <token>` back'), 'paste `npx bongos paste-token <token>` back');
+  assert.equal(m.bongosify('run bongos upgrade --to 1.2.3'), 'run npx bongos upgrade --to 1.2.3');
+  assert.equal(m.bongosify('`bongos exec scripts/gds/api.js GET /x`'), '`npx bongos exec scripts/gds/api.js GET /x`');
+});
+
+t('bongosify: never double-prefixes, and is idempotent over its own output', () => {
+  for (const s of ['npx bongos ship 1', 'node scripts/gds/ship.js 1', 'bongos ship 1', '`bongos dev` then `node scripts/gds/start.js`']) {
+    const once = m.bongosify(s);
+    assert.ok(!once.includes('npx npx'), `double prefix from: ${s}`);
+    assert.equal(m.bongosify(once), once, `a second run changed: ${s}`);
+    assert.ok(!BARE_VERB.test(once), `a bare bongos verb survived: ${once}`);
+  }
+});
+
+t('bongosify: names and prose that merely contain "bongos" are left alone', () => {
+  for (const s of ['`@bongos/core`', '/bongos-feedback', '`bongos: command not found`', 'the Bongos status page',
+    'the bongos CLI', 'the bongos database', 'src/bongos/routes/x.js', 'GET /api/bongos/me', 'bongos-ship-card']) {
+    assert.equal(m.bongosify(s), s, s);
+  }
+});
+
+t('every core skill + routine, as a project receives it, carries no bare `bongos <verb>`', () => {
+  const offenders = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      if (!/\.(md|txt|sh)$/.test(e.name)) continue;
+      const out = m.bongosify(readFileSync(p, 'utf8'));
+      if (out.includes('npx npx')) offenders.push(`${relative(ROOT, p)}: npx npx`);
+      const hit = out.match(BARE_VERB);
+      if (hit) offenders.push(`${relative(ROOT, p)}: ${hit[0]}`);
+    }
+  };
+  walk(join(ROOT, '.claude', 'skills'));
+  walk(join(ROOT, '.claude', 'scheduled-tasks'));
+  assert.deepEqual(offenders, []);
+});
+
+t('the core checkout\'s OWN skills are not rewritten: they still run node scripts/gds/*.js', () => {
+  const ship = readFileSync(join(ROOT, '.claude', 'skills', 'builder-ship', 'SKILL.md'), 'utf8');
+  assert.match(ship, /node scripts\/gds\/ship\.js/, 'the source skill keeps the checkout spelling');
+  assert.ok(!ship.includes('npx bongos ship'), 'npx only appears on the way INTO a project');
+});
+
+t('the starter allow-list is the npx spelling: no rule for a bare `bongos` nothing runs', () => {
+  const bongosRules = m.STARTER_ALLOW.filter((r) => /bongos /.test(r));
+  assert.ok(bongosRules.length > 10, 'the blessed commands are there');
+  for (const r of bongosRules) assert.match(r, /^\w+\(npx bongos [a-z]/, `not the npx spelling: ${r}`);
+  assert.ok(m.STARTER_ALLOW.includes('Bash(npx bongos ship:*)') && m.STARTER_ALLOW.includes('PowerShell(npx bongos ship:*)'));
+});
+
+t('the starter CLAUDE.md names only `npx bongos …` commands and keeps the npm install first-run note', () => {
+  const md = tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } });
+  assert.equal(md.match(BARE_VERB), null, 'a bare bongos command is a command-not-found in a project');
+  assert.ok(md.includes('npx bongos start') && md.includes('npx bongos ship') && md.includes('npx bongos doctor'));
+  assert.ok(md.indexOf('npm install') < md.indexOf('npx bongos start'), 'npm install still comes first');
+  assert.match(md, /not on your PATH/, 'says WHY it runs through npx');
+});
+
+// The pre-1004621 starter, rebuilt from the template by undoing each refresh pair. If the template
+// changes a CLI sentence without adding its pair, this round trip stops being exact and fails.
+const legacyStarter = (branding) => {
+  let md = tmpl.renderInstanceClaudeMd(branding);
+  for (const [legacy, current] of tmpl.LEGACY_CLI_LINES) md = md.split(current).join(legacy);
+  return md;
+};
+
+t('refreshStarterCliLines: an unedited old starter comes back byte-identical to today\'s', () => {
+  const b = { identity: { productName: 'Acme' }, domains: { buildersOrigin: 'https://b.acme.example.org' } };
+  const old = legacyStarter(b);
+  assert.ok(BARE_VERB.test(old), 'the fixture really is the old bare-bongos starter');
+  const r = tmpl.refreshStarterCliLines(old);
+  assert.equal(r.text, tmpl.renderInstanceClaudeMd(b));
+  assert.equal(r.changed, tmpl.LEGACY_CLI_LINES.length);
+  assert.deepEqual(tmpl.refreshStarterCliLines(r.text), { text: r.text, changed: 0 }, 'idempotent');
+});
+
+t('refreshStarterCliLines: an owner-reworded sentence and the rest of the file are left alone; CRLF works', () => {
+  const old = legacyStarter({ identity: { productName: 'Acme' } })
+    .replace('- **`bongos claim <id>`** locks a task to your session.', '- We claim with `bongos claim <id>` (our wording).')
+    + '\n## Our own notes\n\nKeep `bongos start` here verbatim.\n';
+  const r = tmpl.refreshStarterCliLines(old);
+  assert.ok(r.text.includes('- We claim with `bongos claim <id>` (our wording).'), 'an edited line is the owner\'s');
+  assert.ok(r.text.endsWith('\n## Our own notes\n\nKeep `bongos start` here verbatim.\n'), 'owner prose untouched');
+  assert.equal(r.changed, tmpl.LEGACY_CLI_LINES.length - 1);
+  const crlf = tmpl.refreshStarterCliLines(legacyStarter({ identity: { productName: 'Acme' } }).replace(/\n/g, '\r\n'));
+  assert.equal(crlf.changed, tmpl.LEGACY_CLI_LINES.length, 'a Windows (autocrlf) checkout is matched too');
+  assert.ok(!/(?<!\r)\n/.test(crlf.text), 'and keeps its CRLF endings');
+});
+
+// The upgrade path. `bongos upgrade` calls materializeClaude({ coreRoot, instanceDir, log }) —
+// default overwrite — after moving the pin (scripts/gds/upgrade.js), so an EXISTING project picks
+// all of this up on its next upgrade. This drives exactly that call against a project scaffolded
+// before task 1004621: old CLAUDE.md, the bare-`bongos` starter settings.json, old skills.
+function oldProjectFixture() {
+  const core = mkdtempSync(join(tmpdir(), 'npx-core-'));
+  const inst = mkdtempSync(join(tmpdir(), 'npx-inst-'));
+  mkdirSync(join(core, '.claude', 'skills', 'alpha'), { recursive: true }); // package-only: no settings.json at the core root
+  writeFileSync(join(core, '.claude', 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\n---\nrun `node scripts/gds/ship.js 1`, or paste `bongos paste-token <token>`\n');
+  mkdirSync(join(inst, '.claude', 'skills', 'alpha'), { recursive: true });
+  writeFileSync(join(inst, '.claude', 'skills', 'alpha', 'SKILL.md'), '---\nname: alpha\n---\nrun `bongos ship 1`\n'); // what the old materialize wrote
+  writeFileSync(join(inst, 'CLAUDE.md'), legacyStarter({ identity: { productName: 'Acme' } }));
+  const oldAllow = m.STARTER_ALLOW.map((r) => r.replace('(npx bongos ', '(bongos '))
+    .filter((r) => r !== 'Bash(bongos recall:*)' && r !== 'PowerShell(bongos recall:*)'); // the owner removed one
+  writeFileSync(join(inst, '.claude', 'settings.json'), JSON.stringify({ permissions: { allow: oldAllow, deny: [] } }, null, 2));
+  const settings = () => JSON.parse(readFileSync(join(inst, '.claude', 'settings.json'), 'utf8'));
+  return { core, inst, oldAllow, settings, cleanup: () => { rmSync(core, { recursive: true, force: true }); rmSync(inst, { recursive: true, force: true }); } };
+}
+
+t('upgrade path: an existing project\'s skills, CLAUDE.md and allow-list all move to `npx bongos`', () => {
+  const f = oldProjectFixture();
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  const skill = readFileSync(join(f.inst, '.claude', 'skills', 'alpha', 'SKILL.md'), 'utf8');
+  assert.match(skill, /`npx bongos ship 1`/);
+  assert.match(skill, /`npx bongos paste-token <token>`/);
+  assert.equal(skill.match(BARE_VERB), null);
+  const md = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  assert.equal(md, tmpl.renderInstanceClaudeMd({ identity: { productName: 'Acme' } }), 'the unedited starter sentences were refreshed');
+  assert.equal(res.claudeMdCliLines, tmpl.LEGACY_CLI_LINES.length);
+  assert.ok(res.writtenPaths.includes('CLAUDE.md'), 'reported, so the pin commit carries it');
+  const allow = f.settings().permissions.allow;
+  for (const r of f.oldAllow) assert.ok(allow.includes(r), `the owner's own rule is kept: ${r}`);
+  assert.ok(allow.includes('Bash(npx bongos ship:*)') && allow.includes('PowerShell(npx bongos ship:*)'), 'each bare rule gained its npx twin');
+  assert.ok(!allow.includes('Bash(npx bongos recall:*)'), 'a rule the owner removed is not brought back by its twin');
+  assert.equal(res.settingsAllowTwinsAdded.length, f.oldAllow.filter((r) => /\(bongos /.test(r)).length);
+  f.cleanup();
+});
+
+t('upgrade path: a second upgrade adds nothing more (no npx npx, no duplicate rule)', () => {
+  const f = oldProjectFixture();
+  m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  const after1 = readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8');
+  const md1 = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  const res2 = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, log: () => {} });
+  assert.equal(readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8'), after1);
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), md1);
+  assert.equal(res2.settingsAllowTwinsAdded, undefined);
+  assert.ok(!after1.includes('npx npx') && !md1.includes('npx npx'));
+  f.cleanup();
+});
+
+t('upgrade path: a dry run reports the changes and writes nothing', () => {
+  const f = oldProjectFixture();
+  const before = readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8');
+  const mdBefore = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  const res = m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: true, log: () => {} });
+  assert.ok(res.settingsAllowTwinsAdded.length > 0 && res.claudeMdCliLines > 0);
+  assert.equal(readFileSync(join(f.inst, '.claude', 'settings.json'), 'utf8'), before);
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), mdBefore);
+  assert.ok(!res.writtenPaths.includes('CLAUDE.md'), 'a content-preserving rewrite is not waived for the pre-flight');
+  f.cleanup();
+});
+
+t('adopt mode (overwrite:false) never touches the owner\'s CLAUDE.md', () => {
+  const f = oldProjectFixture();
+  const mdBefore = readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8');
+  m.materializeClaude({ coreRoot: f.core, instanceDir: f.inst, dryRun: false, overwrite: false, log: () => {} });
+  assert.equal(readFileSync(join(f.inst, 'CLAUDE.md'), 'utf8'), mdBefore);
+  f.cleanup();
+});
+
+t('topUpNpxAllowTwins: an unreadable shape is reported, never rewritten', () => {
+  assert.match(m.topUpNpxAllowTwins('{nope').reason, /not valid JSON/);
+  assert.match(m.topUpNpxAllowTwins('{"permissions":{"allow":"x"}}').reason, /permissions\.allow/);
+  assert.deepEqual(m.topUpNpxAllowTwins('{"permissions":{"allow":["Bash(git status:*)"]}}'), { text: null, added: [], reason: null });
+});
+
 console.log(`\nclaude_materialize: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);