@bongos/core 1.21.122 → 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.122",
-  "core_contract": "1.21.122",
-  "source_commit": "1744caf4412e029c7cf9b465a9fae581bc2deea7",
+  "core_version": "1.21.123",
+  "core_contract": "1.21.123",
+  "source_commit": "bfe95a4e390577d4579a3da16d81d5ada6bc8b9a",
   "source_ref": "HEAD",
-  "built_at": "2026-10-14T19:02:19.295Z",
+  "built_at": "2026-10-14T19:30:01.919Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 605,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3120,
+    "functional_verbatim": 3122,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3754,
-  "tree_sha256": "df175c2d7b99fee7204cf032575b41a9fa13988b1a3635717568822cf1d84d6b",
+  "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": "1053b6160f72c6f78d9608b8431ba59b707fb310493fdb24ea52efd52f1ef825"
+      "sha256": "bac025cc3ff28c70baf2de467e271bdb23fab1f3cf61100381efbc835f88a952"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "05a2ac9355a782e35f6af18287d0395ece73a55b0541f680106c250d1f604b63"
+      "sha256": "f2b2bf656d2fa819a7bd0f10ceb966b5414c1c06f05f2e8ccaa9ed326a7227ed"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5297,7 +5297,7 @@
     {
       "path": "modules/government/protected-surfaces.json",
       "mode": "0000644",
-      "sha256": "9aedf10b3cb611343baf96662e6f79d45ed2218b83abfb3ad8c03536c722d37c"
+      "sha256": "3f7f0bd81b70a995464993a084d35951c3d98b927d0d02fbe97f84105cbdd89f"
     },
     {
       "path": "modules/government/ranks.js",
@@ -10467,12 +10467,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "0698dfed8aaee5032ad705115bcbc515cc7328a78c31a30018a2e2f5df0cf1ca"
+      "sha256": "e92fbdef629a9283a773d94986531ae9d30412fe05dc3012dd918be8fb859030"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "aefc81df15571d208d96577a7ade7189f1d1e064ae9a1af132b0725f871fcb40"
+      "sha256": "cf96b6c94e06d4306f0b3e3c0626c051729a0498bd3e6760012ce86350286d16"
     },
     {
       "path": "public-docs/index.html",
@@ -10492,7 +10492,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "43b16f9fbd2c3834c02bd141ce4b9e737003d1c42112e6cb607e7a118e29e7dd"
+      "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": "bb8edf9166b1c452b87d75e009d7404758bcba6ea58aa9011848ec44e761bb52"
+      "sha256": "d944906397fc7936701bd36f3896a418829acf385c70a7ccaef07bd6cc348e91"
     },
     {
       "path": "scripts/gds/ship-git.js",
@@ -12049,6 +12049,11 @@
       "mode": "0000644",
       "sha256": "7a489ea223b4fa1d7a3b4ee1076c9a0cb65d6d929e9a5a6e0b8e403e15266afc"
     },
+    {
+      "path": "scripts/gds/ship-mode-manual.js",
+      "mode": "0000644",
+      "sha256": "077ab61bd14d0a5c8b4012103dd7289ba29a6a7d1ac3420ad401a7d6ef365597"
+    },
     {
       "path": "scripts/gds/ship-preflight-steps.js",
       "mode": "0000644",
@@ -12087,7 +12092,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "9f00804212ef485fd8cfd02be19cddb4be2570a34aa2a284f237940aff17753e"
+      "sha256": "44f7161514392afb04a9165086a1fcc12e1f231d3a641220409ffe0c4ae2c9a2"
     },
     {
       "path": "scripts/gds/shipping-mode.js",
@@ -12227,7 +12232,7 @@
     {
       "path": "scripts/gds/update-channel.js",
       "mode": "0000644",
-      "sha256": "f6b0d78ff92c9962b158bc5b36bae021c63fcc24095c7b10866f1505ee3f5232"
+      "sha256": "66bed9292a4f5ec70b15ba29a94abec5ed8c69891a5b674a030002844275880c"
     },
     {
       "path": "scripts/gds/update-sweep.js",
@@ -12262,7 +12267,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "f4f158948ab880ceee1cf745ba0071983054c20deba885fed735b7828fe7c1ca"
+      "sha256": "d55d4ba8c8b7d3abedbae59c28a9b1ef9c7021ccc214c6917d1a042c84019d25"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -12567,7 +12572,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "1b0cec97fbdf2c14f48354741f5537a7db3dbc947e7b7182eb2aa9173cfa00dc"
+      "sha256": "5def34a161ca00980bf8a68d4273f3183fdd7269f9b83c61e62e82c154ba881d"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -12807,7 +12812,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d49bdec14177f77cd4e6dd63ac2532a095565373c0948d9d7b91c809e4e3e6f3"
+      "sha256": "01bc6b541cf12105be05701170377582f537316fe3f70fdea2681bae07864bf7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13622,7 +13627,7 @@
     {
       "path": "tests/cli_allowlist_permissions.mjs",
       "mode": "0000644",
-      "sha256": "ce1d4031bf29064a8522440116e4da5dde78ffd59eb0c396b5d32a72790a260a"
+      "sha256": "92bad4d5a6f224b0764bab5e7f906a0990c60f7fab75c5977ce64ba9e9b08b44"
     },
     {
       "path": "tests/cli_dispatcher.mjs",
@@ -14997,7 +15002,7 @@
     {
       "path": "tests/government_protected_surfaces.mjs",
       "mode": "0000644",
-      "sha256": "3518806d6b065029677e77a242604b6dc85bfd28537c2d109dacaedd29ac6d49"
+      "sha256": "72fc7970c987dbb78120575546aed5faeb9e55342b68e6ba1668508927a9f103"
     },
     {
       "path": "tests/government_rank_sync.mjs",
@@ -17949,6 +17954,11 @@
       "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

@@ -106,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/docs/module-api-changelog.md

@@ -3081,5 +3081,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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,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-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." },
@@ -79,7 +80,6 @@
     { "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/package-lock.json

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

@@ -9714,5 +9714,11 @@
       "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

@@ -36,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 ----------
 
@@ -145,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') {
@@ -193,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
@@ -850,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-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

@@ -61,6 +61,11 @@
 //                                                       # 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,6 +104,7 @@ 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',
@@ -113,7 +114,6 @@ const MODULE_GLOBS = {
     '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.122'; // 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

@@ -271,14 +271,6 @@ const ADDED_SINCE_R101 = [
     '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.
   {
@@ -303,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_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/);
+});