@bongos/core 1.21.121 → 1.21.122

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.121",
-  "core_contract": "1.21.121",
-  "source_commit": "514ed742253be1dacb6b1d18d49f2f6fa3f6b427",
+  "core_version": "1.21.122",
+  "core_contract": "1.21.122",
+  "source_commit": "1744caf4412e029c7cf9b465a9fae581bc2deea7",
   "source_ref": "HEAD",
-  "built_at": "2026-10-14T17:15:08.661Z",
+  "built_at": "2026-10-14T19:02:19.295Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 605,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3118,
+    "functional_verbatim": 3120,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3752,
-  "tree_sha256": "49b303e76f9a422c8c0b909fe0ee46687b713859b18104045df85b7ef48fa505",
+  "file_count": 3754,
+  "tree_sha256": "df175c2d7b99fee7204cf032575b41a9fa13988b1a3635717568822cf1d84d6b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -107,7 +107,7 @@
     {
       "path": ".claude/skills/builder-ship/SKILL.md",
       "mode": "0000644",
-      "sha256": "9a646bdb323e8e22d7e65b4e721ee2ffe717b9b83006f2bf8fcec5db8614ae43"
+      "sha256": "1053b6160f72c6f78d9608b8431ba59b707fb310493fdb24ea52efd52f1ef825"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -337,7 +337,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "493cebcc4535646738cfda7d3df73ba9895e7e88c3c268d62cca55420aebab29"
+      "sha256": "c13884fb0bd175f8bc9745150b2ca5ed254dd0ad14bcaa63511cf892cdbaec36"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -2307,7 +2307,7 @@
     {
       "path": "docs/adr/0369-ship-mode-decides-who-starts-a-ship-not-how-it-lands.md",
       "mode": "0000644",
-      "sha256": "9a5d9de0e7895a66d5515a453beca25d4839e7f93ef4dd0cd60524239ab005ee"
+      "sha256": "a0dba98c2dfe34ed6110f2d813fef346ad8adf7430f2b7ab4da38be72c37f7c8"
     },
     {
       "path": "docs/adr/0370-a-repo-we-create-is-private.md",
@@ -2382,7 +2382,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "1504a1bc002e033dd4c69c55a074014b35f88fe0015746911ac69e02cff4a430"
+      "sha256": "b8d8cae75596996b38203b5b73b8fc4f5cfc4afa8fa6a170541131fdfed924ea"
     },
     {
       "path": "docs/architecture.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "24cea3fdb2f8e21b6358090612695e37c03e734fcd305e87d35456fa8a515adf"
+      "sha256": "05a2ac9355a782e35f6af18287d0395ece73a55b0541f680106c250d1f604b63"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5297,7 +5297,7 @@
     {
       "path": "modules/government/protected-surfaces.json",
       "mode": "0000644",
-      "sha256": "f7b6342000bd9f49d9747e2e02056060ad5aeda074424fbba586cd8bc1ef6bd2"
+      "sha256": "9aedf10b3cb611343baf96662e6f79d45ed2218b83abfb3ad8c03536c722d37c"
     },
     {
       "path": "modules/government/ranks.js",
@@ -7622,7 +7622,7 @@
     {
       "path": "modules/lifecycle/routes/project-settings.js",
       "mode": "0000644",
-      "sha256": "ff31bc1e4dbfec3026e250beaf8d5f4bdfc02b39cee616be1bb36ddc74b6f11b"
+      "sha256": "67d28a56701e45e176236fc0eae3ece9e349cc5c7b61cf6e7b8267afe304ade5"
     },
     {
       "path": "modules/lifecycle/routes/recommendations.js",
@@ -10467,12 +10467,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4fbad4e149e09def5dfaf46fb9069c0298871200c54d8836c61efdf527e14038"
+      "sha256": "0698dfed8aaee5032ad705115bcbc515cc7328a78c31a30018a2e2f5df0cf1ca"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7107e720fbe7a367451fb610dcccac24f7563e1a50b898bf1899b76afc53fd6f"
+      "sha256": "aefc81df15571d208d96577a7ade7189f1d1e064ae9a1af132b0725f871fcb40"
     },
     {
       "path": "public-docs/index.html",
@@ -10492,7 +10492,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "7818da891dbc2d601d13dc938d43d83f49061084ed93fef83fe6d4479c98f828"
+      "sha256": "43b16f9fbd2c3834c02bd141ce4b9e737003d1c42112e6cb607e7a118e29e7dd"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -11997,7 +11997,7 @@
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "ad768320095b1d6693e6da5cee1f8e857ac69cbbfbea0a64dfeaa7092c432de2"
+      "sha256": "bb8edf9166b1c452b87d75e009d7404758bcba6ea58aa9011848ec44e761bb52"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -12044,6 +12044,11 @@
       "mode": "0000644",
       "sha256": "8d37d5c6cbaa1ca0e8363fab6c34159d1e16922fdae11d4ffc17b4d9e2c7f795"
     },
+    {
+      "path": "scripts/gds/ship-mode-ask.js",
+      "mode": "0000644",
+      "sha256": "7a489ea223b4fa1d7a3b4ee1076c9a0cb65d6d929e9a5a6e0b8e403e15266afc"
+    },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
       "mode": "0000644",
@@ -12082,7 +12087,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "96bda284d66eb2428bbd05d359143fb6090fe6ce51bc2deca0a47590a8f392ca"
+      "sha256": "9f00804212ef485fd8cfd02be19cddb4be2570a34aa2a284f237940aff17753e"
     },
     {
       "path": "scripts/gds/shipping-mode.js",
@@ -12562,7 +12567,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "67711bf6dd6becd1edeb6866279a788fd6360a51d013eed77f2592be0aaab01b"
+      "sha256": "1b0cec97fbdf2c14f48354741f5537a7db3dbc947e7b7182eb2aa9173cfa00dc"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -12802,7 +12807,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "0ebfd076b4e28ae56b54b3bdc1f43d1f4ee3e74391b4b28600de50f653ee097c"
+      "sha256": "d49bdec14177f77cd4e6dd63ac2532a095565373c0948d9d7b91c809e4e3e6f3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -14992,7 +14997,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "3f002c9669af99cba90480163e1040604ec77b53583a779c0ef81ee75dd02547"
+      "sha256": "3518806d6b065029677e77a242604b6dc85bfd28537c2d109dacaedd29ac6d49"
     },
     {
       "path": "tests/government_rank_sync.mjs",
@@ -17939,6 +17944,11 @@
       "mode": "0000644",
       "sha256": "aee20a5f6e2998d18f605b91d1eb1019e8ada824135759b29633caa3153d9255"
     },
+    {
+      "path": "tests/ship_mode_first_ship.mjs",
+      "mode": "0000644",
+      "sha256": "361d6c7a364c0c1f6fb8266f887fe25fc357250e4585b438fdbf3fb3fafa6849"
+    },
     {
       "path": "tests/ship_post_land_verify.mjs",
       "mode": "0000644",

package/.claude/skills/builder-ship/SKILL.md

@@ -83,6 +83,8 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
    `--notes-file` is refused rather than resolved by precedence, so nothing you
    wrote is dropped without a word.
 
+   **If the ship stops with `[otb-ask-ship-mode]` (exit 5), ask the person, once** (task 1004630, [ADR 0369](../../../docs/adr/0369-ship-mode-decides-who-starts-a-ship-not-how-it-lands.md)). The project never chose who starts a ship, so its first ship asks. Nothing has resolved and the claim is still active. Put the question to the person with your question tool if you have one — two options, **Auto (recommended)** first, then **Manual**, each with the one-line meaning the ship printed — and re-run the exact command it printed with `--ship-mode auto` or `--ship-mode manual`. That saves the answer for the whole project and the ship carries on; it never asks again. Never answer it yourself: the choice is the owner's. An unattended run is never asked (it ships on the default, Auto).
+
    **Never merge a task branch to main before running `ship.js`.** `ship.js` diffs the claim branch against `main`; an already-merged branch yields an empty diff, and the only exits are `--allow-empty` (dead-ends the task at `completed`, requiring an Archon-only confirm) or reverting the merge. Ship from the branch, then let `ship.js` land it. (This trap was hit on tasks 1002417 and 1002419, producing blockers 1000081/1000082 and an ~8.5-hour stall.)
 
 5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**

package/clients/bongos-client/index.d.ts

@@ -129,7 +129,7 @@ export interface GetPageNotesSiteResponse { notes: unknown }
 export interface GetProfilesHandleResponse { account: unknown; cross_project: unknown }
 export interface GetProjectManageLinkResponse { ok: boolean; link: unknown }
 export interface GetProjectSettingsResponse { rows: unknown }
-export interface GetProjectSettingsShipModeResponse { mode: unknown; chosen: unknown; source: unknown; sentence: unknown; choices: unknown }
+export interface GetProjectSettingsShipModeResponse { mode: unknown; chosen: unknown; source: unknown; sentence: unknown; choices: unknown; can_change: unknown }
 export interface GetProjectsFeaturedResponse { projects: unknown; page: PageInfo }
 export interface GetProjectsResponse { projects: unknown }
 export interface GetProvisioningFleetResponse { instances: unknown; capacity: unknown }

package/docs/adr/0369-ship-mode-decides-who-starts-a-ship-not-how-it-lands.md

@@ -33,7 +33,7 @@ It lives in `project_settings` (migration `core_231`), so it needs no migration.
 
 - This task adds the setting only. Behaviour follows in the dependent tasks:
   - the creation wizard asks for it (task 1004629);
-  - the first ship asks once if nobody has chosen (task 1004630);
+  - the first ship asks once if nobody has chosen (task 1004630). The ship stops before anything resolves and exits 5 with an `[otb-ask-ship-mode]` ask; the AI puts the two choices to the person and re-runs with `--ship-mode auto|manual`, which saves the answer. It never asks a caller who cannot change settings (`can_change` on the read), an unattended run, or when the mode cannot be read; those ship on the default;
   - the AI obeys it (task 1004631).
 - **How the wizard's answer reaches the project (task 1004629).** The wizard runs on the platform, and the new project's database is out of its reach. So the answer travels the way the founding marker does: the platform keeps it on the new project's record, sends it to the project at startup, and the project reads it as a *chosen* mode (`source: 'wizard'`) only while its own setting is unset. The settings page and the CLI write that setting, so a later change always wins. Nothing is written into the project's database on its behalf.
 - A database read failure answers Auto rather than blocking a ship. That matches the setting's default, and blocking would be the worse outcome for a person mid-task.

package/docs/api/openapi.json

@@ -16489,7 +16489,7 @@
           "project-settings"
         ],
         "summary": "GET /project-settings/ship-mode",
-        "description": "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.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "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. 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).\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/lifecycle/routes/project-settings.js",
         "responses": {
@@ -27665,14 +27665,16 @@
           "chosen": {},
           "source": {},
           "sentence": {},
-          "choices": {}
+          "choices": {},
+          "can_change": {}
         },
         "required": [
           "mode",
           "chosen",
           "source",
           "sentence",
-          "choices"
+          "choices",
+          "can_change"
         ]
       },
       "GetProjectsFeaturedResponse": {

package/docs/module-api-changelog.md

@@ -3079,5 +3079,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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/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/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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.121",
+  "version": "1.21.122",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.121",
+      "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.121",
+  "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

@@ -9708,5 +9708,11 @@
       "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/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',

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.121'; // 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/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/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);
+});