@bongos/core 1.21.120 → 1.21.122

package/src/bongos/routes/modules.js

@@ -77,6 +77,8 @@ const express = require('express');
 const auth = require('../auth');
 const { asyncHandler, validateOrRespond, LIMITS } = require('./_helpers');
 const loader = require('../../module-loader/loader');
+// named, not loader.restartPendingFor: knip sees a named require, never a member read
+const { restartPendingFor } = require('../../module-loader/loader');
 const catalog = require('../../module-loader/catalog');
 const modulesLib = require('../../modules');
 // scripts/gds/ is a sibling CORE-package dir (both resolve under
@@ -110,6 +112,15 @@ const log = require('../logger').logger.child({ src: 'modules' });
 const { listOverrides, setOverride } = require('../module-overrides');
 const { listCatalog } = require('../module-listing');
 
+// The sentence for a toggle that waits on a restart (task 1004463). 'routes' are the
+// module's pages, 'pollers' its background jobs. PURE.
+function restartNote(waits, enabled) {
+  const parts = enabled
+    ? [waits.includes('routes') && 'its pages do not open', waits.includes('pollers') && 'its background jobs do not run']
+    : [waits.includes('routes') && 'its pages still open', waits.includes('pollers') && 'its background jobs still run'];
+  return `It turns ${enabled ? 'on' : 'off'} at the next restart of this server. Until then ${parts.filter(Boolean).join(' and ')}.`;
+}
+
 // A packaged submission embeds every file's content (base64) — cap the total
 // so a runaway/misbuilt module can't bloat the review-queue table. Generous
 // headroom over what a real feature module carries (routes + migrations + UI
@@ -258,6 +269,8 @@ module.exports = function buildModulesRouter() {
         ? `/builders/modules?howto=${encodeURIComponent(m.key)}&version=${encodeURIComponent(String(m.version))}`
         : null;
       m.store_delisted = m.source === 'instance' && delistedKeys.has(m.key);
+      // what of this module still waits for a restart to match its toggle (task 1004463)
+      m.restart_pending = restartPendingFor(m.key, m.enabled === true);
     }
     res.json({
       modules: all,
@@ -297,6 +310,9 @@ module.exports = function buildModulesRouter() {
       // the write path deliberately is not.
       const resolvedSet = await setOverride(key, enabled, { builderId: req.builder && req.builder.id });
       const effective = resolvedSet ? resolvedSet[key] === true : enabled;
+      // Routes mount and pollers start once, at boot (task 1004463): say so rather than
+      // "live now" when this change waits for the next restart of this server.
+      const waits = restartPendingFor(key, effective);
 
       console.log(`[gds] module "${key}" ${enabled ? 'enabled' : 'disabled'} by builder ${req.builder && req.builder.id}`);
       res.json({
@@ -308,9 +324,12 @@ module.exports = function buildModulesRouter() {
         // who is not told so will re-click the toggle and blame the feature.
         effective,
         source: (resolvedSet && resolvedSet.sources && resolvedSet.sources[key]) || 'override',
-        note: effective === enabled
-          ? 'Live on this box now, and durable — it survives the next deploy.'
-          : `Recorded, but "${key}" still resolves to ${effective}: a higher-precedence layer (env, or the spend guard) is winning.`,
+        restart_pending: waits,
+        note: effective !== enabled
+          ? `Recorded, but "${key}" still resolves to ${effective}: a higher-precedence layer (env, or the spend guard) is winning.`
+          : waits.length
+            ? `Saved, and it survives the next deploy. ${restartNote(waits, enabled)}`
+            : 'Live on this box now, and durable — it survives the next deploy.',
       });
     }));
 

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

@@ -112,7 +112,7 @@ function discoverModules({ roots = DEFAULT_ROOTS, core = coreVersion() } = {}) {
 // Cached singleton for app code (lazy, like src/modules.js's modules()).
 let _cache = null;
 function discovered(opts) { return (_cache ||= discoverModules(opts)); }
-function _reset() { _cache = null; _startedPollers = []; }
+function _reset() { _cache = null; _startedPollers = []; _boot = { routes: null, pollers: null }; _bootShape = null; }
 
 // The discovered manifests as MODULE_REGISTRY-shaped entries, so src/modules.js
 // can merge them with its built-in registry. Empty until a module exists.
@@ -190,8 +190,10 @@ function mountModuleRoutes(router, { isEnabled } = {}, opts) {
   const enabled = enabledModules({ isEnabled }, opts);
   verifyEnabledPorts(enabled);
   let mounted = 0;
-  for (const { dir, manifest } of enabled) {
+  _boot.routes = new Set();
+  for (const { key, dir, manifest } of enabled) {
     const routeKeys = (manifest.contributes && manifest.contributes.routes) || [];
+    if (routeKeys.length) _boot.routes.add(key);
     for (const rk of routeKeys) {
       const factory = require(path.join(dir, 'routes', `${rk}.js`));
       const sub = typeof factory === 'function' ? factory() : factory;
@@ -284,6 +286,41 @@ function moduleWebSurfaces({ isEnabled } = {}, opts) {
   return out;
 }
 
+// What this process mounted at boot (task 1004463): the keys whose routes were mounted
+// and whose pollers started. null until that boot step has run in this process — so a
+// script or test that never booted is never told a restart is pending.
+let _boot = { routes: null, pollers: null };
+// key → { routes, pollers }: whether each discovered module mounts routes / runs a poller in
+// this process. Module files do not change under a running process, so it is worked out
+// once, on first ask, rather than stat'ing disk on every GET /modules.
+let _bootShape = null;
+function bootShape(opts) {
+  if (_bootShape) return _bootShape;
+  _bootShape = new Map();
+  for (const { key, dir, manifest } of discovered(opts).loaded) {
+    const c = manifest.contributes || {};
+    _bootShape.set(key, {
+      routes: (c.routes || []).length > 0,
+      // the same rule startModulePollers applies: a poller with no file here runs elsewhere
+      pollers: (c.pollers || []).some((pk) => fs.existsSync(path.join(dir, 'pollers', `${pk}.js`))),
+    });
+  }
+  return _bootShape;
+}
+
+// Does turning module `key` to `enabled` wait for a restart in THIS process (task
+// 1004463)? Routes mount and pollers start once, at boot, so a module switched on after
+// boot has no pages yet, and one switched off keeps answering until the restart. Returns
+// what waits — [] when the change is live now. PURE over the boot record and the manifest.
+function restartPendingFor(key, enabled, opts) {
+  const shape = bootShape(opts).get(key);
+  if (!shape) return [];
+  const waits = [];
+  if (_boot.routes && shape.routes && _boot.routes.has(key) !== !!enabled) waits.push('routes');
+  if (_boot.pollers && shape.pollers && _boot.pollers.has(key) !== !!enabled) waits.push('pollers');
+  return waits;
+}
+
 // Started poller handles (key, name, module), so stopModulePollers stops exactly
 // what startModulePollers started — and a test can introspect them.
 let _startedPollers = [];
@@ -299,6 +336,7 @@ let _startedPollers = [];
 // No-op when nothing is discovered/enabled. Returns the started-handle list.
 function startModulePollers(deps = {}, { isEnabled } = {}, opts) {
   const started = [];
+  _boot.pollers = new Set();
   for (const { key, dir, manifest } of discovered(opts).loaded) {
     if (typeof isEnabled === 'function' && !isEnabled(key)) continue;
     const pollerKeys = (manifest.contributes && manifest.contributes.pollers) || [];
@@ -323,6 +361,7 @@ function startModulePollers(deps = {}, { isEnabled } = {}, opts) {
             r.catch((e) => console.error(`[module-loader] poller ${key}/${pk} start error: ${e && e.message ? e.message : e}`));
           }
           started.push({ key, poller: pk, handle: poller });
+          _boot.pollers.add(key);
         }
       } catch (e) {
         console.error(`[module-loader] poller ${key}/${pk} start threw: ${e && e.message ? e.message : e}`);
@@ -370,6 +409,7 @@ module.exports = {
   moduleWebSurfaces,
   startModulePollers,
   stopModulePollers,
+  restartPendingFor,
   loaderSnapshot,
   coreVersion,
   dedupeRoots,

package/tests/government_protected_surfaces.mjs

@@ -266,11 +266,19 @@ const ADDED_SINCE_R101 = [
     + 'score guards a model cannot talk past.'),
   ...carve('scripts/gds/ship.js', ['ship-check', 'ship-deploy-target', 'ship-escalation',
     'ship-finish', 'ship-flow', 'ship-git', 'ship-grade-steps', 'ship-grade', 'ship-honesty',
-    'ship-io', 'ship-land', 'ship-memory-sync', 'ship-merge-gate', 'ship-merge',
+    'ship-io', 'ship-land', 'ship-memory-sync', 'ship-merge-gate', 'ship-merge', 'ship-mode-ask',
     'ship-preflight-steps', 'ship-regen', 'ship-resume', 'ship-session-upload', 'ship-state',
     'ship-surprise', 'ship-visual'],
     'the 2026-08-23 ship.js carve: the land path, the ship state machine, the grade gate '
     + 'steps and pushVia, ~6,200 lines behind a 373-line protected entry point.'),
+  // task 1004630: a ship.js sibling added after the carve — registered so the carve
+  // tripwire below stays green and the file sits at ship.js's floor.
+  {
+    after: 'scripts/gds/ship-visual.js',
+    glob: 'scripts/gds/ship-mode-ask.js',
+    why: 'split out of the protected ship.js: the ship-mode step every ship runs '
+       + 'before it lands, so an edit here could change how work reaches main.',
+  },
   // task 1002839 (ADR 0089 §1). Not a `grader-*.js` sibling, so the carve tripwire
   // below would not demand it — registered by hand because it owns the gate.
   {

package/tests/hall_catalog_world.mjs

@@ -58,7 +58,7 @@ test('modules: the row is the oversight row — title with the mono key, clamped
   assert.match(js, /<span class="ov-row__title">\$\{escapeHtml\(m\.title \|\| m\.key\)\}<span class="ov-mono">\$\{escapeHtml\(m\.key\)\}<\/span>/, 'the key rides inside the title in mono');
   assert.match(js, /class="ov-row__sub mod-row__desc"/, 'the description is the sub line');
   assert.match(js, /<details class="mod-more"/, 'a details disclosure opens the rest');
-  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}<\/div>/, 'provenance, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill are the facts line');
+  assert.match(js, /<div class="ov-row__facts">\$\{provenancePill\(m\)\}\$\{attributionFacts\(m\)\}\$\{upkeepFact\(m\)\}\$\{howtoFact\(m\)\}\$\{delistedFact\(m\)\}\$\{restartFact\(m\)\}<\/div>/, 'provenance, credit, upkeep, (for a store version, task 1004366) the how-to link and (task 1003797) the delisted pill and (task 1004463) the waits-for-a-restart pill are the facts line');
   assert.match(js, /<div class="ov-row__right mod-row__right">\$\{rightHtml\(m\)\}<\/div>/, 'the right column is one function');
   const css = read('modules.css');
   assert.match(css, /\.mod-row__desc \{[^}]*-webkit-line-clamp: 2/, 'the description clamps to two lines');

package/tests/module_loader.mjs

@@ -462,3 +462,34 @@ test('the demo proof module mounts + serves through the loader (BV1.R52 / task 1
   assert.deepEqual(routes.sort(), ['GET /demo/health', 'POST /demo/ping']);
   loader._reset();
 });
+
+// ---------------------------------------------------------------------------
+// task 1004463 — a toggle says whether it waits for a restart. Routes mount and pollers
+// start once, at boot, so restartPendingFor compares the toggle with what THIS process
+// mounted; the Modules toggle used to claim "Live on this box now" regardless.
+// ---------------------------------------------------------------------------
+
+test('task 1004463: restartPendingFor names what waits for a restart, and nothing before boot', () => {
+  loader._reset();
+  const factory = "module.exports = () => function moduleRoute(req, res, next) { next(); };";
+  const poller = 'module.exports = { start() {}, stop() {} };';
+  const root = fixtureRoot({
+    pages: { manifest: validManifest('pages', { contributes: { routes: ['main'] } }), files: { 'routes/main.js': factory } },
+    jobs: { manifest: validManifest('jobs', { contributes: { routes: ['main'], pollers: ['tick'] } }), files: { 'routes/main.js': factory, 'pollers/tick.js': poller } },
+    remote: { manifest: validManifest('remote', { contributes: { pollers: ['elsewhere'] } }) },
+    quiet: { manifest: validManifest('quiet') },
+  });
+  const opts = { roots: [root], core: '1.0.0' };
+  assert.deepEqual(loader.restartPendingFor('pages', true, opts), [], 'a process that never booted is never told a restart is pending');
+  const bootOn = (k) => k === 'jobs';
+  loader.mountModuleRoutes({ use: () => {} }, { isEnabled: bootOn }, opts);
+  loader.startModulePollers({}, { isEnabled: bootOn }, opts);
+  assert.deepEqual(loader.restartPendingFor('pages', true, opts), ['routes'], 'switched on after boot: its pages wait');
+  assert.deepEqual(loader.restartPendingFor('pages', false, opts), [], 'back off: matches what is mounted');
+  assert.deepEqual(loader.restartPendingFor('jobs', false, opts), ['routes', 'pollers'], 'switched off after boot: pages and jobs keep running');
+  assert.deepEqual(loader.restartPendingFor('jobs', true, opts), []);
+  assert.deepEqual(loader.restartPendingFor('remote', true, opts), [], 'a poller with no file here never runs in this process');
+  assert.deepEqual(loader.restartPendingFor('quiet', true, opts), [], 'nothing mounted at boot, nothing to wait for');
+  assert.deepEqual(loader.restartPendingFor('nope', true, opts), []);
+  loader._reset();
+});

package/tests/module_toggle_restart.mjs

@@ -0,0 +1,73 @@
+// tests/module_toggle_restart.mjs — task 1004463.
+//
+// Measured on cloudbongos.com: switching a module on stored the override and the toggle
+// said "Live on this box now", but the module's pages stayed 404 until the next restart,
+// because routes mount (and pollers start) once, at boot. The toggle now asks the loader
+// what still waits (restartPendingFor) and says so; GET /modules carries the same field
+// so the hall can show "waits for a restart" on the row.
+//
+// Hermetic: setOverride is stubbed BEFORE the route file binds it, and the loader's
+// answer is stubbed on the loader object the route calls through. The loader's own rule
+// is tests/module_loader.mjs (task 1004463 case).
+//
+// Run:  node --test tests/module_toggle_restart.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const overrides = require('../src/bongos/module-overrides.js');
+overrides.setOverride = async (key, enabled) => ({ [key]: enabled, sources: { [key]: 'override' } });
+const loader = require('../src/module-loader/loader.js');
+// the route binds restartPendingFor at require time, so stub it BEFORE the route loads and
+// let each case choose the answer through `pending`
+let pending = () => [];
+loader.restartPendingFor = (...a) => pending(...a);
+const buildModulesRouter = require('../src/bongos/routes/modules.js');
+
+function handlerFor(router, method, path) {
+  const layer = router.stack.find((l) => l.route && l.route.path === path && l.route.methods[method]);
+  assert.ok(layer, `no ${method.toUpperCase()} ${path} on the router`);
+  return layer.route.stack[layer.route.stack.length - 1].handle;
+}
+async function invoke(handler, req) {
+  const res = {
+    statusCode: 200, body: undefined,
+    json(b) { this.body = b; return this; },
+    status(c) { this.statusCode = c; return this; },
+    fail(code, opts) { this.body = { error: code, ...opts }; return this; },
+  };
+  let err = null;
+  await handler(req, res, (e) => { err = e; });
+  if (err) throw err;
+  return res;
+}
+const router = buildModulesRouter();
+const key = buildModulesRouter.listModules()[0].key;
+const toggle = (enabled) => invoke(handlerFor(router, 'post', '/modules/:key/enable'), { params: { key }, query: {}, body: { enabled }, builder: { id: 1 } });
+
+test('a toggle that waits for a restart says so, instead of "live now"', async () => {
+  pending = () => ['routes', 'pollers'];
+  const on = await toggle(true);
+  assert.deepEqual(on.body.restart_pending, ['routes', 'pollers']);
+  assert.doesNotMatch(on.body.note, /Live on this box now/);
+  assert.equal(on.body.note, 'Saved, and it survives the next deploy. It turns on at the next restart of this server. Until then its pages do not open and its background jobs do not run.');
+  pending = () => ['routes'];
+  const off = await toggle(false);
+  assert.equal(off.body.note, 'Saved, and it survives the next deploy. It turns off at the next restart of this server. Until then its pages still open.');
+});
+
+test('a toggle with nothing waiting is still live now', async () => {
+  pending = () => [];
+  const r = await toggle(true);
+  assert.deepEqual(r.body.restart_pending, []);
+  assert.equal(r.body.note, 'Live on this box now, and durable — it survives the next deploy.');
+});
+
+test('GET /modules carries restart_pending on every row', async () => {
+  pending = (k) => (k === key ? ['routes'] : []);
+  const r = await invoke(handlerFor(router, 'get', '/modules'), { params: {}, query: {}, body: {} });
+  for (const m of r.body.modules) assert.ok(Array.isArray(m.restart_pending), `${m.key} carries restart_pending`);
+  assert.deepEqual(r.body.modules.find((m) => m.key === key).restart_pending, ['routes']);
+});

package/tests/projects_hub_pre_uat.mjs

@@ -86,7 +86,10 @@ test('the restart door appears ONLY where it has a reason to exist, and mirrors
   // task 1004182 folded into 'cloud-host'. A `!== 'dedicated'` test against a value no row
   // can hold is always true, so keeping it would have been a condition that reads like a
   // guard and guards nothing.
-  assert.doesNotMatch(body, /hosting_shape/, 'no shape term survives — the one it excluded no longer exists');
+  // task 1004463: the ONE shape term is an inclusion — the platform's own row always has the
+  // door, because a module toggled in its hall waits for a restart
+  assert.match(body, /inst.last_verified_up === false || inst.hosting_shape === 'control-plane'/, 'the self row is the one healthy card with a door');
+  assert.doesNotMatch(body, /dedicated/, 'the shape it once excluded no longer exists');
   assert.match(body, /!inst\.open_intent/, 'the strip tells the story while work is in flight');
 });
 

package/tests/provision_restart.mjs

@@ -167,9 +167,9 @@ await ta('dry-run runs no real work and observes nothing', async () => {
   assert.equal(writes.length, 0);
 });
 
-await ta('a co-tenant restarts on the co-hosting box; a cloud-host on the control plane', async () => {
+await ta("a co-tenant restarts on the co-hosting box; a cloud-host and the platform's own row on the control plane", async () => {
   const seen = {};
-  for (const shape of ['co-tenant', 'cloud-host']) {
+  for (const shape of ['co-tenant', 'cloud-host', 'control-plane']) {
     const box = [], control = [];
     const { deps } = recorder();
     deps.exec = (cmd) => { box.push(cmd); return /healthz/.test(cmd) ? { ok: true, stdout: '{}' } : { ok: true, stdout: '' }; };
@@ -179,6 +179,7 @@ await ta('a co-tenant restarts on the co-hosting box; a cloud-host on the contro
   }
   assert.ok(seen['co-tenant'].box > 0 && seen['co-tenant'].control === 0, 'a co-tenant runs on the box');
   assert.ok(seen['cloud-host'].control > 0 && seen['cloud-host'].box === 0, 'a cloud-host runs control-plane-local (task 2074) — restart it THERE');
+  assert.ok(seen['control-plane'].control > 0 && seen['control-plane'].box === 0, 'the self row IS this box (task 1004463)');
 });
 
 await ta('privileged mode escalates the restart', async () => {

package/tests/provisioning_restart.mjs

@@ -89,14 +89,17 @@ t('RESTART_FROM is exactly {active} — every other state is already served by t
   }
 });
 
-t('RESTART_SHAPES is the runner-reachable pair, and the set is a subset of HOSTING_SHAPES', () => {
-  assert.deepEqual([...provisioning.RESTART_SHAPES].sort(), ['cloud-host', 'co-tenant']);
+t('RESTART_SHAPES is what the runner can reach, and the set is a subset of HOSTING_SHAPES', () => {
+  // task 1004463 added the control plane's own row: its hall's module toggles wait for a restart
+  assert.deepEqual([...provisioning.RESTART_SHAPES].sort(), ['cloud-host', 'co-tenant', 'control-plane']);
+  const G = require('../modules/provisioning/control-plane-guard.js');
+  assert.equal(G.intentAllowedForShape('restart', 'control-plane'), true, 'the self-row guard lets the restart through, so the route never promises one it refuses');
   for (const s of provisioning.RESTART_SHAPES) assert.ok(provisioning.HOSTING_SHAPES.includes(s), `${s} is a real shape`);
   // Was `!has('dedicated')`. Task 1004182 removed that value from HOSTING_SHAPES, which made
   // the assertion vacuously true — it would now pass against any set at all. Name the shapes
   // that still EXIST and are still unreachable, and assert they are real first, so this
   // cannot rot the same way twice.
-  for (const unreachable of ['byo-host', 'control-plane']) {
+  for (const unreachable of ['byo-host']) {
     assert.ok(provisioning.HOSTING_SHAPES.includes(unreachable), `${unreachable} must be a real shape or this assertion is vacuous`);
     assert.ok(!provisioning.RESTART_SHAPES.has(unreachable), unreachable);
   }

package/tests/provisioning_settings_apply.mjs

@@ -92,8 +92,8 @@ t('the two gates agree: every settings-apply shape is one the self-row guard let
   // "a restart is coming" and then answer the owner with control_plane_protected.
   const G = require('../modules/provisioning/control-plane-guard.js');
   for (const s of provisioning.SETTINGS_APPLY_SHAPES) assert.equal(G.intentAllowedForShape('settings-apply', s), true, s);
-  // and the restart door was NOT opened on the self row as a side effect
-  assert.ok(!provisioning.RESTART_SHAPES.has('control-plane'), 'task 1004334 widened the settings push only');
+  // the restart door on the self row came later, deliberately (task 1004463)
+  assert.ok(provisioning.RESTART_SHAPES.has('control-plane'), 'task 1004463 opened the restart door on the self row');
 });
 
 await ta('enqueueSettingsApply: a fresh intent → created:true; the INSERT carries the settings-apply action', async () => {

package/tests/ship_mode_first_ship.mjs

@@ -0,0 +1,219 @@
+// tests/ship_mode_first_ship.mjs — the first ship asks for the ship mode once
+// (task 1004630, ADR 0369).
+//
+// Pinned here:
+//   1. the verdict: ask only when the mode was never chosen, the caller can answer,
+//      and someone is there to answer; an answer is saved; a chosen mode never asks;
+//   2. the flow: an ask stops the ship with exit 5 and prints the two choices plus
+//      the re-run; the re-run saves the answer once and the ship goes on; a refused
+//      save never blocks the ship; a bad --ship-mode value is refused;
+//   3. asked exactly once: after the answer is saved, the next ship does not ask;
+//   4. the wiring: shipMain runs the ask after the claim is found and before the
+//      budget cap, the grader and the resolve, so nothing resolves while it waits;
+//   5. the read route reports can_change for the caller, and null when authority
+//      cannot be established.
+//
+// Run:  node --test tests/ship_mode_first_ship.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const {
+  ASK_EXIT, ASK_MARKER, unattended, shipModeFlag, shipModeAskVerdict, askLines, runFirstShipAsk,
+} = require('../scripts/gds/ship-mode-ask.js');
+
+const unchosen = { mode: 'auto', chosen: false, source: 'default', can_change: true };
+const chosen = { mode: 'manual', chosen: true, source: 'project_settings', can_change: true };
+
+// ---- 1. the verdict --------------------------------------------------------
+
+test('a never-chosen mode asks; a chosen one never does', () => {
+  assert.deepEqual(shipModeAskVerdict({ shipMode: unchosen, flag: null, unattended: false }), { action: 'ask' });
+  assert.equal(shipModeAskVerdict({ shipMode: chosen, flag: null, unattended: false }).action, 'proceed');
+});
+
+test('an answer on an unchosen project is saved; on a chosen one it changes nothing', () => {
+  assert.deepEqual(shipModeAskVerdict({ shipMode: unchosen, flag: { mode: 'manual' }, unattended: false }), { action: 'save', mode: 'manual' });
+  assert.equal(shipModeAskVerdict({ shipMode: chosen, flag: { mode: 'auto' }, unattended: false }).action, 'proceed',
+    'the flag answers the first-ship question only; changing a chosen mode is the settings page or shipping-mode.js');
+});
+
+test('never blocks a ship nobody can answer for', () => {
+  assert.equal(shipModeAskVerdict({ shipMode: null, flag: null, unattended: false }).why, 'unreadable');
+  assert.equal(shipModeAskVerdict({ shipMode: { ...unchosen, can_change: false }, flag: null, unattended: false }).why, 'cannot_change');
+  assert.equal(shipModeAskVerdict({ shipMode: unchosen, flag: null, unattended: true }).why, 'unattended');
+});
+
+test('an older server with no can_change still asks (unknown is not "no")', () => {
+  const { can_change, ...old } = unchosen;
+  assert.equal(shipModeAskVerdict({ shipMode: old, flag: null, unattended: false }).action, 'ask');
+  assert.equal(shipModeAskVerdict({ shipMode: { ...unchosen, can_change: null }, flag: null, unattended: false }).action, 'ask');
+});
+
+test('unattended means an Autobongos worker or a subagent', () => {
+  assert.equal(unattended({}), false);
+  assert.equal(unattended({ OTB_SUBAGENT: '1' }), true);
+  assert.equal(unattended({ AUTOBONGOS_GRADE_LEDGER: '/tmp/ledger.json' }), true);
+});
+
+test('--ship-mode parses auto|manual in any case and flags anything else', () => {
+  assert.equal(shipModeFlag(['1', '--notes', 'x']), null);
+  assert.deepEqual(shipModeFlag(['1', '--ship-mode', 'Auto']), { mode: 'auto' });
+  assert.deepEqual(shipModeFlag(['1', '--ship-mode', 'manual']), { mode: 'manual' });
+  assert.deepEqual(shipModeFlag(['1', '--ship-mode', 'sometimes']), { bad: 'sometimes' });
+  assert.deepEqual(shipModeFlag(['1', '--ship-mode']), { bad: '(missing)' });
+});
+
+// ---- 2. the flow -----------------------------------------------------------
+
+function harness(initial, { saveStatus = 200 } = {}) {
+  let current = { ...initial };
+  const saves = [];
+  const logs = [];
+  return {
+    saves, logs,
+    deps: (args, env = {}) => ({
+      args,
+      env,
+      log: (l) => logs.push(l),
+      getShipMode: async () => ({ ...current }),
+      saveShipMode: async (mode) => {
+        saves.push(mode);
+        if (saveStatus !== 200) return { ok: false, status: saveStatus, data: { error: 'permission_forbidden' } };
+        current = { ...current, mode, chosen: true, source: 'project_settings' };
+        return { ok: true, status: 200, data: { mode, chosen: true, sentence: `Saved ${mode}.` } };
+      },
+    }),
+  };
+}
+
+test('an unchosen project stops the ship with exit 5 and asks Auto first', async () => {
+  const h = harness(unchosen);
+  const args = ['1004630', '--notes-file', 'notes.md', '--summary', 'two words'];
+  const r = await runFirstShipAsk(h.deps(args));
+  assert.equal(r.stop, true);
+  assert.equal(r.exit, ASK_EXIT);
+  assert.equal(ASK_EXIT, 5);
+  const text = r.lines.join('\n');
+  assert.ok(r.lines[0].startsWith(ASK_MARKER));
+  assert.match(text, /Auto \(recommended\)[\s\S]*Manual/, 'Auto is offered first and named as recommended');
+  assert.match(text, /node scripts\/gds\/ship\.js 1004630 --notes-file notes\.md --summary "two words" --ship-mode auto\|manual/);
+  assert.match(text, /claim is still active/);
+  assert.deepEqual(h.saves, [], 'asking saves nothing');
+});
+
+test('the re-run with the answer saves it and the ship goes on', async () => {
+  const h = harness(unchosen);
+  const r = await runFirstShipAsk(h.deps(['1004630', '--ship-mode', 'manual']));
+  assert.equal(r.stop, false);
+  assert.deepEqual(h.saves, ['manual']);
+  assert.match(h.logs.join('\n'), /Ship mode saved: manual/);
+});
+
+test('asked exactly once: after the answer, the next ship neither asks nor saves', async () => {
+  const h = harness(unchosen);
+  const first = await runFirstShipAsk(h.deps(['1']));
+  assert.equal(first.stop, true);
+  await runFirstShipAsk(h.deps(['1', '--ship-mode', 'auto']));
+  const next = await runFirstShipAsk(h.deps(['2']));
+  assert.equal(next.stop, false, 'the second ship does not ask again');
+  const nextWithStaleFlag = await runFirstShipAsk(h.deps(['3', '--ship-mode', 'manual']));
+  assert.equal(nextWithStaleFlag.stop, false);
+  assert.deepEqual(h.saves, ['auto'], 'the answer was written once and never overwritten by a later ship');
+});
+
+test('a refused save never blocks the ship, and says who can set it', async () => {
+  const h = harness(unchosen, { saveStatus: 403 });
+  const r = await runFirstShipAsk(h.deps(['1', '--ship-mode', 'manual']));
+  assert.equal(r.stop, false);
+  assert.match(h.logs.join('\n'), /Only the project owner[\s\S]*default, Auto/);
+});
+
+test('a bad --ship-mode value is refused before anything resolves', async () => {
+  const h = harness(unchosen);
+  const r = await runFirstShipAsk(h.deps(['1', '--ship-mode', 'sometimes']));
+  assert.equal(r.stop, true);
+  assert.equal(r.exit, 2);
+  assert.match(r.lines[0], /must be auto or manual/);
+  assert.deepEqual(h.saves, []);
+});
+
+test('an unreadable mode and an unattended run both ship on without asking', async () => {
+  const dead = await runFirstShipAsk({ args: ['1'], getShipMode: async () => { throw new Error('down'); }, saveShipMode: async () => assert.fail('no save'), env: {}, log: () => {} });
+  assert.equal(dead.stop, false);
+  const h = harness(unchosen);
+  const alone = await runFirstShipAsk(h.deps(['1'], { OTB_SUBAGENT: '1' }));
+  assert.equal(alone.stop, false);
+});
+
+test('the ask falls back to its own wording when the server sends no choices', () => {
+  const lines = askLines({ mode: 'auto', chosen: false }, ['1']);
+  assert.match(lines.join('\n'), /Auto \(recommended\)[\s\S]*Manual/);
+});
+
+// ---- 4. the wiring ---------------------------------------------------------
+
+test('shipMain asks after finding the claim and before the budget cap and grader', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-flow.js'), 'utf8');
+  const main = src.slice(src.indexOf('async function shipMain'));
+  const claimFound = main.indexOf("const ac = claims.find(");
+  const ask = main.indexOf('runFirstShipAsk(');
+  const budget = main.indexOf('Hard cap: refuse to ship over the monthly budget');
+  assert.ok(claimFound > 0 && ask > claimFound, 'asks only once a real claim is in hand');
+  assert.ok(budget > ask, 'asks before the budget cap, so nothing has resolved or been spent');
+  assert.match(main.slice(ask, budget), /cliExit\(firstShip\.exit\);\s*return;/, 'stops with cliExit, never a hard exit after a request');
+});
+
+test('the --ship-mode flag is documented in the ship usage banner', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship.js'), 'utf8');
+  assert.match(src, /--ship-mode auto\|manual/);
+});
+
+// ---- 5. the read route's can_change ----------------------------------------
+
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+const fakeRes = () => ({
+  code: null, statusCode: 200, payload: null, headers: {},
+  fail(code, opts) { this.code = code; this.statusCode = opts?.status ?? 400; this.payload = { error: code }; return this; },
+  status(c) { this.statusCode = c; return this; },
+  set(k, v) { this.headers[k] = v; return this; },
+  json(p) { this.payload = p; return this; },
+});
+
+async function readAs({ builder, government }) {
+  const saved = { resolve: api.projectSettings.resolveShipMode, resolveOptional: api.resolveOptional };
+  api.projectSettings.resolveShipMode = async () => ({ mode: 'auto', source: 'default', chosen: false, invalid: null });
+  api.resolveOptional = (port) => (port === 'government' ? government : saved.resolveOptional(port));
+  try {
+    const file = path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js');
+    delete require.cache[require.resolve(file)];
+    const router = require(file)();
+    const route = router.stack.find((l) => l.route && l.route.path === '/project-settings/ship-mode' && l.route.methods.get).route;
+    const res = fakeRes();
+    await route.stack[route.stack.length - 1].handle({ builder }, res);
+    return res;
+  } finally {
+    api.projectSettings.resolveShipMode = saved.resolve;
+    api.resolveOptional = saved.resolveOptional;
+  }
+}
+
+test('can_change is true for a settings manager and false for anyone else', async () => {
+  const government = { resolveBuilderPermissions: async (id) => (id === 1 ? ['project.settings.manage'] : ['task.claim.any']) };
+  assert.equal((await readAs({ builder: { id: 1 }, government })).payload.can_change, true);
+  assert.equal((await readAs({ builder: { id: 2 }, government })).payload.can_change, false);
+});
+
+test('can_change is null, never true, when authority cannot be established', async () => {
+  assert.equal((await readAs({ builder: { id: 1 }, government: null })).payload.can_change, null);
+  const throwing = { resolveBuilderPermissions: async () => { throw new Error('boom'); } };
+  const res = await readAs({ builder: { id: 1 }, government: throwing });
+  assert.equal(res.statusCode, 200, 'a permission read failure never fails the read');
+  assert.equal(res.payload.can_change, null);
+});