@bongos/core 1.21.121 → 1.21.123

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.123",
+  "core_contract": "1.21.123",
+  "source_commit": "bfe95a4e390577d4579a3da16d81d5ada6bc8b9a",
   "source_ref": "HEAD",
-  "built_at": "2026-10-14T17:15:08.661Z",
+  "built_at": "2026-10-14T19:30:01.919Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 605,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3118,
+    "functional_verbatim": 3122,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3752,
-  "tree_sha256": "49b303e76f9a422c8c0b909fe0ee46687b713859b18104045df85b7ef48fa505",
+  "file_count": 3756,
+  "tree_sha256": "c5becc4dfe0e822803424a46f1041b66adce70cbe65f85be941603de3db80cee",
   "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": "bac025cc3ff28c70baf2de467e271bdb23fab1f3cf61100381efbc835f88a952"
     },
     {
       "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": "f2b2bf656d2fa819a7bd0f10ceb966b5414c1c06f05f2e8ccaa9ed326a7227ed"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5297,7 +5297,7 @@
     {
       "path": "modules/government/protected-surfaces.json",
       "mode": "0000644",
-      "sha256": "f7b6342000bd9f49d9747e2e02056060ad5aeda074424fbba586cd8bc1ef6bd2"
+      "sha256": "3f7f0bd81b70a995464993a084d35951c3d98b927d0d02fbe97f84105cbdd89f"
     },
     {
       "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": "e92fbdef629a9283a773d94986531ae9d30412fe05dc3012dd918be8fb859030"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7107e720fbe7a367451fb610dcccac24f7563e1a50b898bf1899b76afc53fd6f"
+      "sha256": "cf96b6c94e06d4306f0b3e3c0626c051729a0498bd3e6760012ce86350286d16"
     },
     {
       "path": "public-docs/index.html",
@@ -10492,7 +10492,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "7818da891dbc2d601d13dc938d43d83f49061084ed93fef83fe6d4479c98f828"
+      "sha256": "86c4edcb22bf8005ac7f4e479a9b4037d2bdad36618ed1e8f739a3a786952344"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10812,12 +10812,12 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "1d141943f8367b8814e5a455c0c5d68a3915ac802df6cae9c3550f0628dbc384"
+      "sha256": "eed7d9f195a2197d19bff7e1ebb61562a386db6bdda805db10f970afdf46b2fa"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
       "mode": "0000644",
-      "sha256": "7659039447e370fe143327a8e55a730781d035fe6831e2af895288680ac5334f"
+      "sha256": "d8560389c6a72cda1f7fe958af67b943e825b68fdd8f0fa28bf9143e42a1ece9"
     },
     {
       "path": "scripts/gds/cleanup-orphans.js",
@@ -11997,7 +11997,7 @@
     {
       "path": "scripts/gds/ship-flow.js",
       "mode": "0000644",
-      "sha256": "ad768320095b1d6693e6da5cee1f8e857ac69cbbfbea0a64dfeaa7092c432de2"
+      "sha256": "d944906397fc7936701bd36f3896a418829acf385c70a7ccaef07bd6cc348e91"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -12044,6 +12044,16 @@
       "mode": "0000644",
       "sha256": "8d37d5c6cbaa1ca0e8363fab6c34159d1e16922fdae11d4ffc17b4d9e2c7f795"
     },
+    {
+      "path": "scripts/gds/ship-mode-ask.js",
+      "mode": "0000644",
+      "sha256": "7a489ea223b4fa1d7a3b4ee1076c9a0cb65d6d929e9a5a6e0b8e403e15266afc"
+    },
+    {
+      "path": "scripts/gds/ship-mode-manual.js",
+      "mode": "0000644",
+      "sha256": "077ab61bd14d0a5c8b4012103dd7289ba29a6a7d1ac3420ad401a7d6ef365597"
+    },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
       "mode": "0000644",
@@ -12082,7 +12092,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "96bda284d66eb2428bbd05d359143fb6090fe6ce51bc2deca0a47590a8f392ca"
+      "sha256": "44f7161514392afb04a9165086a1fcc12e1f231d3a641220409ffe0c4ae2c9a2"
     },
     {
       "path": "scripts/gds/shipping-mode.js",
@@ -12222,7 +12232,7 @@
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
-      "sha256": "f6b0d78ff92c9962b158bc5b36bae021c63fcc24095c7b10866f1505ee3f5232"
+      "sha256": "66bed9292a4f5ec70b15ba29a94abec5ed8c69891a5b674a030002844275880c"
     },
     {
       "path": "scripts/gds/update-sweep.js",
@@ -12257,7 +12267,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "f4f158948ab880ceee1cf745ba0071983054c20deba885fed735b7828fe7c1ca"
+      "sha256": "d55d4ba8c8b7d3abedbae59c28a9b1ef9c7021ccc214c6917d1a042c84019d25"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -12562,7 +12572,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "67711bf6dd6becd1edeb6866279a788fd6360a51d013eed77f2592be0aaab01b"
+      "sha256": "5def34a161ca00980bf8a68d4273f3183fdd7269f9b83c61e62e82c154ba881d"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -12802,7 +12812,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "0ebfd076b4e28ae56b54b3bdc1f43d1f4ee3e74391b4b28600de50f653ee097c"
+      "sha256": "01bc6b541cf12105be05701170377582f537316fe3f70fdea2681bae07864bf7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13617,7 +13627,7 @@
     {
       "path": "tests/cli_allowlist_permissions.mjs",
       "mode": "0000644",
-      "sha256": "ce1d4031bf29064a8522440116e4da5dde78ffd59eb0c396b5d32a72790a260a"
+      "sha256": "92bad4d5a6f224b0764bab5e7f906a0990c60f7fab75c5977ce64ba9e9b08b44"
     },
     {
       "path": "tests/cli_dispatcher.mjs",
@@ -14992,7 +15002,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "3f002c9669af99cba90480163e1040604ec77b53583a779c0ef81ee75dd02547"
+      "sha256": "72fc7970c987dbb78120575546aed5faeb9e55342b68e6ba1668508927a9f103"
     },
     {
       "path": "tests/government_rank_sync.mjs",
@@ -17939,6 +17949,16 @@
       "mode": "0000644",
       "sha256": "aee20a5f6e2998d18f605b91d1eb1019e8ada824135759b29633caa3153d9255"
     },
+    {
+      "path": "tests/ship_mode_first_ship.mjs",
+      "mode": "0000644",
+      "sha256": "361d6c7a364c0c1f6fb8266f887fe25fc357250e4585b438fdbf3fb3fafa6849"
+    },
+    {
+      "path": "tests/ship_mode_hands_off.mjs",
+      "mode": "0000644",
+      "sha256": "78f05df6119d9637994f628f3968eefff34aea8a04d28eaa899acc5a238ce154"
+    },
     {
       "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).**
@@ -104,6 +106,7 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
 
 ## Constraints
 
+- **Check the ship mode before you ship** (`node scripts/gds/shipping-mode.js`, task 1004631, [ADR 0369](../../../docs/adr/0369-ship-mode-decides-who-starts-a-ship-not-how-it-lands.md)). In **Auto** you run the ship yourself — never hand the person `cd …` and a ship command to type; a permission refusal on the ship command is a missing allow-rule to fix (the project's next core upgrade writes them), not a reason to hand it over. In **Manual** ask first; if the ship stops with `[otb-ask-ship-approval]` (exit 5), ask the person "Ship it, or not yet?" and re-run with `--person-approved` only after a real yes.
 - **Never ship a task you don't have an active claim on.** The API will reject it (`NOT_YOUR_CLAIM`); surface clearly and run `/builder-start` to find the right state.
 - **Don't fabricate the value summary.** If you can't summarize the value in non-jargon English, the work is probably not actually shippable yet — release instead and surface the gap to the user.
 - **Be honest in handoff notes.** Use `[verified-prod]` only when a real human exercised the feature on the live site. Otherwise `[verified-smoke]` or `[implemented-not-verified]`. The whole project relies on this honesty.

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,9 @@ 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)
+  1.21.123 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.122 with no explicit bump. run 38624070870. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/government/protected-surfaces.json

@@ -71,6 +71,8 @@
     { "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-manual.js", "group": "pipeline", "why": "task 1004631. 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/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." },

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.123",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.121",
+      "version": "1.21.123",
       "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.123",
   "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,17 @@
       "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"
+    }
+  ],
+  "1.21.123": [
+    {
+      "id": "1004631",
+      "text": "Found why the AI refused to ship on Windows projects: the core update failed on Windows, so projects never got the permission that lets the AI run a ship. That is fixed. New projects also tell the AI to ship on its own in Auto"
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -440,6 +440,9 @@ const STARTER_COMMANDS = [
   // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
   'npx bongos start:*',
   'npx bongos status:*',
+  // Exact form, no `:*`: reading the ship mode is how the agent knows whether to ship on its own
+  // (task 1004631, ADR 0369). `ship-mode auto|manual` WRITES it, and stays a prompt.
+  'npx bongos ship-mode',
   'npx bongos recall:*',
   'npx bongos exec scripts/gds/me.js:*',
   'npx bongos doctor:*',

package/scripts/gds/claude-md-template.js

@@ -77,6 +77,7 @@ ${ident}
 - **Start every session with \`npx bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
 - **\`npx bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
 - **\`npx bongos ship\`** runs the smoke + grade, then merges and deploys; **\`npx bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
+- **The project's ship mode says who starts a ship** — \`npx bongos ship-mode\` prints it. In **Auto** (the default) you run \`npx bongos ship\` yourself when the task is done; never hand the person commands to run. In **Manual** ask the person first, and ship only after they say yes.
 - **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
 - **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
 

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');
@@ -34,6 +36,25 @@ const { noteServerReward } = require('./ship-state.js');
 // task 1004536: each graded round lands in the autonomous run's ledger (inert
 // without one), so ship.js can refuse a third grade at its entry point.
 const { recordGradeOutcome } = require('./autobongos-grade-cap.js');
+// task 1004631: on a Manual project an AI session asks before it ships (ADR 0369).
+const manualShip = require('./ship-mode-manual.js');
+
+// stopForManualApproval(args, taskId) — Manual ship mode (task 1004631, ADR 0369). Every path
+// that can LAND work calls this first: a fresh ship, a resumed merge, and a re-grade (whose pass
+// runs finishShip). When an AI session runs it on a Manual project without the person's yes, it
+// prints the ask, exits 5 and returns true; the caller returns. A mode that cannot be read is
+// Auto and never stops a ship. Who is stopped is ship-mode-manual.js's pure verdict.
+async function stopForManualApproval(args, taskId) {
+  let shipMode = null;
+  try {
+    const r = await apiCall('GET', '/api/bongos/project-settings/ship-mode');
+    shipMode = r.ok ? r.data : null;
+  } catch (_) { shipMode = null; }
+  if (!manualShip.manualShipVerdict({ shipMode, args }).stop) return false;
+  for (const line of manualShip.manualAskLines(args, taskId)) console.log(line);
+  cliExit(manualShip.MANUAL_ASK_EXIT);
+  return true;
+}
 
 // ---------- Main flow ----------
 
@@ -42,7 +63,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);
   }
@@ -143,6 +164,7 @@ async function shipMain() {
     }
     if (action.action === 'resume-merge') {
       console.log(`Task #${taskId} is at 'confirmed' (merge/deploy stalled) and ${action.via === 'owner' ? 'you last held the claim' : 'you are an Archon'} — resuming the merge + deploy (no re-claim needed).`);
+      if (await stopForManualApproval(args, taskId)) return; // a resumed land is a ship too (task 1004631)
       return resumeMerge(taskId, { summary, skipMerge, force, task, dbOnly });
     }
     if (action.action === 'done') {
@@ -157,6 +179,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
@@ -173,6 +213,10 @@ async function shipMain() {
     process.exit(1);
   }
 
+  // ---- Manual ship mode: an AI session asks the person first (task 1004631, ADR 0369) ----
+  // Before anything resolves, so a "not yet" leaves the claim exactly as it was.
+  if (await stopForManualApproval(args, taskId)) return;
+
   // ---- Surprise gate: forced "anything surprise you?" prompt ----
   //
   // Resolve the user's intent into a single value: either a non-empty surprise
@@ -830,6 +874,9 @@ async function regradeMain(opts = {}) {
     console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--visual <image>] [--visual-alt "caption"] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
+  // A passing re-grade runs finishShip, the same land as a fresh ship, so Manual mode asks
+  // here too — whether reached by --regrade or by shipMain's resume-grade dispatch (task 1004631).
+  if (await stopForManualApproval(args, taskId)) return;
   // task 1003702: refuse --notes rather than swallowing it. The reasoning — why
   // a refusal and not a persist — is in ship-honesty.js above regradeNotesRefusal
   // and is not repeated here. What is load-bearing at THIS call site is the

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-mode-manual.js

@@ -0,0 +1,54 @@
+// scripts/gds/ship-mode-manual.js — Manual ship mode: the AI asks before it ships (task 1004631, ADR 0369).
+//
+// WHY. Ship mode says who starts a ship. In Auto the AI ships on its own; in Manual a person
+// approves each ship. The instance CLAUDE.md and the /builder-ship skill tell the AI to ask in
+// Manual, but words alone are what failed the owner in Auto (the AI refused to ship), so the ship
+// itself also stops: when an AI session runs it on a Manual project without the person's yes, it
+// exits before anything resolves and prints the question. The re-run with `--person-approved`
+// carries on.
+//
+// WHO IT STOPS. Only an AI session: Claude Code sets CLAUDECODE=1 in the shell it runs commands
+// in, and a person typing `npx bongos ship` in their own terminal has already decided. An
+// Autobongos worker (OTB_SUBAGENT=1) is not stopped: the runner is the owner's own opt-in to
+// unattended shipping, and stopping it would only park every task it takes.
+//
+// WHAT IT IS NOT. A security wall. The flag is one word an agent could add, the same posture as
+// `--approved` on the sandbox review: the rule is behavioural, and the skill says never to pass it
+// without a real yes. Rank and every server gate are unchanged (ADR 0016). A mode that cannot be
+// read never stops a ship (the resolver's own posture: Auto).
+//
+// The decision is pure (manualShipVerdict) so tests prove it with no network.
+
+'use strict';
+
+// Same code as the first-ship question (ship-mode-ask.js, task 1004630): "a question for the
+// person is waiting", distinct from failure (1), usage (2) and the grade cap (6).
+const MANUAL_ASK_EXIT = 5;
+const MANUAL_ASK_MARKER = '[otb-ask-ship-approval]';
+const APPROVED_FLAG = '--person-approved';
+
+// manualShipVerdict({ shipMode, args, env }) → { stop: boolean, why }
+function manualShipVerdict({ shipMode, args = [], env = process.env }) {
+  if (!shipMode || shipMode.mode !== 'manual') return { stop: false, why: 'not_manual' };
+  if (args.includes(APPROVED_FLAG)) return { stop: false, why: 'approved' };
+  if (env.OTB_SUBAGENT === '1') return { stop: false, why: 'unattended_runner' };
+  if (env.CLAUDECODE !== '1') return { stop: false, why: 'person_at_terminal' };
+  return { stop: true, why: 'needs_approval' };
+}
+
+// manualAskLines(args, taskId) — the question the AI puts to the person, and the re-run.
+function manualAskLines(args, taskId) {
+  const rerun = ['node', 'scripts/gds/ship.js', ...args]
+    .map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(' ');
+  return [
+    `${MANUAL_ASK_MARKER} This project's ship mode is Manual: a person approves each ship.`,
+    `Ask the person whether to ship task ${taskId} now, with two options: Ship it, or Not yet.`,
+    'Only after they say yes, re-run:',
+    '',
+    `  ${rerun} ${APPROVED_FLAG}`,
+    '',
+    'Nothing was resolved: the claim is still active. Never add the flag without their yes.',
+  ];
+}
+
+module.exports = { MANUAL_ASK_EXIT, MANUAL_ASK_MARKER, APPROVED_FLAG, manualShipVerdict, manualAskLines };

package/scripts/gds/ship.js

@@ -50,11 +50,22 @@
 //                                                       # 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
 //                                                       # task. Honored only when the game state is already
 //                                                       # staged-fresh (a re-run); it can't pre-approve.
+//   node scripts/gds/ship.js <task-id> --person-approved
+//                                                       # Manual ship mode (task 1004631, ADR 0369): an AI
+//                                                       # session on a Manual project stops before anything
+//                                                       # resolves and exits 5 with an ask; re-run with this
+//                                                       # ONLY after the person said yes to shipping now.
 
 
 // ---------------------------------------------------------------------------

package/scripts/gds/update-channel.js

@@ -179,6 +179,16 @@ function resolveChannelTarget({ installed, channel, available } = {}) {
 
 // ---- registry: what versions of the core are published? ---------------------
 
+// npmSpawnOpts — what a spawn of `npm` needs on this platform (task 1004631). On Windows `npm` is
+// `npm.cmd`, and Node refuses to spawn a .cmd without a shell (CVE-2024-27980), so a bare
+// spawnSync('npm') fails with ENOENT there. That failure made `bongos upgrade` roll back on every
+// Windows laptop before it wrote the project's .claude/ files — so the project had no permission
+// rules, and Claude Code's safety check refused `npx bongos ship`. A shell is safe here because
+// every argument passed to npm by these callers is a fixed word or a package@version string.
+function npmSpawnOpts(platform = process.platform) {
+  return platform === 'win32' ? { shell: true } : {};
+}
+
 // List published versions of @bongos/core from the registry via `npm view … versions --json`.
 // The package is public (task 1003872), so this needs no credential and no instance-local
 // `.npmrc` — any cwd resolves it. Fail-SOFT: any error returns
@@ -188,7 +198,7 @@ function resolveChannelTarget({ installed, channel, available } = {}) {
 function listAvailableVersions({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
   let res;
   try {
-    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs });
+    res = run('npm', ['view', pkg, 'versions', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs, ...npmSpawnOpts() });
   } catch (e) {
     return { ok: false, error: e && e.message ? e.message : String(e), versions: [] };
   }
@@ -220,7 +230,7 @@ function parseNpmViewVersions(stdout) {
 function readReleaseTags({ cwd = process.cwd(), pkg = CORE_PKG, run = spawnSync, env = process.env, timeoutMs = NPM_VIEW_TIMEOUT_MS } = {}) {
   let res;
   try {
-    res = run('npm', ['view', pkg, 'dist-tags', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs });
+    res = run('npm', ['view', pkg, 'dist-tags', '--json'], { cwd, env, encoding: 'utf8', timeout: timeoutMs, ...npmSpawnOpts() });
   } catch (e) {
     return { ok: false, error: e && e.message ? e.message : String(e), released: null, tags: {} };
   }
@@ -463,6 +473,7 @@ function describeStaleness(st, { slug = 'instance' } = {}) {
 }
 
 module.exports = {
+  npmSpawnOpts,
   CORE_PKG,
   VALID_CHANNELS,
   DEFAULT_CHANNEL,

package/scripts/gds/upgrade.js

@@ -29,7 +29,7 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
-const { parseSemver, compareSemver, isStable, listAvailableVersions } = require('./update-channel');
+const { parseSemver, compareSemver, isStable, listAvailableVersions, npmSpawnOpts } = require('./update-channel');
 const { checkArtistGate } = require('./upgrade-artist-gate');
 // The database side of a move: which command migrates, as which account, and whether that
 // account can reach the database (tasks 1004274, 1002712, 1004512).
@@ -514,7 +514,7 @@ function npmInstall(instanceDir, run = spawnSync) {
   // This used to take an extraEnv carrying a resolved npm credential, because the instance
   // `.npmrc`'s env expansion could shadow a valid user-level one (task 1002754). The core is
   // public and writes no `.npmrc`, so there is no credential to resolve (task 1003878).
-  const opts = { cwd: instanceDir, stdio: 'inherit' };
+  const opts = { cwd: instanceDir, stdio: 'inherit', ...npmSpawnOpts() }; // Windows: npm.cmd needs a shell (task 1004631)
   const r = run('npm', ['install', '--no-audit', '--no-fund'], opts);
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }

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

@@ -104,12 +104,14 @@ const MODULE_GLOBS = {
   lifecycle: [
     'modules/lifecycle/',
     'scripts/gds/ship.js', 'scripts/gds/claim.js', 'scripts/gds/release.js',
+    'scripts/gds/ship-mode-manual.js', // task 1004631
     // task 1004024: the 2026-08-23 ship.js carve, now protected (by name: no '*' here).
     'scripts/gds/ship-check.js', 'scripts/gds/ship-deploy-target.js', 'scripts/gds/ship-escalation.js',
     '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/merge-mode.js', 'scripts/gds/confirm.js', 'scripts/gds/main-audit.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.123'; // 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/cli_allowlist_permissions.mjs

@@ -214,6 +214,10 @@ const GIT_GH_COMMANDS = [
   // CLI access gives `npx bongos paste-token <token>` (task 1004575), a blessed writer
   // (see BLESSED_WRITERS) spelled the way a clone can run it.
   'npx bongos paste-token:*',
+  // EXACT form, no `:*` (task 1004631, ADR 0369): with no argument shipping-mode.js only
+  // READS the ship mode, which the agent must know before it ships. With `auto|manual` it
+  // WRITES the project setting, so a prefix rule would pre-allow that write.
+  'node scripts/gds/shipping-mode.js',
 ];
 // gds CLIs audited read-only under EVERY flag they take — a prefix rule allows them all.
 // Audited and left OUT: backlog-review.js (POSTs from its default walk) and

package/tests/government_protected_surfaces.mjs

@@ -266,7 +266,7 @@ 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 '
@@ -295,6 +295,14 @@ const ADDED_SINCE_R101 = [
     why: 'the core neutral provider set, which declares none. An entry added here would '
        + 'send every instance\'s diffs to a vendor by default.',
   },
+  // task 1004631: 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-merge.js',
+    glob: 'scripts/gds/ship-mode-manual.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.',
+  },
 ];
 
 // Surfaces RENAMED since R101 — still protected, under a new path. Distinct from

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);
+});

package/tests/ship_mode_hands_off.mjs

@@ -0,0 +1,146 @@
+// tests/ship_mode_hands_off.mjs — Auto ships hands-off, Manual asks first (task 1004631, ADR 0369).
+//
+// The owner's AI refused `npx bongos ship` on their own project. The cause: `bongos upgrade`
+// spawned bare `npm`, which is ENOENT on Windows, so the upgrade rolled back before it wrote
+// the project's .claude/settings.json, and with no allow-rule Claude Code's safety check denied
+// the ship. Pinned here:
+//   1. npm is spawned with a shell on Windows (and only there) by the upgrade and the registry reads;
+//   2. a fresh project's starter allows the ship and the read-only ship-mode check, but NOT the
+//      ship-mode write;
+//   3. the instance CLAUDE.md tells the AI to follow the ship mode and never hand over commands;
+//   4. Manual mode: an AI session stops before anything resolves and asks; a person at a
+//      terminal, an approved re-run, an Autobongos worker, Auto and an unreadable mode never stop;
+//   5. the wiring: the Manual check runs after the claim is found and before the grade.
+//
+// Run:  node --test tests/ship_mode_hands_off.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 { npmSpawnOpts, listAvailableVersions } = require('../scripts/gds/update-channel.js');
+const { STARTER_ALLOW } = require('../scripts/gds/claude-materialize.js');
+const {
+  MANUAL_ASK_EXIT, MANUAL_ASK_MARKER, APPROVED_FLAG, manualShipVerdict, manualAskLines,
+} = require('../scripts/gds/ship-mode-manual.js');
+
+// ---- 1. npm on Windows -----------------------------------------------------
+
+test('npm gets a shell on Windows only (npm is npm.cmd there, and Node will not spawn a .cmd bare)', () => {
+  assert.deepEqual(npmSpawnOpts('win32'), { shell: true });
+  assert.deepEqual(npmSpawnOpts('linux'), {});
+  assert.deepEqual(npmSpawnOpts('darwin'), {});
+});
+
+test('the registry read passes the platform spawn options to npm', () => {
+  const calls = [];
+  listAvailableVersions({ run: (cmd, args, opts) => { calls.push({ cmd, args, opts }); return { status: 0, stdout: '["1.0.0"]' }; } });
+  assert.equal(calls[0].cmd, 'npm');
+  assert.equal(calls[0].opts.shell, npmSpawnOpts().shell);
+});
+
+test('the upgrade\'s npm install uses the same spawn options', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'upgrade.js'), 'utf8');
+  const fn = src.slice(src.indexOf('function npmInstall'), src.indexOf('async function runMigrate'));
+  assert.match(fn, /npmSpawnOpts\(\)/);
+});
+
+// ---- 2. the starter permissions --------------------------------------------
+
+test('a fresh project allows the ship, and reading the ship mode, for both shell tools', () => {
+  for (const tool of ['Bash', 'PowerShell']) {
+    assert.ok(STARTER_ALLOW.includes(`${tool}(npx bongos ship:*)`), `${tool} ship`);
+    assert.ok(STARTER_ALLOW.includes(`${tool}(npx bongos ship-mode)`), `${tool} ship-mode read`);
+  }
+});
+
+test('the starter never pre-allows WRITING the ship mode', () => {
+  assert.ok(!STARTER_ALLOW.some((r) => /ship-mode[: ]/.test(r) || /ship-mode\*/.test(r)),
+    'only the exact no-argument read is allowed; `ship-mode auto|manual` stays a prompt');
+});
+
+// ---- 3. the instance CLAUDE.md ---------------------------------------------
+
+test('a new project\'s CLAUDE.md tells the AI to follow the ship mode and never hand over commands', () => {
+  const tpl = require('../scripts/gds/claude-md-template.js');
+  const render = Object.values(tpl).find((v) => typeof v === 'function');
+  const text = render({});
+  assert.match(text, /npx bongos ship-mode/);
+  assert.match(text, /In \*\*Auto\*\*[^\n]*run `npx bongos ship` yourself[^\n]*never hand the person commands/);
+  assert.match(text, /In \*\*Manual\*\* ask the person first/);
+});
+
+// ---- 4. Manual mode --------------------------------------------------------
+
+const AI = { CLAUDECODE: '1' };
+const manual = { mode: 'manual', chosen: true };
+
+test('an AI session on a Manual project stops and asks', () => {
+  assert.deepEqual(manualShipVerdict({ shipMode: manual, args: ['7'], env: AI }), { stop: true, why: 'needs_approval' });
+});
+
+test('the approved re-run, a person at a terminal, and an Autobongos worker are never stopped', () => {
+  assert.equal(manualShipVerdict({ shipMode: manual, args: ['7', APPROVED_FLAG], env: AI }).stop, false);
+  assert.equal(manualShipVerdict({ shipMode: manual, args: ['7'], env: {} }).why, 'person_at_terminal');
+  assert.equal(manualShipVerdict({ shipMode: manual, args: ['7'], env: { ...AI, OTB_SUBAGENT: '1' } }).why, 'unattended_runner');
+});
+
+test('Auto and an unreadable mode ship on', () => {
+  assert.equal(manualShipVerdict({ shipMode: { mode: 'auto', chosen: true }, args: ['7'], env: AI }).stop, false);
+  assert.equal(manualShipVerdict({ shipMode: null, args: ['7'], env: AI }).stop, false);
+});
+
+test('the ask names the task, both answers, the exact re-run, and forbids a yes nobody gave', () => {
+  const lines = manualAskLines(['7', '--summary', 'two words'], 7);
+  const text = lines.join('\n');
+  assert.ok(lines[0].startsWith(MANUAL_ASK_MARKER));
+  assert.match(text, /ship task 7 now[\s\S]*Ship it, or Not yet/);
+  assert.match(text, /node scripts\/gds\/ship\.js 7 --summary "two words" --person-approved/);
+  assert.match(text, /Never add the flag without their yes/);
+  assert.equal(MANUAL_ASK_EXIT, 5);
+});
+
+// ---- 5. the wiring ---------------------------------------------------------
+
+const flowSrc = () => fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship-flow.js'), 'utf8');
+
+test('the Manual check stops with cliExit and returns, never a hard exit after a request', () => {
+  const src = flowSrc();
+  const helper = src.slice(src.indexOf('async function stopForManualApproval'), src.indexOf('async function shipMain'));
+  assert.match(helper, /manualShip\.manualShipVerdict\(/);
+  assert.match(helper, /cliExit\(manualShip\.MANUAL_ASK_EXIT\);\s*return true;/);
+  assert.doesNotMatch(helper, /process\.exit\(/);
+});
+
+test('a fresh ship asks after the claim is found and before preflight, the grade and the resolve', () => {
+  const main = flowSrc().slice(flowSrc().indexOf('async function shipMain'));
+  const claimFound = main.indexOf('const ac = claims.find(');
+  const gate = main.indexOf('if (await stopForManualApproval(args, taskId)) return;', claimFound);
+  const preflight = main.indexOf('Step 0: preflight');
+  assert.ok(claimFound > 0 && gate > claimFound && preflight > gate);
+});
+
+test('a resumed merge asks before it lands (the stranded-ship re-run)', () => {
+  const main = flowSrc().slice(flowSrc().indexOf('async function shipMain'));
+  const branch = main.slice(main.indexOf("action.action === 'resume-merge'"), main.indexOf('return resumeMerge(taskId'));
+  assert.match(branch, /if \(await stopForManualApproval\(args, taskId\)\) return;/);
+});
+
+test('a re-grade asks before it can pass into finishShip (direct --regrade and the resume-grade dispatch)', () => {
+  const src = flowSrc();
+  const regrade = src.slice(src.indexOf('async function regradeMain'));
+  const gate = regrade.indexOf('if (await stopForManualApproval(args, taskId)) return;');
+  const finish = regrade.indexOf('finishShip(');
+  assert.ok(gate > 0 && finish > gate, 'the gate runs before the land');
+  const main = src.slice(src.indexOf('async function shipMain'), src.indexOf('async function regradeMain'));
+  assert.match(main, /action\.action === 'resume-grade'[\s\S]*?return regradeMain\(/, 'resume-grade goes through regradeMain, so its gate covers it');
+});
+
+test('--person-approved is documented in the ship usage banner', () => {
+  assert.match(fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'ship.js'), 'utf8'), /--person-approved/);
+});