@bongos/core 1.21.124 → 1.21.125

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.124",
-  "core_contract": "1.21.124",
-  "source_commit": "695a6d5cad41a0d7a9e79cf58a7de3282b64daf3",
+  "core_version": "1.21.125",
+  "core_contract": "1.21.125",
+  "source_commit": "6537f85e10dcb60107037c138237fe4e5d855500",
   "source_ref": "HEAD",
-  "built_at": "2026-10-14T19:49:05.130Z",
+  "built_at": "2026-10-15T15:06:45.205Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 605,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 3124,
+    "functional_verbatim": 3128,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3758,
-  "tree_sha256": "97c9a1a6dc5c913bdacb02a6bbef3bef853e5babbbd971cd4f097403aa754be9",
+  "file_count": 3762,
+  "tree_sha256": "7fb72ed794b2cdaa7f0fe66ffdccb7b56f5c18a9d4d66f18b4767254072e1827",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -312,7 +312,7 @@
     {
       "path": "bin/bongos.js",
       "mode": "0000755",
-      "sha256": "20794ff2c632668d2a65ab1ca1a0e6d5b240c19769dbabf6999c7347d41f54e6"
+      "sha256": "f2a64dc742bb1f13938840c9f294ea7a60f1895dc9366200e33d53891e5e0fe5"
     },
     {
       "path": "clients/bongos-client/README.md",
@@ -2922,7 +2922,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "1ead6d6c8697d53d3f324f3d5c1523f5c590ebcce268abcb2b29a367d6c34f17"
+      "sha256": "a1ec4ace0bc91b34031c59bb4fd08263af542f5ddd1284204bfd821cf843b527"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7929,6 +7929,11 @@
       "mode": "0000644",
       "sha256": "22904d8c06daabb634b55f240b895c906e90ba4c6ed81e7a41cdbbb78635ace8"
     },
+    {
+      "path": "modules/onboarding/howto-guide.js",
+      "mode": "0000644",
+      "sha256": "18984c946d746da66ff7678379e9f49c9cfdcdb8f70d2acd852ab29c820baad0"
+    },
     {
       "path": "modules/onboarding/module.json",
       "mode": "0000644",
@@ -10472,12 +10477,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "31a3c967bca985d1dc5007279f9ed7e9352b0466128af6edd9debbf4e7b592bb"
+      "sha256": "cb1fe1a974c6063f91ae16893f1daddb028647374dc13d9df725ea4be5074d9a"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4714b7161307f36c4ae4322e72f3670f6d958b1ab3b19f728a3f05f880898771"
+      "sha256": "e92ae06c5b33aa14e3ec516f009526f335ebec59b5e03b4e774a4a48c252d087"
     },
     {
       "path": "public-docs/index.html",
@@ -10497,7 +10502,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "aeb72646e01f775fe09e570e0f5e8dccf9733fc59cb79d5a67e6315f2195d88c"
+      "sha256": "415b376c73ce06c6803897093c02aa9157378d55487a0f84dd8387dc749a75a0"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -10874,6 +10879,11 @@
       "mode": "0000644",
       "sha256": "9dd80d2c37602c59cb75db0be02cfadc737fc64891a81d03f5be5f0ea5e35a27"
     },
+    {
+      "path": "scripts/gds/core-pin-sync.js",
+      "mode": "0000644",
+      "sha256": "f8a3a0ee2c0f4dbc2583603cd6e7b547140a5f8dc286b7c5f0b6dadd6096a002"
+    },
     {
       "path": "scripts/gds/coreB-carve-proof.sh",
       "mode": "0000644",
@@ -12817,7 +12827,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "792dad669f6c0d0b86433d206c837ca7ffcbf6a8b5b7c02bda8707c3dd3f7099"
+      "sha256": "81694f072dbbb4e64a286a4f5157d07a8e1105ae8a94d800f09eba00f30848e6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13829,6 +13839,11 @@
       "mode": "0000644",
       "sha256": "a3cf352d5dc340b453b22513c28d8c0a439526862535f51f84b7aea2161c734f"
     },
+    {
+      "path": "tests/core_pin_sync.mjs",
+      "mode": "0000644",
+      "sha256": "ac3714b1b089ba2450f1125c74cbe5491deb4ddec1eec77c4c83a8a635a84d93"
+    },
     {
       "path": "tests/core_update_banner.mjs",
       "mode": "0000644",
@@ -15584,6 +15599,11 @@
       "mode": "0000644",
       "sha256": "7cd031d48b41424a654ddc66404cf112a21ecc7d558256ac27ec9357401f112c"
     },
+    {
+      "path": "tests/howto_guide.mjs",
+      "mode": "0000644",
+      "sha256": "8e9b206fdde738f289bc11e204852595e9128b523cfc20cd67e3e83fb60a2fac"
+    },
     {
       "path": "tests/html_comment_nesting.mjs",
       "mode": "0000644",

package/bin/bongos.js

@@ -190,6 +190,15 @@ function main(argv) {
     return 0;
   }
 
+  // Run the core the checkout PINS (task 1004632). A task worktree has no node_modules
+  // of its own, so after a core update lands it resolves the main checkout's older core
+  // and the ship fails on a bug the pin already fixed. `ship` installs the pinned core
+  // into the checkout and re-runs under it; scripts/gds/core-pin-sync.js.
+  if (!COMPILED && verb === 'ship') {
+    const synced = require('../scripts/gds/core-pin-sync.js').ensurePinnedCore({ coreRoot: REPO_ROOT, argv });
+    if (synced != null) return synced;
+  }
+
   // `bongos exec <relpath> [args]` — run a core script by its package-relative path (see above).
   if (verb === 'exec') {
     if (COMPILED) {

package/docs/module-api-changelog.md

@@ -3085,5 +3085,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.122 with no explicit bump. run 38624070870. (task 1002620)
   1.21.124 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.123 with no explicit bump. run 38626749089. (task 1002620)
+  1.21.125 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.124 with no explicit bump. run 38757326466. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/onboarding/howto-guide.js

@@ -0,0 +1,259 @@
+// modules/onboarding/howto-guide.js — the in-session how-to guide: ~25 short steps an AI walks a person through (task 1004627)
+//
+// WHY. The owner opened Bongos on their own project and did not know where to begin:
+// nothing told them `/builder-start` exists, what a goal is for, or what happens on a
+// first ship. This guide is the CONTENT an AI assistant walks a person through inside
+// their own session, one short step at a time, at the moment it is useful — so someone
+// who has never heard of a Bongos command is never lost.
+//
+// It is the single source of truth for the three tasks that build on it:
+//   • task 1004634 stores each person's read/unread state per step id;
+//   • task 1004635 shows the right unread step when its moment arrives, then marks it read;
+//   • task 1004636 lets a person reopen the guide, see progress, or skip it.
+// So the step ids are STABLE: a stored "read" mark names one. Never rename or reuse an
+// id — retire a step by deleting it and add a new id for new content
+// (tests/howto_guide.mjs pins the shape and the plain-language rule).
+//
+// Each step is: what the feature is FOR (`what`), WHEN to reach for it (`when`), and the
+// exact words or command to TRY (`try`). Plain language throughout — the reader may not
+// be technical; the test bans the accessibility scorer's jargon list. Commands are the
+// ones an instance actually gets (core skills + `npx bongos` verbs); a step names a
+// slash command AND the plain words that reach it, because typed-only commands do not
+// answer to plain words.
+//
+// Read it in a terminal: `node modules/onboarding/howto-guide.js` (add `--moment <id>`).
+
+'use strict';
+
+// The moments, in the order a new project meets them. `trigger` says, for task 1004635,
+// what event opens the moment; it is descriptive here, not wiring.
+const MOMENTS = Object.freeze([
+  { id: 'first_open', title: 'Opening the project for the first time', trigger: 'the first prompt of the first session in a project folder' },
+  { id: 'setup', title: 'Setting up the project', trigger: 'the project has no goal yet, or setup is unfinished' },
+  { id: 'goal', title: 'Creating a goal', trigger: 'the person asks to plan work, or the project has no open goal' },
+  { id: 'task', title: 'Creating a task', trigger: 'the person describes a change they want, or a goal has no tasks' },
+  { id: 'find_work', title: 'Finding work', trigger: 'the person asks what to do next, or starts a session with nothing claimed' },
+  { id: 'first_claim', title: 'Claiming your first task', trigger: 'the person claims a task for the first time' },
+  { id: 'first_ship', title: 'Your first ship', trigger: 'the person finishes the work on their first claimed task' },
+  { id: 'after_ship', title: 'After a ship', trigger: 'a task reaches shipped for the first time' },
+  { id: 'invite', title: 'Inviting people', trigger: 'the person mentions a teammate, or asks how others can help' },
+  { id: 'settings', title: 'Settings', trigger: 'the person asks to change how Bongos behaves for them or the project' },
+  { id: 'stuck', title: 'When something goes wrong', trigger: 'a command fails, or the person says they are stuck or confused' },
+]);
+
+const STEPS = Object.freeze([
+  // first_open
+  {
+    id: 'welcome', moment: 'first_open', title: 'What Bongos is',
+    what: 'Bongos keeps the list of everything your project needs, and the AI does the building. You decide what gets made; the AI does the work and records it.',
+    when: 'The first time you open this project with an AI assistant.',
+    try: 'Ask: "What is Bongos and what can it do for me?"',
+  },
+  {
+    id: 'where_to_start', moment: 'first_open', title: 'Where to start',
+    what: 'There are three ways in: finish setting up the project, make a goal (a bigger outcome you want), or make a task (one piece of work).',
+    when: 'Any time you are not sure what to do first.',
+    try: 'Say: "Where should I start?" The AI will look at the project and suggest one of the three.',
+  },
+  {
+    id: 'ask_in_plain_words', moment: 'first_open', title: 'Just ask in plain words',
+    what: 'You never need to memorise commands. Describe what you want and the AI picks the right one, then tells you which it used.',
+    when: 'Whenever you want something done and do not know the command.',
+    try: 'Say: "I want to add a contact form to the website."',
+  },
+  {
+    id: 'the_hall', moment: 'first_open', title: 'The hall: your project in a browser',
+    what: 'The hall is your project\'s web page. It shows goals, tasks, who is working on what, and what has shipped.',
+    when: 'When you want to see everything at a glance instead of asking.',
+    try: 'Ask: "Open the hall for this project" or "What is the hall link?"',
+  },
+  // setup
+  {
+    id: 'sign_in', moment: 'setup', title: 'Sign in once',
+    what: 'Signing in links this computer to your project, so the AI can claim and ship work in your name.',
+    when: 'The first time on a new computer, or when the AI says your sign-in has expired.',
+    try: 'Type /builder-setup, or in a terminal run `npx bongos login`.',
+  },
+  {
+    id: 'check_setup', moment: 'setup', title: 'Check everything is ready',
+    what: 'A quick health check of this computer and your sign-in, with a plain fix for anything missing.',
+    when: 'Before your first task, or when something that used to work stops working.',
+    try: 'Say: "Check my setup", or run `npx bongos doctor`.',
+  },
+  {
+    id: 'project_status', moment: 'setup', title: 'See where the project stands',
+    what: 'A summary of the current version: what is done, what is left, and what is blocking.',
+    when: 'At the start of a working session, or before planning.',
+    try: 'Type /status, or say "How far along is the project?"',
+  },
+  // goal
+  {
+    id: 'what_is_a_goal', moment: 'goal', title: 'What a goal is',
+    what: 'A goal is a bigger outcome, like "people can sign up" — a home for the tasks that get you there, with a clear "done when".',
+    when: 'When what you want is too big to finish in one sitting.',
+    try: 'Ask: "Should this be a goal or a single task?"',
+  },
+  {
+    id: 'create_goal', moment: 'goal', title: 'Create a goal',
+    what: 'The AI asks what the goal is for and what "done" looks like, then writes it up with its first few tasks.',
+    when: 'When you have decided on a new outcome to work towards.',
+    try: 'Type /goal-create, or say "Make a goal for letting people sign up."',
+  },
+  // task
+  {
+    id: 'what_is_a_task', moment: 'task', title: 'What a task is',
+    what: 'A task is one piece of work small enough to finish and check in one go. Every change to the project belongs to a task, so there is always a record of it.',
+    when: 'Whenever you want something changed.',
+    try: 'Ask: "What makes a good task?"',
+  },
+  {
+    id: 'create_task', moment: 'task', title: 'Create a task',
+    what: 'Describe the change and how you will know it is done. The AI writes it up and files it under the right goal.',
+    when: 'When you know a specific change you want.',
+    try: 'Say: "Make a task: the contact form should email me each message."',
+  },
+  {
+    id: 'capture_an_idea', moment: 'task', title: 'Save an idea for later',
+    what: 'Not ready to commit to it? Save it as an idea. Ideas wait in a list until you decide to turn them into tasks or drop them.',
+    when: 'When a thought comes up in the middle of other work.',
+    try: 'Say: "Save an idea: a dark mode for the website."',
+  },
+  // find_work
+  {
+    id: 'whats_claimable', moment: 'find_work', title: 'See what you can work on',
+    what: 'A list of the tasks that are ready right now and safe to start without clashing with anyone else\'s work.',
+    when: 'At the start of a session, or when you finish a task.',
+    try: 'Type /builder-start, or say "What can I work on?"',
+  },
+  {
+    id: 'work_a_goal', moment: 'find_work', title: 'Work through a whole goal',
+    what: 'The AI takes the goal\'s tasks one at a time — start, build, ship, next — and stops to ask you only when it needs a decision.',
+    when: 'When a goal has several tasks that follow on from each other.',
+    try: 'Say: "Work through goal 12 end to end", or type /builder-sequence.',
+  },
+  // first_claim
+  {
+    id: 'claim_a_task', moment: 'first_claim', title: 'Claiming a task',
+    what: 'Claiming says "I am on this one", so nobody else starts the same work. The AI then works on it in its own separate copy of the project, so your main folder stays tidy.',
+    when: 'When you pick a task to work on.',
+    try: 'Type /builder-claim followed by the task number, or say "Claim task 42."',
+  },
+  {
+    id: 'give_a_task_back', moment: 'first_claim', title: 'Give a task back',
+    what: 'Changed your mind? Giving it back makes the task available again. Nothing is lost and nothing is charged.',
+    when: 'When you will not finish a task you claimed.',
+    try: 'Type /builder-release, or say "Give this task back."',
+  },
+  {
+    id: 'preview_before_ship', moment: 'first_claim', title: 'See a change before it ships',
+    what: 'For changes you can see, the AI can show you the page as it will look, before anything goes live.',
+    when: 'When the task changes something on screen.',
+    try: 'Say: "Let me see it before you ship", or type /builder-stage.',
+  },
+  // first_ship
+  {
+    id: 'what_ship_does', moment: 'first_ship', title: 'What shipping does',
+    what: 'Shipping finishes a task: automatic reviewers check the work, then it is added to the project. Going live for your users can wait for a person to say yes.',
+    when: 'When the work on your task is finished.',
+    try: 'Type /builder-ship, or say "Ship it."',
+  },
+  {
+    id: 'review_findings', moment: 'first_ship', title: 'When the reviewers ask for fixes',
+    what: 'If the reviewers find a problem, the task is held, not lost. The AI fixes what they listed and asks for another review.',
+    when: 'When a ship says it needs fixes.',
+    try: 'Say: "Fix what the reviewers found and try again."',
+  },
+  // after_ship
+  {
+    id: 'what_happens_after', moment: 'after_ship', title: 'What happens after a ship',
+    what: 'The task is marked shipped, anything that was waiting on it becomes ready, and the record of the work is kept for the next person.',
+    when: 'Right after your first task ships.',
+    try: 'Ask: "What did that ship unlock?"',
+  },
+  {
+    id: 'fresh_session', moment: 'after_ship', title: 'Start fresh after a few tasks',
+    what: 'A long conversation gets slower and costlier. After a few tasks, the AI can write a short note so a fresh conversation picks up exactly where you left off.',
+    when: 'After three or so tasks in one conversation.',
+    try: 'Say: "Hand this off to a fresh session", or type /session-handoff.',
+  },
+  // invite
+  {
+    id: 'invite_people', moment: 'invite', title: 'Invite people',
+    what: 'Bring someone onto the project by their GitHub name. You choose whether anyone can join, people must ask first, or only invited people can sign in.',
+    when: 'When you want someone else to help build.',
+    try: 'In the hall, use "Invite someone" and enter their GitHub name, or ask "How do I invite someone?"',
+  },
+  {
+    id: 'ask_for_help', moment: 'invite', title: 'Ask a teammate for help',
+    what: 'Send a named person, or anyone with the right skills, a request for help on a task. It shows up in their own list.',
+    when: 'When you are stuck on a task and someone else knows the area.',
+    try: 'Say: "Ask Sam to help with task 42", or type /ask-for-help.',
+  },
+  // settings
+  {
+    id: 'ship_mode', moment: 'settings', title: 'Ship mode: who starts a ship',
+    what: 'In Auto, the AI ships a finished task by itself. In Manual, it stops and waits for you to say "ship it".',
+    when: 'When you want more, or less, control over when work is added to the project.',
+    try: 'In the hall\'s project settings pick Auto or Manual, or run `npx bongos ship-mode` to see the current one.',
+  },
+  {
+    id: 'how_the_ai_talks', moment: 'settings', title: 'How the AI talks to you',
+    what: 'Tell Bongos how technical you are and how long you like answers. Every AI session on this project follows it.',
+    when: 'When answers feel too technical, too long, or too short.',
+    try: 'Open your settings in the hall and look for how the AI talks to you, or say "Keep your answers shorter."',
+  },
+  // stuck
+  {
+    id: 'when_stuck', moment: 'stuck', title: 'When something goes wrong',
+    what: 'Every refusal comes with a plain explanation: what happened, what the AI will do, and whether it needs you. Most fix themselves.',
+    when: 'When a command fails or you do not understand what happened.',
+    try: 'Say: "Explain that in plain words and fix it."',
+  },
+  {
+    id: 'tell_the_bongos_team', moment: 'stuck', title: 'Tell the Bongos team',
+    what: 'If Bongos itself gets in your way, say so. Your words go to the people who build Bongos, and each complaint becomes a fix.',
+    when: 'Whenever Bongos is confusing, slow, or broken.',
+    try: 'Say: "Bongos feedback: …" followed by what went wrong.',
+  },
+]);
+
+const MOMENT_IDS = new Set(MOMENTS.map((m) => m.id));
+
+function stepById(id) { return STEPS.find((s) => s.id === id) || null; }
+
+// The steps for one moment, in guide order. Unknown moment → [].
+function stepsForMoment(momentId) { return STEPS.filter((s) => s.moment === momentId); }
+
+// The first step not in `readIds` (an iterable of step ids), in guide order — what
+// "continue the tutorial" means. null when everything is read.
+function nextUnread(readIds) {
+  const read = new Set(readIds || []);
+  return STEPS.find((s) => !read.has(s.id)) || null;
+}
+
+function formatStep(step) {
+  return [`${step.title}  [${step.id}]`, `  What it is for: ${step.what}`, `  When: ${step.when}`, `  Try: ${step.try}`].join('\n');
+}
+
+function formatGuide({ moment = null } = {}) {
+  const out = [];
+  for (const m of MOMENTS) {
+    if (moment && m.id !== moment) continue;
+    out.push(`## ${m.title}`);
+    for (const s of stepsForMoment(m.id)) out.push(formatStep(s), '');
+  }
+  return out.join('\n').trimEnd() + '\n';
+}
+
+if (require.main === module) {
+  const i = process.argv.indexOf('--moment');
+  const moment = i > -1 ? process.argv[i + 1] : null;
+  if (moment && !MOMENT_IDS.has(moment)) {
+    process.stderr.write(`unknown moment "${moment}" — one of: ${[...MOMENT_IDS].join(', ')}\n`);
+    process.exitCode = 2;
+  } else {
+    process.stdout.write(formatGuide({ moment }));
+  }
+}
+
+module.exports = { MOMENTS, STEPS, MOMENT_IDS, stepById, stepsForMoment, nextUnread, formatStep, formatGuide };

package/package-lock.json

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

package/package.json

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

@@ -9726,5 +9726,15 @@
       "id": "1004633",
       "text": "Found why a merged task on your own project stayed at 'confirmed': with no GitHub key set up on the project's server, Bongos could not prove the merge happened, and its background checker switched itself off. It now confirms t"
     }
+  ],
+  "1.21.125": [
+    {
+      "id": "1004632",
+      "text": "When a project updates its Bongos core, the next task's ship now uses the new core automatically instead of the old one, so it no longer fails for no visible reason."
+    },
+    {
+      "id": "1004627",
+      "text": "Bongos now has a 27-step plain-language how-to guide that an AI can walk a new person through inside their session, from where to start to their first ship."
+    }
   ]
 }

package/scripts/gds/core-pin-sync.js

@@ -0,0 +1,233 @@
+// scripts/gds/core-pin-sync.js — make `bongos ship` run the core the checkout PINS (task 1004632)
+//
+// WHY. An instance's task worktrees (`.claude/worktrees/task-N`) have no `node_modules`
+// of their own: Node and `npx` walk up to the MAIN checkout's, and so does every
+// `bongos ship`. After a core-update task lands, the next task's branch pins the new
+// core in package.json — but its worktree still resolves the main checkout's install,
+// which is whatever version was there before. On the owner's project that meant a
+// ship ran 1.21.20 against a branch pinned to 1.21.71 and failed on a bug 1.21.71 had
+// already fixed; the AI had to `npm ci` by hand in both places.
+//
+// THE FIX. Before `bongos ship` runs, the dispatcher asks `planCoreSync()` whether the
+// core it is running is the one the checkout it stands in pins. When it is not, it
+// installs the pinned core INTO that checkout (`npm ci`, or `npm install` with no
+// lockfile) and re-runs the same command under it. A worktree that gets its own
+// install keeps resolving it from then on. If the install fails, the builder gets one
+// line that names the command to run — never a silent run on the wrong core. Only
+// `ship` checks: it is the verb that runs the core's land/smoke code against the
+// branch, and it is slow anyway — the many quick verbs (status, recall, exec) pay no
+// git spawn for it.
+//
+// Safety. The pin comes from the branch, and installing it then RUNS it — so a branch
+// must never be able to choose what gets installed. Two gates, both required:
+//   1. the spec is a shape the core itself writes — a vendored
+//      `file:vendor/bongos-core-<v>.tgz` or an exact registry semver;
+//   2. the pin has already LANDED: package.json, package-lock.json and the vendored
+//      tarball in this checkout are byte-identical (same git blob, no local edits) to
+//      the ones on `main` / `origin/main`. That is exactly the case this fixes — a
+//      core update merged, the next task's branch carries it — and a branch that pins
+//      something main does not get the remedy line, never an automatic install.
+// The install also runs with `--ignore-scripts` (the core's dependencies need no
+// install hook), through npm's own JS entry under this node where it can be found, so
+// no shell is involved; only a Windows box without it falls back to `npm.cmd` + shell,
+// with fixed arguments. A `node_modules` that
+// is a LINK (the junction worktree.js gives an outside-repo worktree) is unlinked
+// first — installing through it would rewrite the MAIN checkout's install. It is never
+// followed and a real directory is never removed. The re-run sets BONGOS_CORE_SYNCED
+// so a pin the install still cannot satisfy cannot loop.
+//
+// It does nothing in the core repo itself (the running package is not `@bongos/core`),
+// outside git, or when the checkout pins no core. Pure planner + injectable runner, so
+// tests/core_pin_sync.mjs drives every branch without npm or a network.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const CORE_PKG = '@bongos/core';
+const SYNCED_ENV = 'BONGOS_CORE_SYNCED';
+
+function readJson(file, fsImpl = fs) {
+  try { return JSON.parse(String(fsImpl.readFileSync(file, 'utf8')).replace(/^/, '')); } catch { return null; }
+}
+
+// { version, safe } for a dependency spec. `version` reads the same shapes upgrade.js
+// does (kept local so the dispatcher never loads upgrade.js's tree); `safe` is true
+// only for the two shapes the core writes itself — a tarball under vendor/ named for
+// its version, or an EXACT registry semver.
+function parseSpec(spec) {
+  const s = String(spec || '').trim();
+  const tgz = s.match(/bongos-core-(\d+\.\d+\.\d+[^/\\]*)\.tgz$/);
+  if (tgz) return { version: tgz[1], safe: /^file:(\.\/)?vendor\/bongos-core-[^/\\]+\.tgz$/.test(s) };
+  if (/^file:/.test(s)) return { version: null, safe: false };
+  const sem = s.match(/^[\^~>=<\s]*v?(\d+\.\d+\.\d+[A-Za-z0-9.+-]*)$/);
+  if (!sem) return { version: null, safe: false };
+  return { version: sem[1], safe: /^\d+\.\d+\.\d+(-[A-Za-z0-9.]+)?$/.test(s) };
+}
+
+function versionFromSpec(spec) { return parseSpec(spec).version; }
+
+function coreSpec(root, fsImpl = fs) {
+  const pkg = readJson(path.join(root, 'package.json'), fsImpl);
+  return pkg ? ((pkg.dependencies || {})[CORE_PKG] || (pkg.devDependencies || {})[CORE_PKG] || null) : null;
+}
+
+// What the checkout at `root` pins: the lockfile's resolved version first (exact), then
+// the package.json spec.
+function pinnedCoreVersion(root, fsImpl = fs) {
+  const lock = readJson(path.join(root, 'package-lock.json'), fsImpl);
+  const locked = lock && lock.packages && lock.packages[`node_modules/${CORE_PKG}`];
+  if (locked && locked.version) return locked.version;
+  return versionFromSpec(coreSpec(root, fsImpl));
+}
+
+// The refs that count as LANDED for gate 2: a pin is trusted only once it is on one of them.
+const LANDED_REFS = ['main', 'origin/main'];
+
+function gitOut(args, cwd, run) {
+  try {
+    const r = run('git', args, { cwd, encoding: 'utf8' });
+    return r && r.status === 0 ? String(r.stdout || '').trim() : null;
+  } catch { return null; }
+}
+
+// Gate 2: every file that decides what `npm ci` installs — package.json, the lockfile,
+// the project .npmrc (it can redirect the registry), and the vendored tarball the spec
+// names — is in the SAME state as on a landed ref: the same blob as it sits on disk (so
+// an uncommitted edit counts), or absent on both. Deleting a file the landed ref has
+// is a difference too. True when one landed ref matches all of them. The lockfile is
+// also required outright: the install is `npm ci`, whose integrity check is the point.
+const PIN_FILES = ['package.json', 'package-lock.json', '.npmrc'];
+
+function pinLanded(root, { run = spawnSync, fsImpl = fs } = {}) {
+  if (!fsImpl.existsSync(path.join(root, 'package-lock.json'))) return false;
+  const spec = coreSpec(root, fsImpl);
+  const files = [...PIN_FILES];
+  const vendored = String(spec || '').match(/^file:(?:\.\/)?(vendor\/bongos-core-[^/\\]+\.tgz)$/);
+  if (vendored) files.push(vendored[1]);
+  const local = files.map((f) => (fsImpl.existsSync(path.join(root, f)) ? (gitOut(['hash-object', '--', f], root, run) || 'unreadable') : null));
+  return LANDED_REFS.some((ref) => files.every((f, i) => gitOut(['rev-parse', '--verify', '--quiet', `${ref}:${f}`], root, run) === local[i]));
+}
+
+function gitTopLevel(cwd, run = spawnSync) {
+  try {
+    const r = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+    if (r.status !== 0) return null;
+    const top = String(r.stdout || '').trim();
+    return top ? path.resolve(top) : null;
+  } catch { return null; }
+}
+
+// Pure decision. Inputs are facts; output says whether to sync and why.
+//   runningPkg   the running core's package.json ({ name, version })
+//   root         the git top-level of the cwd (null outside git)
+//   pinned       what that checkout pins (null when it pins no core)
+//   specSafe     gate 1: the spec is a shape the core writes itself (parseSpec)
+//   landed       gate 2: the pin is byte-identical to a landed ref's (pinLanded)
+//   env          process env (the re-run guard)
+function planCoreSync({ runningPkg, root, pinned, specSafe = false, landed = false, env = process.env }) {
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return { action: 'none', reason: 'not-installed-core' };
+  if (!root) return { action: 'none', reason: 'no-git' };
+  if (!pinned) return { action: 'none', reason: 'no-pin' };
+  const running = runningPkg.version || null;
+  if (running === pinned) return { action: 'none', reason: 'in-sync', running, pinned };
+  if (env && env[SYNCED_ENV]) return { action: 'refuse', reason: 'still-mismatched', running, pinned, root };
+  if (!specSafe) return { action: 'refuse', reason: 'unrecognised-spec', running, pinned, root };
+  if (!landed) return { action: 'refuse', reason: 'pin-not-landed', running, pinned, root };
+  return { action: 'sync', reason: 'mismatch', running, pinned, root };
+}
+
+function installArgs(hasLock) {
+  return [hasLock ? 'ci' : 'install', '--ignore-scripts', '--no-audit', '--no-fund'];
+}
+
+// npm's own JS entry beside this node (Windows: <dir>/node_modules/npm; POSIX:
+// <prefix>/lib/node_modules/npm), so the install needs no shell. null when absent.
+function npmCliPath(execPath = process.execPath, fsImpl = fs) {
+  const dir = path.dirname(execPath);
+  const candidates = [
+    path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+    path.join(dir, '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  ];
+  return candidates.find((c) => fsImpl.existsSync(c)) || null;
+}
+
+function remedyLine({ root, pinned, running, hasLock = true }) {
+  return `bongos: this checkout pins core ${pinned} but ${running || 'another version'} is running. ` +
+    `Run \`npm ${hasLock ? 'ci' : 'install'}\` in ${root}, then run the command again.`;
+}
+
+// Remove a node_modules LINK without following it — the same move as worktree.js's
+// unlinkNodeModulesLink, kept here rather than required: bin/bongos.js is in the
+// executed closure (tests/executed_closure.mjs), and worktree.js would pull its
+// computed require in with it. unlink takes a symlink and (via libuv) a junction; a
+// Windows reparse point unlink refuses falls back to rmdir, which removes the link only.
+function unlinkLink(linkPath, { platform = process.platform, fsImpl = fs } = {}) {
+  if (!fsImpl.lstatSync(linkPath).isSymbolicLink()) throw new Error(`${linkPath} is not a link`);
+  try { fsImpl.unlinkSync(linkPath); } catch (e) {
+    if (platform !== 'win32' || (e.code !== 'EPERM' && e.code !== 'EISDIR')) throw e;
+    fsImpl.rmdirSync(linkPath);
+  }
+}
+
+// Install the pinned core into `root` and re-run the same bongos command under it.
+// Returns the exit code to use.
+function syncAndRerun(plan, { argv, run = spawnSync, fsImpl = fs, log = (s) => process.stderr.write(s + '\n'), env = process.env, platform = process.platform, npmCli = npmCliPath(process.execPath, fsImpl) } = {}) {
+  const { root, pinned, running } = plan;
+  const hasLock = fsImpl.existsSync(path.join(root, 'package-lock.json'));
+  const remedy = () => log(remedyLine({ root, pinned, running, hasLock }));
+  log(`bongos: this checkout pins core ${pinned}, but ${running} is running — installing ${pinned} here first.`);
+  const nm = path.join(root, 'node_modules');
+  let st = null;
+  try { st = fsImpl.lstatSync(nm); } catch { /* absent */ }
+  if (st && st.isSymbolicLink()) {
+    try { unlinkLink(nm, { platform, fsImpl }); } catch (e) {
+      log(`bongos: could not detach the shared node_modules link (${e.message}).`);
+      remedy();
+      return 1;
+    }
+  }
+  // npm's JS entry under this node — no shell. Fallback: `npm`, which on win32 is
+  // npm.cmd and needs a shell (Node refuses a .cmd without one); the args are fixed
+  // strings, never branch data.
+  const cli = npmCli;
+  const inst = cli
+    ? run(process.execPath, [cli, ...installArgs(hasLock)], { cwd: root, stdio: 'inherit', env })
+    : run('npm', installArgs(hasLock), { cwd: root, stdio: 'inherit', env, ...(platform === 'win32' ? { shell: true } : {}) });
+  if (!inst || inst.error || inst.status !== 0) {
+    log(`bongos: installing core ${pinned} failed.`);
+    remedy();
+    return 1;
+  }
+  const bin = path.join(nm, '@bongos', 'core', 'bin', 'bongos.js');
+  if (!fsImpl.existsSync(bin)) { remedy(); return 1; }
+  const res = run(process.execPath, [bin, ...argv.slice(2)], { stdio: 'inherit', env: { ...env, [SYNCED_ENV]: '1' } });
+  if (!res || res.error) return 1;
+  return res.status == null ? 1 : res.status;
+}
+
+// The dispatcher's one call. Returns an exit code when it handled the command (synced
+// and re-ran, or refused), or null to run the verb on the current core.
+function ensurePinnedCore({ coreRoot, argv, cwd = process.cwd(), env = process.env, run = spawnSync, fsImpl = fs, log } = {}) {
+  if (env && env.BONGOS_SKIP_CORE_SYNC) return null;
+  const runningPkg = readJson(path.join(coreRoot, 'package.json'), fsImpl);
+  if (!runningPkg || runningPkg.name !== CORE_PKG) return null; // fast path: the core repo itself
+  const root = gitTopLevel(cwd, run);
+  const pinned = root ? pinnedCoreVersion(root, fsImpl) : null;
+  const specSafe = root ? parseSpec(coreSpec(root, fsImpl)).safe : false;
+  const out = { runningPkg, root, pinned, specSafe, env };
+  // gate 2 costs git spawns — only pay it when there is a mismatch to act on
+  const pre = planCoreSync({ ...out, landed: true });
+  const plan = pre.action === 'sync' ? planCoreSync({ ...out, landed: pinLanded(root, { run, fsImpl }) }) : pre;
+  if (plan.action === 'none') return null;
+  const say = log || ((s) => process.stderr.write(s + '\n'));
+  if (plan.action === 'refuse') {
+    say(remedyLine({ ...plan, hasLock: fsImpl.existsSync(path.join(root, 'package-lock.json')) }));
+    return 1;
+  }
+  return syncAndRerun(plan, { argv, run, fsImpl, log: say, env });
+}
+
+module.exports = { CORE_PKG, SYNCED_ENV, LANDED_REFS, pinLanded, npmCliPath, parseSpec, versionFromSpec, installArgs, pinnedCoreVersion, planCoreSync, remedyLine, syncAndRerun, ensurePinnedCore };

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.124'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.125'; // 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/core_pin_sync.mjs

@@ -0,0 +1,237 @@
+// tests/core_pin_sync.mjs — `bongos <verb>` runs the core the checkout pins (task 1004632)
+//
+// The bug: an instance's task worktree has no node_modules of its own, so after a
+// core-update task lands the next task's `bongos ship` resolved the MAIN checkout's
+// older core and failed on a bug the new pin had already fixed. These cases pin the
+// decision (planCoreSync), the pin reader, and the install-then-re-run path with an
+// injected runner — no npm, no network. The last case is end to end on a real temp
+// git repo with a fake installed core.
+//
+// Run:  node tests/core_pin_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const sync = require('../scripts/gds/core-pin-sync.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.stack || err.message}`); }
+}
+
+const CORE = { name: '@bongos/core', version: '1.21.20' };
+
+test('versionFromSpec reads a vendored tarball and a registry semver', () => {
+  assert.equal(sync.versionFromSpec('file:vendor/bongos-core-1.21.71.tgz'), '1.21.71');
+  assert.equal(sync.versionFromSpec('^1.21.71'), '1.21.71');
+  assert.equal(sync.versionFromSpec('1.21.71'), '1.21.71');
+  assert.equal(sync.versionFromSpec('file:../somewhere'), null);
+  assert.equal(sync.versionFromSpec(undefined), null);
+});
+
+test('parseSpec: only the shapes the core writes itself are safe to auto-install', () => {
+  assert.equal(sync.parseSpec('file:vendor/bongos-core-1.21.71.tgz').safe, true);
+  assert.equal(sync.parseSpec('1.21.71').safe, true);
+  assert.equal(sync.parseSpec('^1.21.71').safe, false, 'a range is not an exact pin');
+  assert.equal(sync.parseSpec('file:../evil/bongos-core-1.21.71.tgz').safe, false);
+  assert.equal(sync.parseSpec('git+https://x/y.git').safe, false);
+});
+
+test('planCoreSync: a pin that has not landed on main refuses — a branch cannot choose what gets installed', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '9.9.9', specSafe: true, landed: false, env: {} });
+  assert.equal(p.action, 'refuse');
+  assert.equal(p.reason, 'pin-not-landed');
+});
+
+test('planCoreSync: an unrecognised spec refuses with the remedy, never installs', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', specSafe: false, env: {} });
+  assert.equal(p.action, 'refuse');
+});
+
+test('installArgs: never runs install scripts; ci with a lockfile, install without', () => {
+  assert.deepEqual(sync.installArgs(true).slice(0, 2), ['ci', '--ignore-scripts']);
+  assert.deepEqual(sync.installArgs(false).slice(0, 2), ['install', '--ignore-scripts']);
+});
+
+test('planCoreSync: the core repo itself is never touched', () => {
+  const p = sync.planCoreSync({ runningPkg: { name: 'cloud-bongos', version: '0.0.2' }, root: '/r', pinned: '1.21.71', env: {} });
+  assert.equal(p.action, 'none');
+});
+
+test('planCoreSync: in sync, no git, no pin → carry on', () => {
+  assert.equal(sync.planCoreSync({ runningPkg: { ...CORE, version: '1.21.71' }, root: '/r', pinned: '1.21.71', env: {} }).action, 'none');
+  assert.equal(sync.planCoreSync({ runningPkg: CORE, root: null, pinned: '1.21.71', env: {} }).action, 'none');
+  assert.equal(sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: null, env: {} }).action, 'none');
+});
+
+test('planCoreSync: the task-49 shape (pinned 1.21.71, running 1.21.20) syncs', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', specSafe: true, landed: true, env: {} });
+  assert.equal(p.action, 'sync');
+  assert.equal(p.pinned, '1.21.71');
+  assert.equal(p.running, '1.21.20');
+});
+
+test('planCoreSync: a re-run that is STILL mismatched refuses instead of looping', () => {
+  const p = sync.planCoreSync({ runningPkg: CORE, root: '/r', pinned: '1.21.71', env: { [sync.SYNCED_ENV]: '1' } });
+  assert.equal(p.action, 'refuse');
+  assert.match(sync.remedyLine(p), /npm ci/);
+});
+
+function tmpCheckout({ pinSpec, lockVersion }) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-sync-'));
+  fs.writeFileSync(path.join(dir, 'package.json'), '' + JSON.stringify({ name: 'inst', dependencies: { '@bongos/core': pinSpec } }));
+  if (lockVersion) {
+    fs.writeFileSync(path.join(dir, 'package-lock.json'), JSON.stringify({ packages: { 'node_modules/@bongos/core': { version: lockVersion } } }));
+  }
+  return dir;
+}
+
+test('pinnedCoreVersion prefers the lockfile, falls back to package.json (BOM tolerated)', () => {
+  const a = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.72' });
+  assert.equal(sync.pinnedCoreVersion(a), '1.21.72');
+  const b = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz' });
+  assert.equal(fs.readFileSync(path.join(b, 'package.json'), 'utf8').charCodeAt(0), 0xFEFF, 'fixture really carries a BOM');
+  assert.equal(sync.pinnedCoreVersion(b), '1.21.71');
+});
+
+test('syncAndRerun: npm ci in the checkout, then re-run the same argv under its own core with the loop guard', () => {
+  const root = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.71' });
+  const calls = [];
+  const run = (cmd, args, opts) => {
+    calls.push({ cmd, args, opts });
+    if (cmd === 'npm') {
+      const d = path.join(root, 'node_modules', '@bongos', 'core', 'bin');
+      fs.mkdirSync(d, { recursive: true });
+      fs.writeFileSync(path.join(d, 'bongos.js'), '');
+      return { status: 0 };
+    }
+    return { status: 7 };
+  };
+  const code = sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship', '49'], run, log: () => {}, env: {}, platform: 'linux', npmCli: null });
+  assert.equal(code, 7, 'the re-run exit code is passed through');
+  assert.equal(calls[0].cmd, 'npm');
+  assert.equal(calls[0].args[0], 'ci');
+  assert.equal(path.resolve(calls[0].opts.cwd), path.resolve(root));
+  assert.equal(calls[1].cmd, process.execPath);
+  assert.deepEqual(calls[1].args.slice(1), ['ship', '49']);
+  assert.ok(calls[1].args[0].includes(path.join('node_modules', '@bongos', 'core', 'bin', 'bongos.js')));
+  assert.equal(calls[1].opts.env[sync.SYNCED_ENV], '1');
+});
+
+test('syncAndRerun: a failed install exits 1 with the one-line remedy, and never re-runs', () => {
+  const root = tmpCheckout({ pinSpec: '1.21.71' });
+  const logs = [];
+  const calls = [];
+  const run = (cmd, args) => { calls.push(cmd); return { status: 1 }; };
+  const code = sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship'], run, log: (s) => logs.push(s), env: {}, platform: 'linux', npmCli: null });
+  assert.equal(code, 1);
+  assert.deepEqual(calls, ['npm']);
+  assert.equal(calls.length, 1);
+  assert.ok(logs.some((l) => /Run `npm install` in /.test(l)), 'no lockfile → remedy names npm install: ' + logs.join('\n'));
+});
+
+test('syncAndRerun: a node_modules LINK is detached first, never installed through', () => {
+  const root = tmpCheckout({ pinSpec: '1.21.71', lockVersion: '1.21.71' });
+  const shared = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-shared-'));
+  fs.writeFileSync(path.join(shared, 'keep.txt'), 'shared');
+  fs.symlinkSync(shared, path.join(root, 'node_modules'), 'junction');
+  const run = (cmd) => {
+    if (cmd === 'npm') {
+      assert.ok(!fs.existsSync(path.join(root, 'node_modules')), 'link must be gone before npm runs');
+      return { status: 1 };
+    }
+    return { status: 0 };
+  };
+  sync.syncAndRerun({ root, pinned: '1.21.71', running: '1.21.20' }, { argv: ['node', 'bongos', 'ship'], run, log: () => {}, env: {}, npmCli: null });
+  assert.equal(fs.readFileSync(path.join(shared, 'keep.txt'), 'utf8'), 'shared', 'the shared install is untouched');
+});
+
+function git(cwd, ...args) {
+  const r = spawnSync('git', ['-c', 'user.email=t@t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...args], { cwd, encoding: 'utf8' });
+  assert.equal(r.status, 0, r.stderr);
+  return r.stdout;
+}
+
+// A real repo: main carries the 1.21.71 pin (the core update landed); the checkout is
+// on a task branch. The running core is the older 1.21.20.
+function landedRepo() {
+  const root = tmpCheckout({ pinSpec: 'file:vendor/bongos-core-1.21.71.tgz', lockVersion: '1.21.71' });
+  fs.mkdirSync(path.join(root, 'vendor'));
+  fs.writeFileSync(path.join(root, 'vendor', 'bongos-core-1.21.71.tgz'), 'tarball-bytes');
+  git(root, 'init', '-q', '-b', 'main');
+  git(root, 'add', '-A');
+  git(root, 'commit', '-qm', 'pin 1.21.71');
+  git(root, 'checkout', '-qb', 'task-49');
+  const coreRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'core-pin-running-'));
+  fs.writeFileSync(path.join(coreRoot, 'package.json'), JSON.stringify(CORE));
+  const installs = [];
+  const run = (cmd, args, opts) => {
+    if (cmd === 'git') return spawnSync(cmd, args, opts);
+    if (cmd === 'npm' || String(args[0] || '').endsWith('npm-cli.js')) installs.push(args);
+    return { status: 1 };
+  };
+  return { root, coreRoot, installs, run };
+}
+
+test('ensurePinnedCore end to end: a pin that LANDED on main gets installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  assert.equal(sync.pinLanded(root, { run }), true);
+  const code = sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} });
+  assert.equal(code, 1, 'the fake install fails, so the remedy exit');
+  assert.equal(installs.length, 1, 'npm ran once');
+  // in sync → null (carry on), no install
+  fs.writeFileSync(path.join(coreRoot, 'package.json'), JSON.stringify({ ...CORE, version: '1.21.71' }));
+  installs.length = 0;
+  assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), null);
+  assert.equal(installs.length, 0);
+});
+
+test('ensurePinnedCore end to end: a branch-swapped tarball (committed or not) is refused, never installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  fs.writeFileSync(path.join(root, 'vendor', 'bongos-core-1.21.71.tgz'), 'attacker-bytes');
+  assert.equal(sync.pinLanded(root, { run }), false, 'uncommitted swap');
+  git(root, 'commit', '-qam', 'swap');
+  assert.equal(sync.pinLanded(root, { run }), false, 'committed on the branch only');
+  const logs = [];
+  const code = sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: (l) => logs.push(l) });
+  assert.equal(code, 1);
+  assert.equal(installs.length, 0);
+  assert.ok(logs.some((l) => /Run `npm ci`/.test(l)), logs.join('\n'));
+});
+
+test('ensurePinnedCore end to end: a branch-only version bump is refused, never installed', () => {
+  const { root, coreRoot, installs, run } = landedRepo();
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ name: 'inst', dependencies: { '@bongos/core': '9.9.9' } }));
+  fs.rmSync(path.join(root, 'package-lock.json'));
+  git(root, 'commit', '-qam', 'bump');
+  assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), 1);
+  assert.equal(installs.length, 0);
+});
+
+test('ensurePinnedCore end to end: deleting the lockfile or adding an .npmrc on the branch is refused', () => {
+  for (const tamper of [
+    (root) => fs.rmSync(path.join(root, 'package-lock.json')),
+    (root) => fs.writeFileSync(path.join(root, '.npmrc'), 'registry=https://evil.example/\n'),
+  ]) {
+    const { root, coreRoot, installs, run } = landedRepo();
+    tamper(root);
+    assert.equal(sync.pinLanded(root, { run }), false);
+    assert.equal(sync.ensurePinnedCore({ coreRoot, argv: ['node', 'bongos', 'ship'], cwd: root, env: {}, run, log: () => {} }), 1);
+    assert.equal(installs.length, 0);
+  }
+});
+
+test('the dispatcher runs the check for ship only', () => {
+  const src = fs.readFileSync(new URL('../bin/bongos.js', import.meta.url), 'utf8');
+  assert.match(src, /if \(!COMPILED && verb === 'ship'\) \{\s*const synced = require\('\.\.\/scripts\/gds\/core-pin-sync\.js'\)\.ensurePinnedCore/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/howto_guide.mjs

@@ -0,0 +1,96 @@
+// tests/howto_guide.mjs — the in-session how-to guide's shape + plain-language rule (task 1004627)
+//
+// The guide's step ids are stored as per-person read marks (task 1004634) and matched to
+// moments (task 1004635), so they must be unique, stable-shaped, and every step must
+// belong to a known moment and carry all three parts (what / when / try). It is written
+// for people who may not be technical, so no step may use the accessibility scorer's
+// jargon list (the same list tests/plain_cards.mjs holds the failure cards to).
+//
+// Run:  node tests/howto_guide.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const guide = require('../modules/onboarding/howto-guide.js');
+const { JARGON_TERMS } = require('../modules/sessions/accessibility.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+test('about 25 steps, each with a unique snake_case id', () => {
+  assert.ok(guide.STEPS.length >= 20 && guide.STEPS.length <= 32, `got ${guide.STEPS.length}`);
+  const ids = guide.STEPS.map((s) => s.id);
+  assert.equal(new Set(ids).size, ids.length, 'duplicate step id');
+  for (const id of ids) assert.match(id, /^[a-z][a-z0-9_]{2,39}$/, id);
+});
+
+test('every step has a known moment and all three parts', () => {
+  for (const s of guide.STEPS) {
+    assert.ok(guide.MOMENT_IDS.has(s.moment), `${s.id}: unknown moment ${s.moment}`);
+    for (const f of ['title', 'what', 'when', 'try']) assert.ok(String(s[f] || '').trim().length > 5, `${s.id}.${f} empty`);
+  }
+});
+
+test('every moment has at least one step and a trigger', () => {
+  for (const m of guide.MOMENTS) {
+    assert.ok(guide.stepsForMoment(m.id).length > 0, `${m.id} has no steps`);
+    assert.ok(m.trigger, `${m.id} has no trigger`);
+  }
+});
+
+test('the moments the owner named are covered', () => {
+  for (const m of ['first_open', 'setup', 'goal', 'task', 'find_work', 'first_ship', 'invite', 'settings']) {
+    assert.ok(guide.MOMENT_IDS.has(m), m);
+  }
+  assert.ok(guide.stepById('where_to_start'), 'the "where to start" step exists');
+  assert.ok(guide.stepById('ship_mode'), 'settings covers the ship mode');
+});
+
+test('steps are short and in plain language (no jargon)', () => {
+  const hits = [];
+  for (const s of guide.STEPS) {
+    for (const f of ['title', 'what', 'when', 'try']) {
+      const text = s[f];
+      if (f !== 'try') assert.ok(text.length <= 240, `${s.id}.${f} is ${text.length} chars — keep a step short`);
+      for (const term of JARGON_TERMS) {
+        const re = new RegExp(`(^|[^A-Za-z])${term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([^A-Za-z]|$)`, /^[A-Z+-]+$/.test(term) ? '' : 'i');
+        if (re.test(text)) hits.push(`${s.id}.${f}: "${term}"`);
+      }
+    }
+  }
+  assert.deepEqual(hits, []);
+});
+
+test('every slash command a step names is a core skill an instance gets', async () => {
+  const fs = await import('node:fs');
+  const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+  for (const s of guide.STEPS) {
+    for (const m of s.try.matchAll(/\/([a-z][a-z-]+)/g)) {
+      const skill = `.claude/skills/${m[1]}/SKILL.md`;
+      assert.ok(fs.existsSync(new URL(`../${skill}`, import.meta.url)), `${s.id}: /${m[1]} is not a skill`);
+      assert.ok(isPublishable(skill), `${s.id}: /${m[1]} does not ship to an instance`);
+    }
+  }
+});
+
+test('nextUnread walks the guide in order and ends at null', () => {
+  assert.equal(guide.nextUnread([]).id, guide.STEPS[0].id);
+  assert.equal(guide.nextUnread([guide.STEPS[0].id]).id, guide.STEPS[1].id);
+  assert.equal(guide.nextUnread(guide.STEPS.map((s) => s.id)), null);
+});
+
+test('formatGuide renders every step, and one moment on request', () => {
+  const all = guide.formatGuide();
+  for (const s of guide.STEPS) assert.ok(all.includes(`[${s.id}]`), s.id);
+  const one = guide.formatGuide({ moment: 'first_ship' });
+  assert.ok(one.includes('[what_ship_does]'));
+  assert.ok(!one.includes('[welcome]'));
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);