@bongos/core 1.21.123 → 1.21.125

package/release-notes.json

@@ -9720,5 +9720,21 @@
       "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"
     }
+  ],
+  "1.21.124": [
+    {
+      "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.123'; // 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);