@bongos/core 1.21.120 → 1.21.122

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/gds/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 2720,
-    "unique_ids": 2300,
-    "certain": 2720,
+    "strings": 2722,
+    "unique_ids": 2302,
+    "certain": 2722,
     "heuristic": 0,
     "duplicate_ids": 240
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 143,
-      "strings": 1912
+      "strings": 1914
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -5091,7 +5091,7 @@
       "surface": "builders-hall",
       "text": "Could not load modules.",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 335,
+      "line": 361,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -5271,7 +5271,7 @@
       "surface": "builders-hall",
       "text": "Could not reach the submit endpoint.",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 314,
+      "line": 340,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -9780,7 +9780,7 @@
       "surface": "builders-hall",
       "text": "Nothing to submit — every module here ships with the core.",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 275,
+      "line": 301,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -17731,6 +17731,15 @@
       "origin": "html-attr:placeholder",
       "confidence": "certain"
     },
+    {
+      "id": "299dd9d33f53",
+      "surface": "builders-hall",
+      "text": "restart it",
+      "file": "modules/hall-ui/public/modules.js",
+      "line": 129,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "58b4e7a48d86",
       "surface": "builders-hall",
@@ -17943,7 +17952,7 @@
       "surface": "builders-hall",
       "text": "submit for review",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 149,
+      "line": 175,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -18550,6 +18559,15 @@
       "origin": "js-markup",
       "confidence": "certain"
     },
+    {
+      "id": "354861d3c2ce",
+      "surface": "builders-hall",
+      "text": "waits for a restart",
+      "file": "modules/hall-ui/public/modules.js",
+      "line": 127,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "35be9e0923da",
       "surface": "builders-hall",
@@ -18861,7 +18879,7 @@
       "surface": "builders-hall",
       "text": "{…} and above can enable or disable a module",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 147,
+      "line": 173,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -19203,7 +19221,7 @@
       "surface": "builders-hall",
       "text": "{…} {…} — how-to",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 390,
+      "line": 416,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -19275,7 +19293,7 @@
       "surface": "builders-hall",
       "text": "{…} — how to use it",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 392,
+      "line": 418,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -19410,7 +19428,7 @@
       "surface": "builders-hall",
       "text": "· version",
       "file": "modules/hall-ui/public/modules.js",
-      "line": 395,
+      "line": 421,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -3077,5 +3077,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.118 with no explicit bump. run 38574092141. (task 1002620)
   1.21.120 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.119 with no explicit bump. run 38597828843. (task 1002620)
+  1.21.121 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.120 with no explicit bump. run 38604777189. (task 1002620)
+  1.21.122 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.121 with no explicit bump. run 38620147259. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/page-readings.json

@@ -1875,7 +1875,7 @@
       "surface": "builders",
       "title": "Modules",
       "states_read": ["browse","search-empty","lens","details","out"],
-      "files_hash": "22c9622ad3cbe0da",
+      "files_hash": "c1d5725a6bf0afe2",
       "reading_hash": "e37d27e205c7ba63",
       "counts": {"lines":48,"placed":19,"shared":8,"unplaced":21},
       "omitted": {"data":76},
@@ -1917,7 +1917,7 @@
         {"key":"L0034","section":"Module catalog","text":"{…} file{…}","placement":"placed","file":"modules/hall-ui/public/gate.js","line":151,"string_id":"3efa67dc6e07"},
         {"key":"L0035","section":"Module catalog","text":"sessions","placement":"placed","file":"modules/hall-ui/public/task.js","line":467,"string_id":"732b4c935e36"},
         {"key":"L0036","section":"Module catalog","text":"Built by this project","placement":"placed","file":"modules/hall-ui/public/modules.html","line":70,"string_id":"b51edc826cbe"},
-        {"key":"L0037","section":"Module catalog","text":"submit for review","placement":"placed","file":"modules/hall-ui/public/modules.js","line":149,"string_id":"0215b2cdca8c"},
+        {"key":"L0037","section":"Module catalog","text":"submit for review","placement":"placed","file":"modules/hall-ui/public/modules.js","line":175,"string_id":"0215b2cdca8c"},
         {"key":"L0038","section":"Module catalog","text":"A module built here can be submitted upstream for review, so it can join the shared catalog with your name and this project credited.","placement":"placed","file":"modules/hall-ui/public/modules.html","line":74,"string_id":"2e17d7e236d9"},
         {"key":"L0039","section":"footer","text":"Sign out","placement":"shared","file":"modules/hall-ui/public/shell.js","line":520,"string_id":"1883ad7f07fc"},
         {"key":"L0040","section":"Module catalog","text":"Builders hall · this session","placement":"placed","file":"modules/hall-ui/public/craft-mode.js","line":810,"string_id":"fd1903586e8e"},
@@ -5129,7 +5129,7 @@
       "surface": "landing",
       "title": "{{productName}} — projects",
       "states_read": ["out-map","in-map","in-map-projects","in-map-profile","in-map-kbd","in-map-search","in-map-mine-on","in-table","in-table-by-builders","in-mine","in-manage","in-manage-address","in-manage-planet","in-manage-card","in-manage-look","in-manage-kind","in-manage-invite","in-manage-invite-handoff","in-manage-invite-guild","in-manage-app-live","in-manage-app-building","in-manage-app-failed","in-manage-app-retry","in-manage-app-offer","in-manage-app-connect","in-manage-snag","in-manage-gone","in-manage-missing","out-manage","in-new","in-new-named","in-new-ready","in-new-name-prefilled","in-new-demo","in-new-demo-used","in-new-checks-filled","in-new-checks-entity","in-new-row-code","in-new-row-address","in-new-row-team","in-new-row-extras","in-new-row-rewards","in-new-row-app","in-new-row-run","in-new-row-ship","in-new-look","in-new-look-custom","in-new-create-blocked","in-new-done","in-new-resume-offer","out-new","out-map-projects","card","card-noart","card-self","in-manage-demo","in-mine-dns-pending","in-manage-dns-pending","in-mine-empty","card-floor","card-backdrop","in-new-done-live","setup-just-created","setup-waiting-on-github","setup-installing","setup-stopped","setup-all-done","setup-cloud-hop-open"],
-      "files_hash": "82d94c8932993dbd",
+      "files_hash": "6c567b2c13fd0fc6",
       "reading_hash": "302909900601b80c",
       "counts": {"lines":825,"placed":246,"shared":21,"unplaced":558},
       "omitted": {"data":150},

package/modules/government/protected-surfaces.json

@@ -71,6 +71,7 @@
     { "glob": "scripts/gds/ship-memory-sync.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-merge-gate.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-merge.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
+    { "glob": "scripts/gds/ship-mode-ask.js", "group": "pipeline", "why": "task 1004630. Split out beside ship.js: the first-ship ask that decides whether a project ships in Auto or Manual mode, so an edit here changes who may start a ship." },
     { "glob": "scripts/gds/ship-preflight-steps.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-regen.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-resume.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
@@ -78,6 +79,7 @@
     { "glob": "scripts/gds/ship-state.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-surprise.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
     { "glob": "scripts/gds/ship-visual.js", "group": "pipeline", "why": "task 1004024. The 2026-08-23 carve of ship.js (task 1003205): the land path, the ship state machine, the grade gate steps, the merge and pushVia, about 6,200 lines behind a 373-line protected entry point." },
+    { "glob": "scripts/gds/ship-mode-ask.js", "group": "pipeline", "why": "task 1004630. Split out of the protected scripts/gds/ship.js beside it: the ship-mode step every ship runs before it lands, so it is protected at ship.js's floor (the 1004024 carve tripwire)." },
     { "glob": "scripts/gds/confirm.js", "group": "pipeline", "why": "the confirm step" },
     { "glob": "scripts/gds/merge-mode.js", "group": "pipeline", "why": "the manual land fallback" },
     { "glob": "scripts/gds/ci-grade.js", "group": "pipeline", "why": "CI grade-gate driver — steers the grade check (ADR 0058)" },

package/modules/hall-ui/public/modules.js

@@ -113,6 +113,32 @@
     return '<span class="fact-pill fact-pill--warn" title="Taken out of the store. Your copy keeps working, but it will get no more updates.">delisted · no more updates</span>';
   }
 
+  // A toggle this server has not acted on yet (task 1004463): routes mount and pollers
+  // start once, at boot, so the change lands at the next restart.
+  // The words are the server's (restartNote in src/bongos/routes/modules.js): 'routes' are
+  // its pages, 'pollers' its background jobs, and only what actually waits is named.
+  function restartFact(m) {
+    const waits = Array.isArray(m.restart_pending) ? m.restart_pending : [];
+    if (!waits.length) return '';
+    const parts = m.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'];
+    const title = `It turns ${m.enabled ? 'on' : 'off'} at the next restart of this server. Until then ${parts.filter(Boolean).join(' and ')}.`;
+    const pill = `<span class="fact-pill fact-pill--warn" title="${escapeHtml(title)}">waits for a restart</span>`;
+    const door = restartDoor();
+    return door ? pill + `<a class="fact-pill" href="${escapeHtml(door)}">restart it</a>` : pill;
+  }
+  // Where this server's Restart button is: only the platform's own hall has one, on its
+  // project page on the hub (task 1004463). Elsewhere whoever runs the server restarts it.
+  function restartDoor() {
+    const hub = window.OTB && typeof window.OTB.hubOrigin === 'function' ? window.OTB.hubOrigin() : null;
+    if (!hub) return null;
+    let hubHost = '';
+    try { hubHost = new URL(hub).hostname; } catch (err) { return null; }
+    const here = String(window.location.hostname || '').replace(/^builders\./, '');
+    return here === hubHost ? `${hub}/projects?view=mine` : null;
+  }
+
   // The lines the row's details disclosure opens onto: the facts the payload
   // carries that the card never rendered — what the module contributes, the
   // core it needs, who maintains it and what it hands off to.
@@ -159,7 +185,7 @@
         <div class="ov-row__main">
           <span class="ov-row__title">${escapeHtml(m.title || m.key)}<span class="ov-mono">${escapeHtml(m.key)}</span></span>
           ${desc ? `<p class="ov-row__sub mod-row__desc">${escapeHtml(desc)}</p>` : ''}
-          <div class="ov-row__facts">${provenancePill(m)}${attributionFacts(m)}${upkeepFact(m)}${howtoFact(m)}${delistedFact(m)}</div>
+          <div class="ov-row__facts">${provenancePill(m)}${attributionFacts(m)}${upkeepFact(m)}${howtoFact(m)}${delistedFact(m)}${restartFact(m)}</div>
           ${lines ? `<details class="mod-more"${openKeys.has(m.key) ? ' open' : ''}><summary aria-label="Details for ${escapeHtml(m.title || m.key)}"></summary>${lines}</details>` : ''}
         </div>
         <div class="ov-row__right mod-row__right">${rightHtml(m)}</div>
@@ -289,13 +315,13 @@
       const body = res.data || {};
       if (!res.ok) throw new Error(body.message || `enable → ${res.status}`);
       const m = allModules.find((x) => x.key === key);
-      if (m) m.enabled = next;
+      if (m) { m.enabled = next; if (Array.isArray(body.restart_pending)) m.restart_pending = body.restart_pending; }
       btn.setAttribute('aria-pressed', next ? 'true' : 'false');
       btn.textContent = next ? 'enabled' : 'disabled';
       const figs = $('#mod-figs');
       if (figs) figs.innerHTML = figsHTML();
       renderRows();
-      toast(body.note || (next ? `${key} enabled.` : `${key} disabled.`), { duration: 3200 });
+      toast(body.note || (next ? `${key} enabled.` : `${key} disabled.`), { duration: body.restart_pending && body.restart_pending.length ? 7000 : 3200 });
     } catch (err) {
       console.error('[modules] toggle failed', err);
       toast(err.message || 'Could not change that module.', { duration: 3200 });

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

@@ -58,6 +58,21 @@ function shipModeRow(resolved) {
   };
 }
 
+// callerHolds(builderId, atom) → true | false | null. null means authority could
+// not be established (government port missing or the resolver threw); a reader
+// treats that as unknown, never as a grant.
+async function callerHolds(builderId, atom) {
+  try {
+    const government = api.resolveOptional('government');
+    if (!government || typeof government.resolveBuilderPermissions !== 'function') return null;
+    const held = (await government.resolveBuilderPermissions(builderId)) || [];
+    return held.includes(atom);
+  } catch (err) {
+    log.error(`ship-mode can_change: ${err && err.message}`);
+    return null;
+  }
+}
+
 // --- the three rows that are READ, never written -----------------------------
 //
 // Each names the committed artefact it resolves from, because "you cannot edit this"
@@ -348,12 +363,18 @@ module.exports = function buildProjectSettingsRouter() {
   // 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.
+  //
+  // can_change (task 1004630): whether THIS caller holds project.settings.manage,
+  // so the first-ship question is put only to someone who can answer it. null when
+  // authority could not be established; the CLI then asks, and a refused save lets
+  // the ship go on. Cosmetic only — the PATCH below keeps its own gate (ADR 0016).
   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 });
+      const canChange = req.builder ? await callerHolds(req.builder.id, 'project.settings.manage') : null;
+      res.json({ mode: resolved.mode, chosen: resolved.chosen, source: resolved.source, sentence: row.sentence, choices: row.choices, can_change: canChange });
     } catch (err) {
       log.error(`GET /project-settings/ship-mode: ${err && err.message}`);
       res.fail('project_settings_read_failed', { status: 500, message: 'internal error' });

package/modules/provisioning/provisioning.js

@@ -123,9 +123,11 @@ const SETTINGS_APPLY_SHAPES = new Set(['co-tenant', 'cloud-host', 'control-plane
 // SETTINGS_APPLY_FROM: each action declaring its own gate is this module's
 // convention, and the two answer different questions.
 const RESTART_FROM = new Set(['active']);
-// Same reachability rule as the settings push (the runner can only restart what it runs),
-// minus 'control-plane': task 1004334 gave the self row a settings push, not a restart door.
-const RESTART_SHAPES = new Set(['co-tenant', 'cloud-host']);
+// Same reachability rule as the settings push (the runner can only restart what it runs).
+// 'control-plane' joined in task 1004463: a module toggled in its hall takes effect only at
+// the next restart, the guard already allows 'restart' on the self row, and the owner's only
+// other way was a shell on the box.
+const RESTART_SHAPES = new Set(['co-tenant', 'cloud-host', 'control-plane']);
 
 // Per-project settings (task 1003040, goal 1000058): the known keys + their
 // vocabularies, enforced at the API layer — the jsonb `settings` column

package/modules/public-landing/public/projects.html

@@ -8541,9 +8541,11 @@ summary{min-height:24px;padding:3px 0;}
      last_verified_up === false is the verdict; null means never probed and is
      deliberately NOT the same claim (publicInstance keeps the two apart), so a
      brand-new project never grows a Restart button it has no use for. A door on
-     every healthy card would only invite needless downtime. */
+     every healthy card would only invite needless downtime. The ONE exception is the
+     platform's own row (task 1004463): a module switched on or off in its hall waits for
+     a restart, so its owner always has the door. */
   function canRestart(inst) {
-    return inst.status === 'active' && inst.last_verified_up === false && !inst.open_intent;
+    return inst.status === 'active' && !inst.open_intent && (inst.last_verified_up === false || inst.hosting_shape === 'control-plane');
   }
   /* keep watching while the platform is doing something to this instance */
   function shouldWatch(inst) {

package/package-lock.json

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

package/package.json

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

@@ -9702,5 +9702,17 @@
       "id": "1004410",
       "text": "The new-project page no longer says GitHub sign-in is unfinished when it already works: the platform now checks the project itself and ticks the step."
     }
+  ],
+  "1.21.121": [
+    {
+      "id": "1004463",
+      "text": "Turning a module on or off now says honestly when it takes effect at the next restart, and the platform's own server can be restarted from its project page instead of needing a login to the machine."
+    }
+  ],
+  "1.21.122": [
+    {
+      "id": "1004630",
+      "text": "If a project never picked a ship mode, its next ship now pauses once and asks: Auto (recommended) or Manual. The answer is saved for the whole project and it never asks again. People who cannot change project settings, and una"
+    }
   ]
 }

package/scripts/gds/exec-path-guard.js

@@ -91,7 +91,7 @@ const EXEMPTIONS = [
        + 're-opens for review.',
   },
   {
-    at: 'src/module-loader/loader.js:196',
+    at: 'src/module-loader/loader.js:198',
     why: 'The plugin loader, and the second site the audit named (B50 "motivating sites"). It '
        + 'require()s a discovered module\'s route file, so the specifier is a runtime path BY '
        + 'DESIGN — a plugin system whose module paths are compile-time constants is not a plugin '
@@ -103,7 +103,7 @@ const EXEMPTIONS = [
        + 'absorbed into this check.',
   },
   {
-    at: 'src/module-loader/loader.js:309',
+    at: 'src/module-loader/loader.js:347',
     why: 'The poller twin of the route require at :196 — same DEFAULT_ROOTS bound, same plugin-by-'
        + 'design rationale, same ADR 0107 / task 1003400 follow-on. Listed on its own line so a '
        + 'change to either call re-opens only that one.',

package/scripts/gds/provision.js

@@ -927,8 +927,10 @@ async function settingsApplyInstance(inst, deps) {
 // ---------------------------------------------------------------------------
 async function restartInstance(inst, deps) {
   const { db, provisioning, exec, log, apply, privileged } = deps;
-  // Same box routing as settingsApplyInstance: a standalone runs control-plane-local.
-  const boxExec = inst.hosting_shape === 'cloud-host' ? (deps.controlExec || exec) : exec;
+  // Same box routing as settingsApplyInstance: a standalone runs control-plane-local, and the
+  // control plane's own row IS this box (task 1004463).
+  const onControlBox = inst.hosting_shape === 'cloud-host' || inst.hosting_shape === 'control-plane';
+  const boxExec = onControlBox ? (deps.controlExec || exec) : exec;
   const sudoP = privileged ? 'sudo ' : '';
   log(`restart ${inst.slug} (shape=${inst.hosting_shape}, status=${inst.status})`);
 

package/scripts/gds/ship-flow.js

@@ -8,7 +8,9 @@
 
 'use strict';
 
-const { cliClient, requireSession, arg, detectWorktreeName, cardFlagsFromMe } = require('./cli-lib');
+const { cliClient, requireSession, arg, detectWorktreeName, cardFlagsFromMe, apiCall, cliExit } = require('./cli-lib');
+// task 1004630: the first ship asks for the ship mode once (ADR 0369).
+const { runFirstShipAsk } = require('./ship-mode-ask.js');
 const { resolveProse, markShipProgress, smokeGateMessages, proseFlagPresent, regradeNotesRefusal, staleSummaryNotice } = require('./ship-honesty.js');
 const { plainCardLines } = require('./plain-cards.js');
 const { classifyEmptyShip } = require('../../modules/lifecycle/ship-preflight');
@@ -42,7 +44,7 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--visual <image>] [--visual-alt "caption"] [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--visual <image>] [--visual-alt "caption"] [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>] [--ship-mode auto|manual]');
     console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
     process.exit(2);
   }
@@ -157,6 +159,24 @@ async function shipMain() {
     process.exit(1);
   }
 
+  // ---- First ship asks for the ship mode, once (task 1004630, ADR 0369) ----
+  // A project that never chose Auto or Manual stops HERE, before anything resolves,
+  // so the AI can ask the person; the re-run carries --ship-mode and saves it. Never
+  // blocks a ship nobody can answer for (see ship-mode-ask.js).
+  const firstShip = await runFirstShipAsk({
+    args,
+    getShipMode: async () => {
+      const r = await apiCall('GET', '/api/bongos/project-settings/ship-mode');
+      return r.ok ? r.data : null;
+    },
+    saveShipMode: (mode) => apiCall('PATCH', '/api/bongos/project-settings/ship-mode', { mode }),
+  });
+  if (firstShip.stop) {
+    for (const line of firstShip.lines) console.log(line);
+    cliExit(firstShip.exit);
+    return;
+  }
+
   // ---- Hard cap: refuse to ship over the monthly budget (V3.R84 #302, C3) ----
   // Shipping runs the subagent grader, which spends API $. If this builder is at
   // or over their monthly budget, refuse here — BEFORE the grader runs and BEFORE

package/scripts/gds/ship-mode-ask.js

@@ -0,0 +1,138 @@
+// scripts/gds/ship-mode-ask.js — the first-ship ship-mode question (task 1004630, ADR 0369).
+//
+// WHY. Ship mode says who starts a ship: Auto (the AI ships on its own) or Manual
+// (a person approves each ship). The creation wizard asks for it (task 1004629),
+// but a project made before that step, or by `bongos init`, never answered. Such a
+// project quietly runs on the default, so its owner never learns there was a choice.
+// This asks ONCE, at the next ship, and saves the answer. Once saved the mode reads
+// as chosen and the question never comes back.
+//
+// HOW. The ship stops BEFORE anything resolves (the claim stays active) and prints
+// an ask the AI turns into a two-option question for the person. The AI re-runs the
+// same ship with `--ship-mode auto|manual`; that saves the answer and the ship goes on.
+//
+// It never blocks a ship it cannot get an answer for. The ship goes on with the
+// default, and nobody is asked, when:
+//   - the mode could not be read (the resolver's own posture: a ship is never
+//     blocked by a settings read);
+//   - the caller cannot change project settings (only an owner-side builder can
+//     answer, so asking a teammate would stop every ship of theirs for nothing);
+//   - nobody is there to answer (an Autobongos worker or a subagent).
+//
+// The decision is pure (shipModeAskVerdict) so tests prove it with no network.
+
+'use strict';
+
+// The ship exits with this code when it stops to ask. Distinct from 1 (failure)
+// and 2 (usage), and from the grade cap's 6, so a wrapper can tell "a question is
+// waiting" from "something broke".
+const ASK_EXIT = 5;
+
+const ASK_MARKER = '[otb-ask-ship-mode]';
+
+// unattended(env) — true when no person is there to answer.
+// OTB_SUBAGENT is set on every Autobongos worker (scripts/gds/autobongos-run.js
+// workerEnv); AUTOBONGOS_GRADE_LEDGER is set only by that supervisor.
+function unattended(env = process.env) {
+  return env.OTB_SUBAGENT === '1' || Boolean(env.AUTOBONGOS_GRADE_LEDGER);
+}
+
+// shipModeFlag(args) — the --ship-mode answer, or null when absent.
+// { mode } for auto|manual, { bad } for any other value (the ship refuses it).
+function shipModeFlag(args) {
+  const i = args.indexOf('--ship-mode');
+  if (i === -1) return null;
+  const raw = String(args[i + 1] || '').trim().toLowerCase();
+  if (raw === 'auto' || raw === 'manual') return { mode: raw };
+  return { bad: raw || '(missing)' };
+}
+
+// shipModeAskVerdict({ shipMode, flag, unattended }) →
+//   { action: 'proceed', why }   — nothing to ask; ship on
+//   { action: 'save', mode }     — the person answered; save it, then ship on
+//   { action: 'ask' }            — stop and ask
+// shipMode is the GET /project-settings/ship-mode body, or null when unreadable.
+// can_change is absent on a server older than this task; absent means "unknown",
+// and unknown asks (a refused save then lets the ship go on, see saveFailureLines).
+function shipModeAskVerdict({ shipMode, flag, unattended: alone }) {
+  if (!shipMode) return { action: 'proceed', why: 'unreadable' };
+  if (shipMode.chosen) return { action: 'proceed', why: 'chosen' };
+  if (flag && flag.mode) return { action: 'save', mode: flag.mode };
+  if (shipMode.can_change === false) return { action: 'proceed', why: 'cannot_change' };
+  if (alone) return { action: 'proceed', why: 'unattended' };
+  return { action: 'ask' };
+}
+
+// askLines(shipMode, argv) — what the ship prints when it stops to ask. The first
+// lines are for the AI; the choices are the server's own words, so the question a
+// person sees matches the settings page.
+function askLines(shipMode, argv) {
+  const choices = (shipMode && Array.isArray(shipMode.choices) && shipMode.choices.length)
+    ? shipMode.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.' },
+    ];
+  const rerun = ['node', 'scripts/gds/ship.js', ...argv.filter((a, i) => a !== '--ship-mode' && argv[i - 1] !== '--ship-mode')]
+    .map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return [
+    `${ASK_MARKER} This project has never chosen a ship mode, so this first ship asks once.`,
+    'Ask the person this question with two options, Auto first, then re-run this ship with their answer:',
+    '',
+    '  How should finished work ship on this project?',
+    ...choices.map((c) => `    - ${c.label}: ${c.sentence}`),
+    '',
+    `  Re-run:  ${rerun} --ship-mode auto|manual`,
+    '',
+    'Nothing was resolved: the claim is still active. The answer is saved for the',
+    'whole project and can be changed later on the project settings page.',
+  ];
+}
+
+// saveFailureLines(status) — a refused or failed save never blocks the ship. The
+// default (Auto) applies, and the person learns who can set it.
+function saveFailureLines(status) {
+  const who = status === 403
+    ? 'Only the project owner (or someone with project settings access) can set the ship mode,'
+    : `The ship mode could not be saved (${status || 'no response'}),`;
+  return [
+    `${who} so this ship goes on with the default, Auto.`,
+    'It can be set later on the project settings page, or with: node scripts/gds/shipping-mode.js auto|manual',
+  ];
+}
+
+// runFirstShipAsk({ args, getShipMode, saveShipMode, env, log }) — the side-effect
+// half shipMain calls once it knows this is a real ship. Returns
+// { stop: true, lines } when the ship must stop and ask, else { stop: false }.
+// getShipMode() → body or null; saveShipMode(mode) → { ok, status, data }.
+async function runFirstShipAsk({ args, getShipMode, saveShipMode, env = process.env, log = console.log }) {
+  const flag = shipModeFlag(args);
+  if (flag && flag.bad) {
+    return { stop: true, exit: 2, lines: [`--ship-mode must be auto or manual (got ${flag.bad}). Nothing was resolved: the claim is still active.`] };
+  }
+  let shipMode = null;
+  try { shipMode = await getShipMode(); } catch (_) { shipMode = null; }
+  const verdict = shipModeAskVerdict({ shipMode, flag, unattended: unattended(env) });
+  if (verdict.action === 'ask') return { stop: true, exit: ASK_EXIT, lines: askLines(shipMode, args) };
+  if (verdict.action === 'save') {
+    let r = null;
+    try { r = await saveShipMode(verdict.mode); } catch (_) { r = null; }
+    if (r && r.ok) {
+      log(`Ship mode saved: ${verdict.mode}. ${(r.data && r.data.sentence) || ''}`.trim());
+    } else {
+      for (const line of saveFailureLines(r && r.status)) log(line);
+    }
+  }
+  return { stop: false };
+}
+
+module.exports = {
+  ASK_EXIT,
+  ASK_MARKER,
+  unattended,
+  shipModeFlag,
+  shipModeAskVerdict,
+  askLines,
+  saveFailureLines,
+  runFirstShipAsk,
+};

package/scripts/gds/ship.js

@@ -50,6 +50,12 @@
 //                                                       # game-surface diffs are otherwise staged to
 //                                                       # the builder's own local preview (ADR 0044) for
 //                                                       # a browser review BEFORE the claim resolves.
+//   node scripts/gds/ship.js <task-id> --ship-mode auto|manual
+//                                                       # answer the first-ship question (task 1004630,
+//                                                       # ADR 0369): a project that never chose a ship
+//                                                       # mode stops once, before anything resolves, and
+//                                                       # exits 5 with an ask; the re-run with the answer
+//                                                       # saves it for the whole project and ships on.
 //   node scripts/gds/ship.js <task-id> --approved      # record your sandbox sign-off (#1048): re-run with
 //                                                       # this AFTER reviewing the staged change at the
 //                                                       # sandbox URL. Persists a sandbox_review row on the

package/src/bongos/module-scope-map.js

@@ -109,9 +109,11 @@ const MODULE_GLOBS = {
     'scripts/gds/ship-finish.js', 'scripts/gds/ship-flow.js', 'scripts/gds/ship-git.js',
     'scripts/gds/ship-grade-steps.js', 'scripts/gds/ship-grade.js', 'scripts/gds/ship-honesty.js',
     'scripts/gds/ship-io.js', 'scripts/gds/ship-land.js', 'scripts/gds/ship-memory-sync.js',
-    'scripts/gds/ship-merge-gate.js', 'scripts/gds/ship-merge.js', 'scripts/gds/ship-preflight-steps.js',
+    'scripts/gds/ship-merge-gate.js', 'scripts/gds/ship-merge.js', 'scripts/gds/ship-mode-ask.js',
+    'scripts/gds/ship-preflight-steps.js',
     'scripts/gds/ship-regen.js', 'scripts/gds/ship-resume.js', 'scripts/gds/ship-session-upload.js',
     'scripts/gds/ship-state.js', 'scripts/gds/ship-surprise.js', 'scripts/gds/ship-visual.js',
+    'scripts/gds/ship-mode-ask.js', // task 1004630
     'scripts/gds/merge-mode.js', 'scripts/gds/confirm.js', 'scripts/gds/main-audit.js',
     'scripts/gds/gate-review.js', 'scripts/gds/push-main.js', 'scripts/gds/ci-grade.js',
     'scripts/gds/merge-lock.js', 'scripts/gds/version-close.js',