@bongos/core 1.21.73 → 1.21.74

package/modules/lifecycle/routes/project-settings.js

@@ -34,6 +34,29 @@ const goalCategory = require('../goal-category');
 
 const log = api.logger('lifecycle');
 
+// --- ship mode: who starts a ship (task 1004628, ADR 0369) -------------------
+//
+// One row shape, two readers: the settings page (inside GET /project-settings) and
+// any builder's CLI or AI session (GET /project-settings/ship-mode), so the sentence
+// a person reads and the one an agent obeys are the same words.
+function shipModeRow(resolved) {
+  return {
+    key: 'ship_mode',
+    title: 'Ship mode',
+    editable: true,
+    state: 'live',
+    value: { mode: resolved.mode, chosen: resolved.chosen, modes: api.projectSettings.SHIP_MODES },
+    sentence: api.projectSettings.describeShipMode(resolved),
+    choices: [
+      { mode: 'auto', label: 'Auto (recommended)', sentence: 'When the AI finishes a task it ships and lands it. Nobody has to type a command.' },
+      { mode: 'manual', label: 'Manual', sentence: 'The AI stops before each ship and asks a person to approve it.' },
+    ],
+    source: resolved.source,
+    invalid: resolved.invalid,
+    reads: { file: 'project_settings[\'ship.mode\'] (migration core_231)', adr: 'ADR 0369' },
+  };
+}
+
 // --- the three rows that are READ, never written -----------------------------
 //
 // Each names the committed artefact it resolves from, because "you cannot edit this"
@@ -214,12 +237,14 @@ module.exports = function buildProjectSettingsRouter() {
       // Inactive included: the set's SHAPE is what this page edits, and a deactivated
       // category the owner cannot see is one they cannot bring back.
       const categories = await goalCategory.listCategories({ includeInactive: true });
+      const shipMode = await api.projectSettings.resolveShipMode();
 
       // A settings read is a configuration comparison — a cached one is wrong the
       // moment somebody turns a knob (the rot.js precedent).
       res.set('Cache-Control', 'no-store');
       res.json({
         rows: [
+          shipModeRow(shipMode),
           {
             key: 'rot_timer',
             title: 'Stale timer',
@@ -316,7 +341,47 @@ module.exports = function buildProjectSettingsRouter() {
       }
     });
 
+  // GET /project-settings/ship-mode — the ship mode alone, for the CLI and the AI.
+  //
+  // rank: any signed-in builder. Unlike the full settings read this carries no
+  // reward internals or file paths an agent could not already read, and every
+  // builder's AI session must know whether to ship on its own or stop and ask —
+  // gating it Metic+ would leave a newcomer's session guessing.
+  router.get('/project-settings/ship-mode', api.requireBuilder, async (req, res) => {
+    try {
+      const resolved = await api.projectSettings.resolveShipMode();
+      res.set('Cache-Control', 'no-store');
+      const row = shipModeRow(resolved);
+      res.json({ mode: resolved.mode, chosen: resolved.chosen, source: resolved.source, sentence: row.sentence, choices: row.choices });
+    } catch (err) {
+      log.error(`GET /project-settings/ship-mode: ${err && err.message}`);
+      res.fail('project_settings_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /project-settings/ship-mode — body { mode: 'auto' | 'manual' }.
+  //
+  // rank: project.settings.manage (metic+, government_010) — the same atom as the
+  // other writes on this page. Validated with the resolver's own parser, so the
+  // page, the CLI and the reader can never disagree about what a mode is.
+  router.patch('/project-settings/ship-mode', api.requireBuilder, api.requirePermission('project.settings.manage'), async (req, res) => {
+    if (api.validateOrRespond(req, res, { mode: { required: true, type: 'string' } })) return;
+    const parsed = api.projectSettings.parseShipMode(req.body.mode);
+    if (!parsed.mode) {
+      return res.fail('bad_ship_mode', { status: 400, message: `mode: ${parsed.reason}` });
+    }
+    try {
+      await api.projectSettings.set(api.projectSettings.KEYS.SHIP_MODE, parsed.mode, req.builder.id);
+      const resolved = await api.projectSettings.resolveShipMode();
+      res.json({ ok: true, mode: resolved.mode, chosen: resolved.chosen, source: resolved.source, sentence: api.projectSettings.describeShipMode(resolved) });
+    } catch (err) {
+      log.error(`PATCH /project-settings/ship-mode: ${err && err.message}`);
+      res.fail('project_settings_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };
 
 module.exports.settingsDeskRows = settingsDeskRows;
+module.exports.shipModeRow = shipModeRow;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.73",
+  "version": "1.21.74",
   "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

@@ -9248,5 +9248,11 @@
       "id": "1004625",
       "text": "The governor city now has its own tab, and in Governing mode it leads the sidebar with every other governing page tucked into one dropdown under it."
     }
+  ],
+  "1.21.74": [
+    {
+      "id": "1004628",
+      "text": "Projects now have a Ship mode setting. Auto, the default, means the AI ships finished work on its own. Manual means it asks first. Owners can switch it on the project settings page."
+    }
   ]
 }

package/scripts/gds/shipping-mode.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// scripts/gds/shipping-mode.js — read or set the project's ship mode (task 1004628, ADR 0369).
+//
+// WHY. Ship mode says WHO starts a ship: in `auto` the AI finishes a task and ships
+// it with no commands from the person; in `manual` it stops and asks first. An AI
+// session has to know which before it ships, and a person has to be able to change
+// it without opening the settings page — so the mode is one command away.
+//
+// Usage:
+//   node scripts/gds/shipping-mode.js                 print the mode (any builder)
+//   node scripts/gds/shipping-mode.js auto|manual     set it (needs project.settings.manage)
+//   node scripts/gds/shipping-mode.js --json          print the mode as JSON
+//
+// Also `bongos ship-mode [auto|manual]`.
+
+'use strict';
+
+const { apiCall, requireSession, errCode, cliExit } = require('./cli-lib');
+
+const USAGE = 'usage: node scripts/gds/shipping-mode.js [auto|manual] [--json]';
+
+// What a person sees. One sentence from the server, plus how to change it.
+function describe(data) {
+  const lines = [`Ship mode: ${data.mode}${data.chosen ? '' : ' (default — not chosen yet)'}`];
+  if (data.sentence) lines.push(data.sentence);
+  lines.push(data.mode === 'manual'
+    ? 'Change it: node scripts/gds/shipping-mode.js auto'
+    : 'Change it: node scripts/gds/shipping-mode.js manual');
+  return lines.join('\n');
+}
+
+async function main(argv) {
+  const args = argv.filter((a) => a !== '--json');
+  const json = argv.includes('--json');
+  if (args.includes('--help') || args.includes('-h')) { console.log(USAGE); return 0; }
+  if (args.length > 1) { console.error(USAGE); return 2; }
+
+  await requireSession();
+
+  if (args.length === 0) {
+    const r = await apiCall('GET', '/api/bongos/project-settings/ship-mode');
+    if (!r.ok) {
+      console.error(`Could not read the ship mode (${r.status}${errCode(r.data) ? `: ${errCode(r.data)}` : ''}).`);
+      return 1;
+    }
+    console.log(json ? JSON.stringify(r.data) : describe(r.data));
+    return 0;
+  }
+
+  const mode = String(args[0]).trim().toLowerCase();
+  if (mode !== 'auto' && mode !== 'manual') { console.error(USAGE); return 2; }
+  const r = await apiCall('PATCH', '/api/bongos/project-settings/ship-mode', { mode });
+  if (!r.ok) {
+    if (r.status === 403) {
+      console.error('Only the project owner (or someone with project settings access) can change the ship mode.');
+    } else {
+      console.error(`Could not set the ship mode (${r.status}${errCode(r.data) ? `: ${errCode(r.data)}` : ''}).`);
+    }
+    return 1;
+  }
+  console.log(json ? JSON.stringify(r.data) : `Saved. ${describe(r.data)}`);
+  return 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2))
+    .then((code) => cliExit(code))
+    .catch((err) => { console.error('fatal:', err && err.message ? err.message : err); cliExit(1); });
+}
+
+module.exports = { describe, main };

package/src/bongos/project-settings.js

@@ -49,8 +49,20 @@ const { logger } = require('./logger');
 const SETTING_KEYS = {
   ROT_DAYS: 'attention.rot_days',
   FOCUS_VERSION: 'roadmap.focus_version',
+  SHIP_MODE: 'ship.mode',
 };
 
+// SHIP MODE (task 1004628, ADR 0369) — WHO starts a ship, never HOW it lands.
+//   auto   — the AI finishes a task, then ships and lands it with no commands from
+//            the person. The default, because a new owner who is handed terminal
+//            commands at every ship reads the project as broken (owner feedback,
+//            2026-10-08).
+//   manual — the AI stops before shipping and the person approves each ship.
+// It is NOT the deploy mode (config/deploy.json, ci|laptop): that one decides the
+// mechanics of landing once a ship starts, is committed config, and is unchanged.
+const SHIP_MODES = Object.freeze(['auto', 'manual']);
+const DEFAULT_SHIP_MODE = 'auto';
+
 // The last-resort rot timer, in days. 30 because that is the shortest window in
 // which "nobody has touched this" is evidence of rot rather than evidence of a
 // normal week — a fortnight would fire on every ordinary holiday, and a quarter is
@@ -202,6 +214,56 @@ async function setFocusVersionId(versionId, builderId = null) {
   return String(versionId);
 }
 
+// parseShipMode(raw) — one candidate as a ship mode, or why it is unusable. Pure,
+// never throws, case-insensitive and trimmed so a hand-typed "Manual " still reads.
+function parseShipMode(raw) {
+  if (raw == null || String(raw).trim() === '') return { reason: 'empty' };
+  const v = String(raw).trim().toLowerCase();
+  if (!SHIP_MODES.includes(v)) return { reason: `must be one of ${SHIP_MODES.join(' | ')}` };
+  return { mode: v };
+}
+
+// resolveShipMode() — the project's ship mode and where it came from.
+// Returns { mode, source, chosen, invalid }:
+//   mode    — always 'auto' or 'manual'
+//   source  — 'project_settings' | 'default'
+//   chosen  — true only when someone actually SET a usable value. "Never chosen" is
+//             a real answer the first-ship prompt (task 1004630) asks about, so it
+//             must not be confused with "chose the default".
+//   invalid — null, or { where, raw, reason } for a stored value that is unusable.
+// A database that cannot be read answers the default rather than failing a ship —
+// the same reporting posture as resolveRotDays.
+async function resolveShipMode() {
+  let row = null;
+  try {
+    row = await getSetting(SETTING_KEYS.SHIP_MODE);
+  } catch (err) {
+    logger.error(`project_settings read failed; falling back to the default ship mode: ${err && err.message}`);
+    return { mode: DEFAULT_SHIP_MODE, source: 'default', chosen: false, invalid: null };
+  }
+  if (row && row.value != null && row.value !== '') {
+    const got = parseShipMode(row.value);
+    if (got.mode) return { mode: got.mode, source: 'project_settings', chosen: true, invalid: null };
+    return {
+      mode: DEFAULT_SHIP_MODE,
+      source: 'default',
+      chosen: false,
+      invalid: { where: `project_settings['${SETTING_KEYS.SHIP_MODE}']`, raw: String(row.value), reason: got.reason },
+    };
+  }
+  return { mode: DEFAULT_SHIP_MODE, source: 'default', chosen: false, invalid: null };
+}
+
+// describeShipMode(resolved) — one plain sentence for a person or an AI session.
+function describeShipMode(resolved) {
+  const r = resolved || {};
+  const what = r.mode === 'manual'
+    ? 'Manual: the AI stops before each ship and waits for a person to approve it.'
+    : 'Auto: when the AI finishes a task it ships and lands it with no commands from a person.';
+  const how = r.chosen ? '' : ' (the default — nobody has chosen yet)';
+  return `${what}${how}`;
+}
+
 // parseDays is exported for the tests only — the range check and the default are
 // asserted against the SAME constants the resolver reads, because a test that
 // re-typed 30 or 365 would be the second copy of the number this file exists to
@@ -218,4 +280,9 @@ module.exports = {
   describeRotTimer,
   getFocusVersionId,
   setFocusVersionId,
+  SHIP_MODES,
+  DEFAULT_SHIP_MODE,
+  parseShipMode,
+  resolveShipMode,
+  describeShipMode,
 };

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.73'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.74'; // 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');
@@ -462,6 +462,12 @@ module.exports = {
     // page's own anti-drift rule forbids, caught one layer up on task 1003280's grade.
     get MIN_ROT_DAYS() { return require('./bongos/project-settings').MIN_ROT_DAYS; },
     get MAX_ROT_DAYS() { return require('./bongos/project-settings').MAX_ROT_DAYS; },
+    // Ship mode (task 1004628, ADR 0369): who starts a ship — the AI (auto) or a
+    // person (manual). The settings page writes it; the CLI and the AI read it.
+    get SHIP_MODES() { return require('./bongos/project-settings').SHIP_MODES; },
+    get parseShipMode() { return require('./bongos/project-settings').parseShipMode; },
+    get resolveShipMode() { return require('./bongos/project-settings').resolveShipMode; },
+    get describeShipMode() { return require('./bongos/project-settings').describeShipMode; },
   },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,

package/tests/project_settings_page.mjs

@@ -63,8 +63,10 @@ function buildRouterWithStubs({ timer, categories, reward = WORKING_REWARD }) {
     resolveOptional: api.resolveOptional,
     list: gc.listCategories,
     set: api.projectSettings.set,
+    resolveShipMode: api.projectSettings.resolveShipMode,
   };
   api.resolveRotDays = async () => timer;
+  api.projectSettings.resolveShipMode = async () => ({ mode: 'auto', source: 'default', chosen: false, invalid: null });
   // reward: WORKING_REWARD (default) | null (port absent) | 'throws' (rewardConfig raises).
   const rewardPort = reward === 'throws'
     ? { rewardConfig: () => { throw new Error('reward boom'); } }
@@ -80,6 +82,7 @@ function buildRouterWithStubs({ timer, categories, reward = WORKING_REWARD }) {
     api.resolveOptional = saved.resolveOptional;
     gc.listCategories = saved.list;
     api.projectSettings.set = saved.set;
+    api.projectSettings.resolveShipMode = saved.resolveShipMode;
   };
   // The handler is the LAST layer on the matching route (requireBuilder and the
   // permission gate sit in front); calling it directly is what keeps this a unit test
@@ -99,22 +102,22 @@ const CATS = [
   { id: 2, slug: 'retired-thing', label: 'Retired thing', sort_order: 20, active: false },
 ];
 
-test('one read returns all five fundamentals, each naming where its value came from', async () => {
+test('one read returns all six fundamentals, each naming where its value came from', async () => {
   const { handlerFor, restore } = buildRouterWithStubs({ timer: TIMER_OK, categories: CATS });
   try {
     const res = fakeRes();
     await handlerFor('get', '/project-settings')({ query: {} }, res);
     const rows = res.payload.rows;
-    assert.equal(rows.length, 5, 'the page draws five rows, so the read returns five');
+    assert.equal(rows.length, 6, 'the page draws six rows, so the read returns six');
     assert.deepEqual(rows.map((r) => r.key),
-      ['rot_timer', 'work_categories', 'credit_calculation', 'equity_calculation', 'upmarket_percent']);
+      ['ship_mode', 'rot_timer', 'work_categories', 'credit_calculation', 'equity_calculation', 'upmarket_percent']);
     // Provenance is the point of the page: every row says where its value came from.
     for (const r of rows) {
       assert.ok(r.reads && r.reads.file, `${r.key} names no file`);
       assert.ok(r.sentence && r.sentence.length > 20, `${r.key} has no readable sentence`);
     }
-    // Exactly two knobs — the criterion's "change the two that are knobs".
-    assert.deepEqual(rows.filter((r) => r.editable).map((r) => r.key), ['rot_timer', 'work_categories']);
+    // Three knobs: the criterion's two, plus ship mode (task 1004628).
+    assert.deepEqual(rows.filter((r) => r.editable).map((r) => r.key), ['ship_mode', 'rot_timer', 'work_categories']);
     // A no-store receipt: a cached settings read is wrong the moment a knob turns.
     assert.equal(res.headers['Cache-Control'], 'no-store');
   } finally { restore(); }

package/tests/ship_mode.mjs

@@ -0,0 +1,171 @@
+// tests/ship_mode.mjs — the project's ship mode: who starts a ship (task 1004628, ADR 0369).
+//
+// Pinned here:
+//   1. the parser accepts exactly auto|manual (trimmed, any case) and explains a refusal;
+//   2. the resolver defaults to AUTO, tells "never chosen" apart from "chose auto",
+//      reports an unusable stored value instead of throwing, and survives a dead DB;
+//   3. the routes: any builder can READ it (the AI must know), the write validates
+//      through the same parser and echoes what the system will now read;
+//   4. the CLI verb is registered and its text names how to change the mode.
+//
+// Run:  node --test tests/ship_mode.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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 poolMod = require(path.join(ROOT, 'src', 'bongos', 'pool.js'));
+// Destructured from a literal relative path, so the dead-code scan (knip) can see
+// these exports are used — a computed path.join() is invisible to it.
+const {
+  SHIP_MODES, DEFAULT_SHIP_MODE, parseShipMode, resolveShipMode, describeShipMode,
+} = require('../src/bongos/project-settings.js');
+const ps = { SHIP_MODES, DEFAULT_SHIP_MODE, parseShipMode, resolveShipMode, describeShipMode };
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+
+// Swap the pool's query for the duration of one call; project-settings reads
+// `pool.query` at call time, so this reaches the real SQL path.
+async function withPool(query, fn) {
+  const pool = poolMod.pool;
+  const saved = pool.query;
+  pool.query = query;
+  try { return await fn(); } finally { pool.query = saved; }
+}
+const rowWith = (value) => async () => ({ rows: value == null ? [] : [{ key: 'ship.mode', value, updated_at: null, updated_by: 1 }] });
+
+test('parseShipMode accepts exactly auto|manual, trimmed and in any case', () => {
+  assert.deepEqual([...ps.SHIP_MODES], ['auto', 'manual']);
+  assert.deepEqual(ps.parseShipMode('auto'), { mode: 'auto' });
+  assert.deepEqual(ps.parseShipMode(' Manual '), { mode: 'manual' });
+  assert.equal(ps.parseShipMode('').reason, 'empty');
+  assert.equal(ps.parseShipMode(null).reason, 'empty');
+  assert.match(ps.parseShipMode('yolo').reason, /auto \| manual/);
+});
+
+test('the default is auto, and an unset project reads as NOT chosen', async () => {
+  assert.equal(ps.DEFAULT_SHIP_MODE, 'auto');
+  const r = await withPool(rowWith(null), () => ps.resolveShipMode());
+  assert.deepEqual(r, { mode: 'auto', source: 'default', chosen: false, invalid: null });
+});
+
+test('a stored choice is read back as chosen — even when it equals the default', async () => {
+  const auto = await withPool(rowWith('auto'), () => ps.resolveShipMode());
+  assert.equal(auto.mode, 'auto');
+  assert.equal(auto.chosen, true, 'choosing auto is different from never choosing');
+  assert.equal(auto.source, 'project_settings');
+  const manual = await withPool(rowWith('manual'), () => ps.resolveShipMode());
+  assert.equal(manual.mode, 'manual');
+});
+
+test('an unusable stored value falls back to auto and is reported, not thrown', async () => {
+  const r = await withPool(rowWith('sometimes'), () => ps.resolveShipMode());
+  assert.equal(r.mode, 'auto');
+  assert.equal(r.chosen, false);
+  assert.equal(r.invalid.raw, 'sometimes');
+  assert.match(r.invalid.where, /ship\.mode/);
+});
+
+test('a database that cannot be read answers the default instead of failing a ship', async () => {
+  const r = await withPool(async () => { throw new Error('db down'); }, () => ps.resolveShipMode());
+  assert.deepEqual(r, { mode: 'auto', source: 'default', chosen: false, invalid: null });
+});
+
+test('describeShipMode says what each mode means in plain words', () => {
+  assert.match(ps.describeShipMode({ mode: 'auto', chosen: true }), /ships and lands it/);
+  assert.match(ps.describeShipMode({ mode: 'manual', chosen: true }), /waits for a person/);
+  assert.match(ps.describeShipMode({ mode: 'auto', chosen: false }), /nobody has chosen yet/);
+});
+
+// ---- the routes -------------------------------------------------------------
+
+const fakeRes = () => ({
+  code: null, statusCode: 200, payload: null, headers: {},
+  fail(code, opts) { this.code = code; this.statusCode = opts?.status ?? 400; this.payload = { error: code, ...(opts || {}) }; 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; },
+});
+
+function buildRouter({ resolved }) {
+  const saved = { resolve: api.projectSettings.resolveShipMode, set: api.projectSettings.set };
+  const writes = [];
+  let current = resolved;
+  api.projectSettings.resolveShipMode = async () => current;
+  api.projectSettings.set = async (key, value, by) => {
+    writes.push({ key, value, by });
+    current = { mode: value, source: 'project_settings', chosen: true, invalid: null };
+    return { key, value };
+  };
+  const file = path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js');
+  delete require.cache[require.resolve(file)];
+  const router = require(file)();
+  const route = (method, p) => router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]).route;
+  const restore = () => { api.projectSettings.resolveShipMode = saved.resolve; api.projectSettings.set = saved.set; };
+  return { route, writes, restore };
+}
+
+test('GET /project-settings/ship-mode is open to any signed-in builder, not gated Metic+', () => {
+  const { route, restore } = buildRouter({ resolved: { mode: 'auto', source: 'default', chosen: false, invalid: null } });
+  try {
+    const names = route('get', '/project-settings/ship-mode').stack.map((l) => l.name);
+    assert.equal(names.length, 2, 'requireBuilder + the handler, and no permission gate');
+    const write = route('patch', '/project-settings/ship-mode').stack;
+    assert.equal(write.length, 3, 'the write carries requireBuilder + the settings permission + the handler');
+  } finally { restore(); }
+});
+
+test('the read returns the mode, whether it was chosen, and the sentence to show', async () => {
+  const { route, restore } = buildRouter({ resolved: { mode: 'auto', source: 'default', chosen: false, invalid: null } });
+  try {
+    const res = fakeRes();
+    const stack = route('get', '/project-settings/ship-mode').stack;
+    await stack[stack.length - 1].handle({}, res);
+    assert.equal(res.payload.mode, 'auto');
+    assert.equal(res.payload.chosen, false);
+    assert.match(res.payload.sentence, /nobody has chosen yet/);
+    assert.deepEqual(res.payload.choices.map((c) => c.mode), ['auto', 'manual']);
+    assert.match(res.payload.choices[0].label, /recommended/i);
+    assert.equal(res.headers['Cache-Control'], 'no-store');
+  } finally { restore(); }
+});
+
+test('the write refuses an unknown mode and saves a good one, echoing what is now read', async () => {
+  const { route, writes, restore } = buildRouter({ resolved: { mode: 'auto', source: 'default', chosen: false, invalid: null } });
+  try {
+    const stack = route('patch', '/project-settings/ship-mode').stack;
+    const handle = stack[stack.length - 1].handle;
+
+    const bad = fakeRes();
+    await handle({ body: { mode: 'sometimes' }, builder: { id: 7 } }, bad);
+    assert.equal(bad.code, 'bad_ship_mode');
+    assert.equal(writes.length, 0, 'a refused mode writes nothing');
+
+    const good = fakeRes();
+    await handle({ body: { mode: 'Manual' }, builder: { id: 7 } }, good);
+    assert.equal(good.code, null);
+    assert.deepEqual(writes, [{ key: 'ship.mode', value: 'manual', by: 7 }]);
+    assert.equal(good.payload.mode, 'manual');
+    assert.equal(good.payload.chosen, true);
+  } finally { restore(); }
+});
+
+// ---- the CLI ----------------------------------------------------------------
+
+test('bongos ship-mode is a registered verb wired to shipping-mode.js', () => {
+  const cli = require(path.join(ROOT, 'bin', 'bongos.js'));
+  const def = cli.VERBS['ship-mode'];
+  assert.ok(def, 'bongos ship-mode must be a registered verb');
+  assert.equal(def.script, 'shipping-mode.js');
+});
+
+test('the CLI text names the mode and how to switch it', () => {
+  const { describe } = require(path.join(ROOT, 'scripts', 'gds', 'shipping-mode.js'));
+  const auto = describe({ mode: 'auto', chosen: false, sentence: 'Auto: …' });
+  assert.match(auto, /Ship mode: auto \(default — not chosen yet\)/);
+  assert.match(auto, /shipping-mode\.js manual/);
+  assert.match(describe({ mode: 'manual', chosen: true }), /shipping-mode\.js auto/);
+});